[TUHS] man-page style

[Doug McIlroy]

Regardless of standards considerations, if there's any advice
that needs to be hammered into man authors, it's to be concise
and accurate, but not pedantic. As Will Strunk commanded,
"Omit needless words."

The most needless words of all are promotional. No man page
should utter words like "powerful", "extraordinarily versatile",
"user-friendly", or "has a wide range of options".

As another instance of the rule, it would be better to recommend
short subtitles than to help make them long by recommending
quotes. If anything is said about limited-length macros, it
would best be under BUGS.

As editor for v7-v10, I would not offer v7 as a canonical
model. It owed its use of boldface in SYNOPIS to the limited
number of fonts (Typically R,F,I,S) that could be on our
typesetter at the same time. For v9 we were able to follow
Kernighan and adopt a distinct literals font (L, which happened
to be Courier but could have been identified with bold had we
wished). I still think this is the best choice.

As for options, v7 is a very poor model. It has many pages
that describe options in line, just as v1 had done for its
few options (called flags pre-v7). By v10 all options were
displayed in a list format.

For nagging reasons of verbal continuity, the options displays
were prefaced by *needless words* like, "The following options
are recognized". A simple OPTIONS heading would be better.

Unfortunately, an OPTIONS heading would intrude between the
basic description and less important details that follow
the options. (I don't agree that it would come too closely
after DESCRIPTION; a majority of man pages already have even
shorter sections.)  OPTIONS could be moved to the end of
DESCRIPTION. However, options may well be the biggest reason
for quick peeks at man pages; they should be easy to spot. It
has reasonably been suggested that OPTIONS should be a .SS
subsection.  That might be followed by .SS DETAILS.

Doug