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

[Ralph Corderoy]

Hi Branden,

Can you try and spend time halving the amount you write, otherwise I
suspect the length puts off other contributors.  :-)

> > OPTIONS is not a standard section, not at all:

I agree with Ingo.

> In the absence of a standard, for man(7) we must look to common
> practice.
>
> On my Debian buster system I have about 2,834 packages installed,

The bulk of those may have been produced by a few systems that do it
wrong thus they have unfair weighting.  A better quality source for
man-macro usage on commands gives

    $ curl -sSg 
https://s3.amazonaws.com/plan9-bell-labs/7thEdMan/vol1/man1.bun.txt |
    > grep '^-\.SH' |
    > tr -dc 'A-Z \012' |
    > sort | uniq -c
          1 SH ADDRESSES
         70 SH BUGS
          1 SH COMMANDS
        136 SH DESCRIPTION
         42 SH DIAGNOSTICS
          1 SH EXAMPLE
          1 SH EXAMPLES
          1 SH EXPRESSIONS
         69 SH FILES
          1 SH  NAME
        135 SH NAME
        114 SH SEE ALSO
        135 SH SYNOPSIS
          1 SH VARIABLES
          2 SH WARNING
    $

> (Too late, I realized I should have been using awk...)

(I'd have first tried annotating the lines of each file with pertinent
meta-data and then grep-ing out the lines of interest, using the `stream
of data' approach.)

> Moreover, if you want to look to the practices of standards bodies,
> 175 of the 175 POSIX section 1 man pages (2013 edition) contain
> OPTIONS sections.  100%.

Not a good example since they're a standards committee and put
standardisation that above a good man page, e.g. `OPTIONS None.
OPERANDS None.  STDIN Not used.  INPUT FILES None...' for true(1p).  I
also agree with Igno that there's no need to split the option
description off from the preceding text that then becomes too short to
deserve its own DESCRIPTION section.  Something else the POSIX committee
doesn't care about.

> overlook the 248 lines of material in _other_ non-standard sections:
> .SH "GRN COMMANDS" .SH "NOTES ABOUT GROFF" .SH "GREMLIN FILE FORMAT"
> .SH "ELEMENT SPECIFICATIONS" .SH "NOTES ON COORDINATES" .SH "NOTES ON
> SUN/X11 COORDINATES"

I don't think Ingo was saying grn(1) is the pinacle of man(7) usage.

> 2. If one is in a _really_ big hurry to find something in a man page,
> typing "/OPTIONS" in the pager is going to win every time over
> scanning the screen for flags mentioned in prose paragraphs.

No one is arguing for burying options in prose.  The list of options is
typically near the start of the man page and stands out by itself.
nroff(1) is an exception because it's mostly punting the definition of
groups of options onto other man pages.

I gave up reading at this point.  :-(

-- 
Cheers, Ralph.
https://plus.google.com/+RalphCorderoy