From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.0 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from minnie.tuhs.org (minnie.tuhs.org [45.79.103.53]) by inbox.vuxu.org (OpenSMTPD) with ESMTP id 9e5a0d19 for ; Fri, 16 Nov 2018 04:50:44 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id 31448A26E7; Fri, 16 Nov 2018 14:50:43 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id 2D8BCA26D6; Fri, 16 Nov 2018 14:50:20 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id BD864A26D6; Fri, 16 Nov 2018 14:50:17 +1000 (AEST) Received: from mcvoy.com (mcvoy.com [192.169.23.250]) by minnie.tuhs.org (Postfix) with ESMTPS id 6A593A26D5 for ; Fri, 16 Nov 2018 14:50:17 +1000 (AEST) Received: by mcvoy.com (Postfix, from userid 3546) id 886F635E133; Thu, 15 Nov 2018 20:50:16 -0800 (PST) Date: Thu, 15 Nov 2018 20:50:16 -0800 From: Larry McVoy To: Doug McIlroy Message-ID: <20181116045016.GK3341@mcvoy.com> References: <201811160003.wAG03mlF139232@tahoe.cs.Dartmouth.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <201811160003.wAG03mlF139232@tahoe.cs.Dartmouth.EDU> User-Agent: Mutt/1.5.24 (2015-08-30) Subject: Re: [TUHS] man-page style X-BeenThere: tuhs@minnie.tuhs.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: The Unix Heritage Society mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: tuhs@tuhs.org Errors-To: tuhs-bounces@minnie.tuhs.org Sender: "TUHS" >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