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

[Larry Kollar]

Ingo Schwarze <schwarze@usta.de> wrote:
> 
> 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.

I completely agree with Ingo. The quoted argument might be expanded to
a multi-word argument in some future edit, so at worst it does no harm and
at best provides some future-proofing. I could see code generators, as Ingo
mentions, quoting each argument to avoid errors. What’s the problem?

…

> 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.

Indeed, most conversions from XML-ish grammars like DITA and HTML,
and even not XML-ish ones like Markdown, avoid a ton of not-so-corner
cases by using the \f escape in place of .I and friends. Trust me, I’ve tried
to code an XSL transform the “right” way. Trailing punctuation can drive
you insane.

I’m sure there are cases when a conversion to *roff is part of a plan to
maintain the document there, instead of a one-off PDF run, but 1) the
converted *roff doc works just fine with \f; 2) you can convert the escapes
to macros piecemeal without affecting the output.

Now, if someone wants to lint a manpage for easier maintenance, I’m all
for that. But printing warnings on the regular, for stylistic issues that don’t
affect the output? Nah.

— Larry