Hi Alex, Alejandro Colomar (man-pages) wrote on Sat, Mar 19, 2022 at 05:07:09PM +0100:
> While fixing style issues in the man-pages project, > I'm finding a few recurrent issues that I think you could warn about: > > Unnecessary quotations: > > [ > .I "foo bar" > .IR foo "bar" > ] In how far are these even problematic? As far as i'm aware, these superfluous quotes neither harm portability nor readability for humans maintaining the manual page. > Unnecessary escape \f: > > [ > foo \fIbar\fP baz > ] > > The last one is more difficult to decide when it's unnecessary, but you > could maybe start with non-formatted lines. When designing a warning, whether it finds some instances of code that permit some stylistic improvement is not the only aspect to consider. One should also make sure that the warning is not excessively noisy and does not cause false positives. Regarding your first suggestion, the quotes are for example not optional in the following code: .Ft int .Fo main .Fa "int argc" .Fa "char *argv[]" .Fc So whether the warning makes sense or is a false positive will depend on the individual macro in question, making the implementation relatively complex for little gain, in particular given that i'm not sure this even is a significant style issue. Regarding your second example, yes, writing foo .I bar baz would be a stylistic improvement, but adding such a warning would cause a deluge of noise when processing the output of (even high-quality) automatical man(7) code generators because using font escape sequences is extremely widespread among man(7) code generators because that is a highly reliable and portable method of choosing fonts, even though it looks a bit awkward to the human eye, whereas automatic generation of font macros and font alternating macros is a very complicated and error-prone task that most (even high-quality) man(7) code generators do not attempt. To summarize, i certainly wouldn't want to warn about these mini-issues in mandoc -T lint. Admittedly, warnings in groff accept a significantly higher rate of noise and false positives than in mandoc -T lint, but i'm not really sure about the tradeoff of noise vs. usefulness for these two even in groff. Yours, Ingo
