Re: [TUHS] man-page style

[Larry McVoy <lm@mcvoy.com>]

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.
> 
> Doug

-- 
---
Larry McVoy            	     lm at mcvoy.com             http://www.mcvoy.com/lm