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

[Alejandro Colomar (man-pages)]

Hi Ingo and Larry,

On 3/22/22 03:44, Larry Kollar wrote:
> Ingo Schwarze <schwarze@usta.de> wrote:

For some reason, Ingo, I still don't get your emails.
This time, not even in SPAM :(.

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

The problem is not so much in having that code,
but in that people that have never (or once or twice)
written patches for the man-pages
get very confused by the source code syntax.
Especially when our source code is quite inconsistent.

It's true that that code is _correct_ as in "it doesn't harm portability 
nor readability for humans".
But the same is true for [.IR foo], and it's warned.

In fact, it doesn't harm readability for humans would be better 
rephrased as "it doesn't harm readability for humans _that already know 
man(7)_".  Since I receive many patches from people that don't know 
man(7), *and* don't seem to have the time to learn it, *but* we need 
their patches because they are the ones who write the kernel features, 
*and* I'd like to minimize their confusion because that implicitly 
reduces the amount of work I need to do to review patches,
then having pedantic style warnings is a good thing, I think.

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

That's true.  I didn't mean to warn as in "this is wrong", but more as 
some pedantic warning that doesn't mean the page is wrong; just that it 
could be better _for some consensuated style_ (other might think that \f 
is better for them).  Kind of clang-tidy(1) or checkpatch.pl for 
man-pages, where you take the warnings you like, and turn off those you 
don't agree with them.

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

Those warnings are only triggered iff you explicitly run `make 
lint-groff`, which is only run by those who want to check the state of 
the pages regarding style.  If you don't run that, the warnings don't 
show up at all.  And I allow changing the warning level easily with 
`make lint-groff GROFF_CHECKSTYLE_LVL=1 EXTRA_GROFFFLAGS=...` so I hope 
it is useful (it is for me already), and it's not noisy to anyone else.

Cheers,

Alex

--
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/