Re: [groff] man-page fixes

[John Gardner]

>
> *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".*


I couldn't agree more, Doug. *curl(1)* reminds me of this every time I run
`man curl` for a reminder on what switch is used to retrieve HTTP headers,
and the first search result for "head" is

curl offers a busload of useful tricks like proxy support [....] as you

will see below, the number of features will make your *head* spin!
>

Granted, *curl(1)* is pretty much doomed to having monolithic options-list,
given the program's "kitchen-sink" design. But the least they could do is
cull out the fluff...

On Fri, 16 Nov 2018 at 12:40, Doug McIlroy <address@hidden> 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
>
>