[TUHS] man-page style
lm at mcvoy.com
Fri Nov 16 14:50:16 AEST 2018
>From my quotes page:
How good is good enough: documentation
Looking at Sun man pages versus Linux man pages is like looking at a Van
Gogh or Monet after studying the work of the high school football player
taking art as an "easy" elective.
Amy Graf, BitMover
On Thu, Nov 15, 2018 at 07:03:48PM -0500, Doug McIlroy wrote:
> 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.
Larry McVoy lm at mcvoy.com http://www.mcvoy.com/lm
More information about the TUHS