Re: [TUHS] man-page style

From my quotes page:

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