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

[G. Branden Robinson]

At 2018-11-12T14:59:45+0000, Ralph Corderoy wrote:
> Hi Branden,

Hi Ralph!

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

I favor brevity, when manageable.  A defense brief is a challenge.  I'll
try to be terser here.

> > > OPTIONS is not a standard section, not at all:
> 
> I agree with Ingo.

This tells us nothing.  If we ignore Michael Kerrisk et al., _no_
section of a man(7) page is standard.  Even "Name" (however you want
to case it) is merely a convention for getting along with external
indexers.

> > 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 |

No.  The Version 7 Unix pages are a wonderful thing but they are not the
final word on current or best practice.  Implement the system documented
there and you'll be rooted in seconds[1], among other problems.

> > (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.)

There was no point in doing it at all if you're going to discard any
_contemporary_ corpus of man pages in favor of elevating one from 1979
as the final word.

> > 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 regard the Austin Group as worthy of consideration as the Bell Labs
CSRC.  Why shouldn't I?

[That said, I see no reason to ape their null-section practices.]

> 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.

Quantify "too short".  Where is the _standard_ that defines this?

> > 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.

Nor I, but my objective is to knead the groff man pages into something
that is broadly consistent and useful as a model for man page writers.
Doubtless there will be many compromises along the way, but "OPTIONS" is
a strange place to make stand given its popularity in the wild.

> > 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.

As I said after you gave up reading, I am--to a point, but not
_exclusively_.

It is best to describe what the command is up to, and let that
discussion motivate the existence of options.  By adhering to a rule of
one terse paragraph before leaping into an option breakdown--because
experts are in too much hurry to be reminded what the flags do to press
the space bar--you overwhelm the novice or the person who has forgotten
much with rapid digressions into corner cases.

> The list of options is typically near the start of the man page and
> stands out by itself.

...depending on how it's typeset.

> nroff(1) is an exception because it's mostly punting the definition of
> groups of options onto other man pages.

In which case it is fine to omit the Options section heading, which I
already said that Ingo persuaded me to do for nroff(1).

> I gave up reading at this point.  :-(

If you bear with me, you might find I reach agreeable points. ;-)

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.

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?

Regards,
Branden

[1] Well, okay, probably not.  At the maximum supported rate of 9600
baud [tty(4)], you won't be doing _anything_ fast.

signature.asc
Description: PGP signature