Re: Warn on semantic newlines

[Alejandro Colomar]

(I reorganized some parts for convenience in the answers)

Hi Ingo,

On 6/16/22 21:08, Ingo Schwarze wrote:
> > As far as I know, there's currently no tool that warns on "foo. bar"
> > in filled test.  Not `mandoc -Tlint`,
>
> That's not entirely accurate.
[...]
> The mandoc(1) program warns if all of the following conditions hold:
>
>   1. The input file uses the mdoc(7) language.

Yup, that disables it for me :(

>      The rationale for doing this for mdoc(7) only and not for man(7)
>      is that the average markup quality for real-world man(7) pages
>      is so much below the markup quality of average real-world mdoc(7)
>      pages that warning about this detail would not really be helpful
>      in man(7) but rather amount to even more noise.
>      When you run mandoc -T lint on some run-of-the mill man(7) page
>      found in the wild, you typically already get buried under a deluge
>      of warnings and errors, usually including several rather serious
>      ones.  Adding even more that are of little importance seems
>      unwise to me while that situation persists.
[...]


> > Also, as far as I know, neither of -ww nor -Tlint have something
> > equivalent to -Wno-switch (or -Wno-error=switch), which could be
> > nice to silence (or make non-fatal) some warnings on purpose.
>
> For mandoc(1), you are the first person asking for that, and i don't
> remember having seen such a request for groff(1) either.

Well, that would allow implementing the warning above for man(7), such 
that quality pages (I try to improve the quality of the pages I 
maintain, maybe even too excessively, but I hope it's a net win in the 
end) can use it, and pages that are still catching up or simply don't 
care to such extremes can live without the noise.

Makes sense?

> > Do you think that could be implemented in groff(1) or mandoc(1)?
>
> I dislike the suggested feature for several reasons.

[...]

> Even with tools where excessive configurability is common,
> like with C compilers, the consequences are invariably unpleasant.
> Rather than striving to keep false positives down, compiler
> developers usually take the existing, excessive configurability
> as an excuse for adding warnings that cause high rates of false
> positives, offering the flimsy pretext "if the noise bothers
> you, just switch it off."  The end result of this kind of laziness
> at the design stage is that instead of having sane defaults, next
> to everybody has to configure and maintain their own set of exceptions,
> including those people who never asked for that, which is the
> overwhelming majority.

My approach with C compilers and static analyzers is the following:

Turn on the minimum set of warnings (e.g., -Wall), and try to get it to 
0 warnings.  There may be a few false positives, so turn off those 
warnings with -Wno-whatever.

When I have 0 warnings, I go to the next level (e.g., -Wextra), and 
repeat the steps until 0 warnings.

And keep increasing the warning level of the tool until I reach a level 
that -Wno-* would be insane (e.g., -Weverything), and then go back and 
remove -Weverything (or maybe the tool isn't too noisy at the highest 
level, so I can keep it.

So far, this has worked well for me, and that also helps document 
exactly what I'm ignoring

For example, for some project of mine, I have the following exceptions 
for clang-tidy(1), which more or less keep track of my coding style:

Checks: >
    *,
    -altera-id-dependent-backward-branch,
    -altera-unroll-loops,
    -bugprone-narrowing-conversions,
    -clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling,
    -concurrency-mt-unsafe,
    -cppcoreguidelines-avoid-magic-numbers,
    -cppcoreguidelines-init-variables,
    -cppcoreguidelines-narrowing-conversions,
    -google-readability-braces-around-statements,
    -hicpp-braces-around-statements,
    -llvmlibc-restrict-system-libc-headers,
    -misc-no-recursion,
    -readability-braces-around-statements,
    -readability-function-cognitive-complexity,
    -readability-isolate-declaration,
    -readability-magic-numbers,

That makes sense to me.  It helps easily show diversions from the coding 
style, apart from the bugs it finds of course.

> For mandoc -T lint, there is an additional aspect.  It is well-known
> how having a globally uniform style of manual page formatting that
> readers automatically get familiar with helps readability.
> Similarly, a globally uniform style in the source code helps
> maintainability (and in addition, also reduces the risk that a
> given page deviates from the common output style).

Partly agree, but at the same time, I don't like extremes at applying 
uniformity, such as the indentation rules in Python (or even worse: YAML).

> Gently guiding people towards such a uniform style is desirable;
> encouraging them to pick their own ruleset according to personal
> taste is not desirable, *in particular* not for those few who might
> actually consider doing that.

I understand this position, and won't push too much for such warnings, 
since I can act as the linter for the Linux man-pages, but it would be 
nice if I could offload some of my work to a tool with few false positives.

> All that said, in general, i'm open to suggestions regarding how
> to improve mandoc warnings, in particular regarding the addition of
> missing warnings and the suppression of false positives.
> But i'm not sure yet what to change following your present
> request.

No problem, I'll keep suggesting stuff.


>> The tool could have a secondary warning, not so important,
>> for "foo, bar".
>
> Absolutely not.

Makes sense.



Cheers,

Alex

--
Alejandro Colomar
<http://www.alejandro-colomar.es/>

OpenPGP_signature
Description: OpenPGP digital signature