Re: [groff] 01/28: groff(7): Rename "pilot" list macros.

[Ingo Schwarze]

Hi Branden,

sorry for missing this earlier...

G. Branden Robinson wrote on Wed, May 25, 2022 at 10:43:20PM -0400:

> man/groff.7.man
[...]
> .\" begin list [piloting a possible extension to man(7)]
> .de LS
> .  nr saved-PD \\n[PD]
> .  nr PD 0
> ..
> .
> .\" end list [piloting a possible extension to man(7)]
> .de EL
> .de LE
> .  nr PD \\n[saved-PD]
> ..

This is a striking example of something that must absolutely *not*
be added as a groff extension to the man(7) language because it
spectacularly fails the usefulness test.

This extension provides no benefit whatsoever.
A portable way to achieve the same result already exists
and isn't even ugly, cumbersome, or fragile:
Instead of .LS, write ".PD 0".
Instead of .LE, write ".PD".

The guarding against already set .PD is completely pointless
because it is bad style for a manual page to use .PD with any
argument other than 0.  And even if an author (questionably)
did use .PD, they know they did and can adjust the .PD at the
end accordingly.

If an extension is completely useless, it is not an attenuating
circumstance if the damage done by using the extension on a man(7)
implementation not supporting it causes only minor damage.
In this case, if a manual page author uses .LS/.LE and the
formatter does not support it, then only the spacing will be
wrong, the content of the manual page will not be damaged.

Then again, why risk even minor damage when there is no benefit
whatsoever?

There is also a minor design problem with your implementation
in so far as it does support nesting lists to two levels, but
not to three levels, or not even to two levels if the author
manually used .PD before, and when it fails, it fails silently
and in a confusing way (leaving .PD 0 in effect after the end
of the last list).  There would be no way to reasonably document
such ill-designed behaviour short of saying ".LS does not nest
and cannot be used when .PD is in effect", and if it were documented
that way, then again the register really isn't needed.
But this design problem doesn't really matter given that the whole
thing is a very bad idea in the first place.


That said, the groff(7) manual page clearly needs cleanup.
Defining more than 20 macros at the beginning can be interpreted in
two (not necessarily mutually exclusive) ways: it might indicate
extreme lazyness and poor style in setting up the page, and/or
it might indicate that the man(7) language is not well-suited for
practical work.  I tend to think the former is closer to the truth
because even though i (personally) consider the man(7) language
obsolete and technically outdated (which we disagree on), we do agree
that the man(7) language *can* be used properly for modern documentation.

Yours,
  Ingo