Fwd: [TUHS] man-page style

Fwd: [TUHS] man-page style

[Stanley Lieber]

[-- Attachment #1: Type: text/plain, Size: 2245 bytes --]

This advice was not honored consistently in Plan 9.

sl


Begin forwarded message:

> From: Doug McIlroy <doug@cs.dartmouth.edu>
> Date: November 15, 2018 at 7:03:48 PM EST
> To: tuhs@tuhs.org
> Subject: [TUHS] man-page style
> 
> 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

[-- Attachment #2: Type: text/html, Size: 3318 bytes --]