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

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Tue, Nov 06, 2018 at 01:57:41PM -0500:

> commit 75205acd4f5c7586199e7b19fa61971fd3b31e19
> Author: G. Branden Robinson <address@hidden>
> Date:   Tue Nov 6 12:43:12 2018 -0500
> 
>     grn(1): Make options discussion a section.
>     
>       * src/preproc/grn/grn.1.man: The man page discusses command-line
>       options, so give them the standard section for them.

While i very much appreciate your extensive work on groff documentation,
i strongly disagree on this particular point.

OPTIONS is not a standard section, not at all:

  $ man -a mdoc man groff_mdoc groff_man | grep OPTIONS
  $ 

That means none of the official specifications of the mdoc(7) and man(7)
languages recommends a section by that name, neither in mandoc nor in
groff.

Using a custom section of that name in a manual page is useless,
distracting, and very poor style.

For a command line program (sections 1, 6, and 8), the list of options
is the meat of the DESCRIPTION section.  Is has to begin near the top
of the DESCRPTION and should only be preceded by a very small amount
of text saying what the basic purpose of the program is and what it
does when called without options.  The reason for that basic rule
is to keep documentation concise such that users quickly find the
relevant information.  As a matter of fact, grn(1) gets that
introductory paragraph about right.

Using an OPTIONS section is useless because it implies that the
DESCRIPTION section before it becomes ridiculously short.  It is
distracting because the word "OPTIONS" merely rehashes the obvious,
violates reader expectations because it is non-standard, and wastes
space for no reason.  It is poor style because it causes a structural
problem.  It is not unusual that the DESCRIPTION in a manual page
needs to provide additional information supplementing the initial
paragraph and the options list; such informations does belong in
the DESCRIPTION, but after the options.  Look at
  https://man.openbsd.org/mkdir.1
  https://man.openbsd.org/chmod.1
  https://man.openbsd.org/date.1
  https://man.openbsd.org/rm.1
  https://man.openbsd.org/cp.1
for elementary examples; there are countless others.  With a separate
OPTIONS section, you no longer have any place for putting such
information, and you only have very poor options to work around
that fundamental problem: either you move such relatively less
important information above the options, seriously misplacing it
and making it harder for the reader to get to the relevant options,
which are almost almost more important than such auxiliary information;
or you invent yet another non-standard section, which in many cases
will also be ridiculously short, causing more distraction.  Besides,
all this is trouble is also needless because even without the OPTIONS
header, the DESCRIPTION text before and after the options list
almost always looks different enough from the list that no further
visiual distinction is needed.

> Relocate the notice about optional whitespace to the top of the section.

Please delete such sentences outright, they are totally pointless:
the SYNOPSIS already makes that clear, and POSIX strongly recommends
it in general.  Only if an option taking an argument does *not*
allow whitespace before the argument (violating the general POSIX
recommendation), that must be mentioned, but not the other way
round.  Restating the obviouds merely harms conciseness, and right
at the top of a page is the worst place to put fluff.

> Also consistently double-quote multi-word arguments to the .SH
> macro, for consistency with the rest of the page and (most)
> other groff man pages.

That's both useless and harmless - in a word, cargo cult.

Yours,
  Ingo