[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Alejandro Colomar (man-pages)
Subject: Re: CHECKSTYLE suggestions: unnecessary quotations and unnecessary \f escape
Date: Tue, 22 Mar 2022 14:09:40 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.7.0

Hi Ingo and Larry,

On 3/22/22 03:44, Larry Kollar wrote:

Ingo Schwarze <> 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

  .I bar

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



Alejandro Colomar
Linux man-pages comaintainer;

reply via email to

[Prev in Thread] Current Thread [Next in Thread]