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 4f33d187 for ; Fri, 16 Nov 2018 00:04:20 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id 055E8A26E8; Fri, 16 Nov 2018 10:04:19 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id 394F2A26D6; Fri, 16 Nov 2018 10:03:53 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id 90E6DA26D6; Fri, 16 Nov 2018 10:03:50 +1000 (AEST) Received: from mail.cs.Dartmouth.EDU (mail.cs.dartmouth.edu [129.170.212.100]) by minnie.tuhs.org (Postfix) with ESMTPS id 34A43A26D5 for ; Fri, 16 Nov 2018 10:03:50 +1000 (AEST) Received: from tahoe.cs.Dartmouth.EDU (tahoe.cs.dartmouth.edu [129.170.212.20]) by mail.cs.Dartmouth.EDU (8.15.2/8.15.2) with ESMTPS id wAG03mMt023603 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Thu, 15 Nov 2018 19:03:48 -0500 Received: from tahoe.cs.Dartmouth.EDU (localhost.localdomain [127.0.0.1]) by tahoe.cs.Dartmouth.EDU (8.15.2/8.14.3) with ESMTP id wAG03mB8139233 for ; Thu, 15 Nov 2018 19:03:48 -0500 Received: (from doug@localhost) by tahoe.cs.Dartmouth.EDU (8.15.2/8.15.2/Submit) id wAG03mlF139232 for tuhs@tuhs.org; Thu, 15 Nov 2018 19:03:48 -0500 From: Doug McIlroy Message-Id: <201811160003.wAG03mlF139232@tahoe.cs.Dartmouth.EDU> Date: Thu, 15 Nov 2018 19:03:48 -0500 To: tuhs@tuhs.org User-Agent: Heirloom mailx 12.5 7/5/10 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Subject: [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: , Errors-To: tuhs-bounces@minnie.tuhs.org Sender: "TUHS" 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