> > *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 <d...@cs.dartmouth.edu> 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 > >
