[groff] man page structure and philosophy (was: mom manpage)

[G. Branden Robinson]

At 2018-12-05T12:35:12+0100, Ulrich Lauther wrote:
> Peter, I couldn't agree more to what you are saying.
> 
> In my opinion, a man page should contain (at most) NAME, SYNOPSIS,
> COPYRIGHT, DESCRIPTION, OPTIONS, ARGUMENTS, INVOCATION, but not
> LANGUAGE.

I'm going to have come out against this.  You have not identified a
sufficient minimal set.  In fact you seem to have looked at one
specimen, bash(1), which is an outlier, and pruned its section titles
somewhat.  Shells are special, a point to which I will return below.  I
suggest instead reviewing a broad corpus of commonly-used Unix commands.
And, of course, you are completely overlooking the needs of section 2
and 3 man pages.

A man page needs to document its topic's _interface to the system_,
which, for a command, necessarily includes that piece that the user
types on.

In my view, a man page for a command (section 1, 6, or 8) would ideally
document (not an exhaustive list):

* how environment variables change the program's behavior (ENVIRONMENT)
* any files it opens without explicit request (FILES)
* any non-default responses to signals (ASYNCHRONOUS EVENTS)

The last is, admittedly, particularly rare; I tend to see it mainly in
POSIX man pages (which Ingo insists, with some justification, are
counter-examples of good man page writing), but this is also because
many tool writers tend not to install signal handlers (even when they
should), and also tend not to document them at all when they do, causing
much merriment.

Think of a command as black box, or a silicon chip in a ceramic package
with pins sticking out of it.  Every single one of those pins should be
labeled and explained.

Copyright information is _not_ necessary in man page output.  It can
live in comments in the man page source documents and I went to some
trouble making this the case for groff's own man pages for this release.

I don't see what "INVOCATION" and "ARGUMENTS" would offer that
"SYNOPSIS", "OPTIONS", and "DESCRIPTION" would not.

> A bad example is bash: NAME to INVOCATION take 210 lines, o.k..  The
> whole man-page is 5869 lines.  A horror to search for some feature you
> need, even if you vaguely remember to have it seen before.

Bash is large and complex.  As the premier interface to a Unix system
even in the age of the desktop GUI, the shell has always been subjected
to intense demand for features.  Modern hackers find even the authentic
Bourne shell too unfriendly to use; I wonder what they would think of
the Thompson or Mashey shells that preceded it.

I've tended to learn the names of the section titles in bash(1) and just
use less's ed-like directional search commands (/ and ?) to locate what
I need.  Many is the time I've typed "/Parameter Expansion" into less.

Regards,
Branden

signature.asc
Description: PGP signature