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
