From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [10.186.190.222] ([166.175.60.245]) by ewsd; Thu Nov 15 20:38:55 EST 2018 From: Stanley Lieber Content-Type: multipart/alternative; boundary=Apple-Mail-351B5393-105A-49CD-882C-80E7BA57DDF9 Content-Transfer-Encoding: 7bit Mime-Version: 1.0 (1.0) Subject: Fwd: [TUHS] man-page style Date: Thu, 15 Nov 2018 20:38:53 -0500 Message-Id: <3D524435-7C57-42C4-80A8-BE19CF275C75@stanleylieber.com> References: <201811160003.wAG03mlF139232@tahoe.cs.Dartmouth.EDU> To: 9front@9front.org X-Mailer: iPhone Mail (16B92) List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: RESTful JSON over ACPI CMS core-based database --Apple-Mail-351B5393-105A-49CD-882C-80E7BA57DDF9 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit This advice was not honored consistently in Plan 9. sl Begin forwarded message: > From: Doug McIlroy > 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 --Apple-Mail-351B5393-105A-49CD-882C-80E7BA57DDF9 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable

Thi= s advice was not honored consistently in Plan 9.

<= /div>

sl

Begin forwarded messa= ge:

From: Dou= g McIlroy <doug@cs.dartmouth.edu= >
Date: November 15, 2018 at 7:03:48 PM EST
To: <= a href=3D"mailto:tuhs@tuhs.org">tuhs@tuhs.org
Subject: [TUH= S] man-page style

Regardless of standards considerations, if there's any a= dvice
that needs to be hammered into man authors, it's to be= concise
and accurate, but not pedantic. As Will Strunk comm= anded,
"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".
<= /span>
As another instance of the rule, it would be better to recom= mend
short subtitles than to help make them long by recommen= ding
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
K= ernighan and adopt a distinct literals font (L, which happened
to be Courier but could have been identified with bold had we
<= span>wished). I still think this is the best choice.
=
As for options, v7 is a very poor model. It has many pages<= br>that describe options in line, just as v1 had done for itsfew options (called flags pre-v7). By v10 all options weredisplayed in a list format.

For nagg= ing reasons of verbal continuity, the options displays
were p= refaced 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<= br>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

= --Apple-Mail-351B5393-105A-49CD-882C-80E7BA57DDF9--