[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Warn on semantic newlines
Re: Warn on semantic newlines
Fri, 17 Jun 2022 13:47:35 +0200
Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.10.0
(I reorganized some parts for convenience in the answers)
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.
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
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:
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
No problem, I'll keep suggesting stuff.
>> The tool could have a secondary warning, not so important,
>> for "foo, bar".
> Absolutely not.
Description: OpenPGP digital signature