(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