Re: [groff] man-page fixes

[Ingo Schwarze]

Hi Doug,

Doug McIlroy wrote on Thu, Nov 15, 2018 at 08:40:14PM -0500:

> Regardless of standards considerations, if there's any advice
> that needs to be hammered into man authors, it's to be concise
> and accurate, but not pedantic. As Will Strunk commanded,
> "Omit needless words."

That is remarkably close to how Jason McIntyre is maintaining
our tree, and it is indeed very useful guidance.

[...]
> As editor for v7-v10, I would not offer v7 as a canonical
> model. It owed its use of boldface in SYNOPIS to the limited
> number of fonts (Typically R,F,I,S) that could be on our
> typesetter at the same time. For v9 we were able to follow
> Kernighan and adopt a distinct literals font (L, which happened
> to be Courier but could have been identified with bold had we
> wished). I still think this is the best choice.

For typeset output, such limitations certainly no longer exist.
For terminal output, however, default roman font and monospaced
("literal") font are still indistinguishable, so moving the markup
of command names, function names, keywords, option letters and the
like from bold to literal still isn't a viable option for manual
pages.  Even though you explain the convention was accidental in
origin, maybe changing it now is no longer all that desirable -
having been used in Unix manual page SYNOPSIS sections for at least
45 years and in BSD manual pages consistently in all sections for
more than 25 years, people are likely to be somewhat used to it by
now.

[...]
> For nagging reasons of verbal continuity, the options displays
> were prefaced by *needless words* like, "The following options
> are recognized". A simple OPTIONS heading would be better.
> 
> Unfortunately, an OPTIONS heading would intrude between the
> basic description and less important details that follow
> the options. (I don't agree that it would come too closely
> after DESCRIPTION; a majority of man pages already have even
> shorter sections.)

That is admittedly the weaker part of my argument.

> OPTIONS could be moved to the end of
> DESCRIPTION. However, options may well be the biggest reason
> for quick peeks at man pages; they should be easy to spot. It
> has reasonably been suggested that OPTIONS should be a .SS
> subsection.  That might be followed by .SS DETAILS.

As a matter of fact, the output from ".SS Options" would be the
same number of lines as the conventional wording "The options are
as follows:" used in BSD manual pages.  And in many cases, you are
right that it would force the author to insert another header line
(saying nothing of substance) after the options, where currently
nothing is required.

So your proposal would entail:

 - one *more* line of boilerplate in a typical manual page
 - reduction of the number of boilerplate words in a typical
   manual page by 5 - 2x1 = 3: that isn't very much, i think
 - editing on the order of a thousand existing section 1 and 8
   manual pages per operating system

With all due respect, and while i appreciate most of your other
points, i doubt that i would want to head into that particular
direction.

Yours,
  Ingo