Re: CHECKSTYLE suggestions: unnecessary quotations and unnecessary \f escape

[Ingo Schwarze]

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