Re: [groff] 01/04: grn(1): Make options discussion a section.

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Mon, Nov 12, 2018 at 11:31:42AM -0500:

> If we ignore Michael Kerrisk et al., _no_ section of a man(7) page
> is standard.

>From about 1970 to about 1985, i consider the list of sections used
in Bell Labs manual pages standard.  From about 1995 onwards, the
closest thing to a standard is what is documented in the groff
distribution - specifically, in the file groff_mdoc(7) which Werner
Lemberg diligently maintained over the years (initially called
groff_mdoc.samples(7)).  Admittedly, the groff_man(7) manual does
not contain a copy of the "MANUAL PAGE TEMPLATE" - but why should
it?  There is no need for duplicate information in the groff
distribution.

While the work of Michael Kerrisk is to be highly commended - without
the Linux man pages project, the state of manual pages in the GNU/Linux
world would be even worse - only part of what man-pages(7) says is
good advice.  Other parts diverge from earlier, perfectly viable
practice.

If BSD pages and the Linux man pages project agree on a particular
point, that's a strong hint that it should probably be followed.
If they disagree, the point has to be considered for technical
merit, and that is where OPTIONS falls short for the reasons
discussed.

[...]
> I regard the Austin Group as worthy of consideration as the Bell
> Labs CSRC.  Why shouldn't I?

Because design by Thompson, Kernighan, Richie, Ossanna, and McIlroy
is invariably better than design by committee?  In particular when
it comes to clarity and conciseness, which are key to documentation?

Besides, that statement is somewhat unfair with respect to the
Austin Group.  They are not even trying to write documentation, but
a standard, and the quality criteria for a standard do not coincide
with the quality criteria for documentation, not even technical
reference documentation.  A standard ought to value formal exactness
above all else even though that can never be fully attained, even
at the expense of simplicity, while documentation should avoid being
pedantic, as Doug rightfully emphasized.

> We can keep this discussion better focused if you will decide whether
> you want to argue from standards or from common practice, taste, and
> judgment.

>From a healthy balance of all of them.  Yes, balancing them cannot
be formalized but requires judgement.

The more the existing (informal, scattered) standards agree, and the
more common practice agrees on a given point, the more caution should
be employed changing it; the more they diverge, the more judgement
matters to figure out which way best serves clarity, simplicity,
and conciseness.

> Rolling back to the state of the groff tree before I made any
> commits at all, I find that 32 of the 61 man page sources have
> "OPTIONS" sections.  Of what precedential value is that?

It shows that groff documentation wasn't consistent in this respect,
nothing more, nothing less.

Yours,
  Ingo