At 2018-11-12T07:23:04+0100, Ingo Schwarze wrote: > Hi Branden, > > G. Branden Robinson wrote on Tue, Nov 06, 2018 at 01:57:41PM -0500: > > > commit 75205acd4f5c7586199e7b19fa61971fd3b31e19 > > Author: G. Branden Robinson <g.branden.robin...@gmail.com> > > 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 > $
Try man-pages(7).
Neither man(7) from Kerrisk's man-pages project nor our groff_man(7)
purport to describe, let alone mandate, _any_ section headings apart
from "NAME", which means your argument against "OPTIONS" works just as
well against "DESCRIPTION" for the man(7) format.
Regarding mdoc-formatted pages, I cede the point, but it's not
applicable to grn(1).
> 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.
I don't think man(7) is _officially_ specified _anywhere_. If it were,
perhaps I would find significantly less to be annoyed with in the Wild
West atmosphere of italicization and boldfacing conventions varying
within the same document or even the same paragraph.
> 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),
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,
providing 3,855 man pages in sections 1, 6, and 8:
$ find /usr/share/man/man[168] -type f | wc -l
3855
Of these, let us see how many have a (case-insensitive) Options section,
being sure to exclude symlinks and mdoc-formatted pages:
$ N=0; D=0; for F in $(find /usr/share/man/man[168]); do if test -f "$F"
&& ! test -L "$F"; then TXT=$(zcat "$F"); if echo "$TXT" | grep -q
'^\.\s*TH\>'; then D=$((D + 1)); if echo "$TXT" | grep -q
'^\.\s*SH\s\+\(OPTIONS\|Options\)$'; then N=$((N + 1)); fi; fi; fi;
done; echo "$N/$D"
1477/3748
(Too late, I realized I should have been using awk...)
That's about 39% of the pages.
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%.
> 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.
You complain about the non-standardness of the "OPTIONS" section, but in
holding up grn(1)'s "DESCRIPTION" as a model example of brevity (about
33 lines on an 80-column grotty device) you conspicuously 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"
My inclination would be to demote all these to subsections (.SS)--which
you might favor--of the Description section--which I suspect you might
not.
> Using an OPTIONS section is useless because it implies that the
> DESCRIPTION section before it becomes ridiculously short.
Not if you've got another 248 lines of reading to do in it.
> 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.
My rebuttal to this is simply:
1. Some commands are more complex in their operation than others. They
consequently require more space to document/explain. Classic Unix
commands which are intended to implement relatively primitive operations
close to the system (ask what time it is in a human-comprehensible
format, manipulate objects on the filesystem in ways that should appear
atomic to userspace) are of a different category than implementations of
"little languages".
If you disagree, then I think you need to justify why any long man pages
exist at all.
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. Visually scanning
for "OPTIONS" set in bold and flush left is even faster when it happens
to already be present on the screen.
However, you (and the Version 7 Unix man pages on my system) have
convinced me of one thing:
* There's no need to break out an Options section if the _only_
discussion of options is in unstructured prose. I'm thinking
specifically of our nroff(1) page. I was going to shunt its
option-exploration paragraph into an Options section, but your
arguments, combined with a bit of reflection and sampling of pages on
my system, have persuaded me that if an Options section exists, it
should contain a list of tagged paragraphs, alphabetically organized,
describing all the supported flags. This for ergonomic purposes;
visually it is low-effort to find a desired flag that way, and much
less work than scanning the words of a paragraph.
So subordinating nroff(1)'s free-form paragraph about options to an
Options section is one change I'm _not_ going to make now.
I'd rearrange OpenBSD's cp(1), too. It leaps into the available options
too quickly. See the 6 paragraphs _after_ the option listing?
In my opinion 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 to into an option breakdown,
because experts are in too much a hurry to be reminded what the flags do
to press the space bar, you overwhelm the novice or the person who has
forgotten a lot with immediate digressions into corner cases.
For instance, to my reading, all the chatter about set[gu]id bits under
the -p flag makes more sense if one has first read the third paragraph
after the not-an-Options-section. (Set[ug]id bits are a fundamental
Unix concept deserving of a section 7 man page, in my opinion. How many
dead trees and student dollars wasted on "Introduction to Unix" books
could have been saved over the decades if our forebears had actually
used section 7 to elucidate the system?)
> > 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.
As it happens, GNU nroff(1) is precisely an example of
whitespace-intolerance in option parsing. It sure makes the Synopsis
markup uglier, as you will shortly see. :-/
But yeah, I can buy this.
The world needs a section 7 man page on option conventions, too. I can think
of four: classical Unix (nroff(1)), BSD (afmtodit(1)), X11 (xeyes(1)),
and GNU. (If there's a System V option convention, I don't know it.)
> > 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.
That's the idea. People have a hard time learning man(7). If I can
give them a simple rule:
Always double-quote a multi-word argument to a macro.
We'll all have better man pages to read.
And as Werner noted, doing so is more portable. :)
Our longest section headings, by word count, are in glilypond(1), for
what it's worth. How standard do you think these are?
.SH "THE LILYPOND PARTS IN ROFF INPUT"
.SH "TRANSFORMATION PROCESSES FOR GENERATING EPS FILES"
.SH "THE GENERATED NEW ROFF STRUCTURE"
--
Regards,
Branden
signature.asc
Description: PGP signature
