From owner-freebsd-doc Thu Feb 6 14: 5: 6 2003 Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 7558537B41F; Thu, 6 Feb 2003 14:05:04 -0800 (PST) Received: from sccrmhc02.attbi.com (sccrmhc02.attbi.com [204.127.202.62]) by mx1.FreeBSD.org (Postfix) with ESMTP id 38E7D43F85; Thu, 6 Feb 2003 14:05:03 -0800 (PST) (envelope-from swear@attbi.com) Received: from localhost.localdomain (unknown[12.242.158.67]) by sccrmhc02.attbi.com (sccrmhc02) with ESMTP id <200302062205020020033pbne>; Thu, 6 Feb 2003 22:05:02 +0000 Received: from localhost.localdomain (localhost [127.0.0.1]) by localhost.localdomain (8.12.6/8.12.5) with ESMTP id h16M3j5F035466; Thu, 6 Feb 2003 14:03:46 -0800 (PST) (envelope-from swear@attbi.com) Received: (from jojo@localhost) by localhost.localdomain (8.12.6/8.12.5/Submit) id h16M3dm6035461; Thu, 6 Feb 2003 14:03:39 -0800 (PST) (envelope-from swear@attbi.com) X-Authentication-Warning: localhost.localdomain: jojo set sender to swear@attbi.com using -f To: Ruslan Ermilov , Kazuo Horikawa Cc: freebsd-doc@FreeBSD.ORG Subject: Re: manpage section ordering and mdoc(7) manpage References: <6qel6qif5w.l6q@localhost.localdomain> <20030205.211427.59464356.horikawa@attbi.com> <20030206103215.GB82539@sunbay.com> From: swear@attbi.com (Gary W. Swearingen) Date: 06 Feb 2003 14:03:39 -0800 In-Reply-To: <20030206103215.GB82539@sunbay.com> Message-ID: <4ty94tcbic.94t@localhost.localdomain> Lines: 47 User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.1 (Cuyahoga Valley) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org Ruslan Ermilov writes: > On Wed, Feb 05, 2003 at 09:14:27PM -0700, Kazuo Horikawa wrote: > > (Cc'ing mdoc(7) authority as he looks missing freebsd-doc mails.) (Thank you, Kazuo; I should have thought of that.) > RETURNS VALUES is NOT optional for sections 2, 3 and 9 functions, > except when the only functions that are documented return "void". > > IMPLEMENTATION NOTES is indeed optional, and "should be used > where appropriate". So we have an "optional" mixed in with the (sometimes) "required", which makes a couple of "the following..." explanations not work. Should the section order standard be changed to group the "required" (i.e., swap "IMPLEMENTATION NOTES" and "RETURN VALUES"), or should the mdoc(7) text be changed so that each section description says whether it's required or not, or what? Note that the template (and some lines following it) disagree (about order) from the "Page Structure Domain"/"Section Headers" subsection. Ruslan, thanks for replying. Do you want me to file a PR on this, or just keep this in e-mail for now, or just go away and leave it to you? (I won't be writing patches for the many other out-of-order manpages, in any case.) > I'm planning on adding yet another standard section, EXIT STATUS, > for sections 1 and 8 manpages; the idea is stolen from 1003.1-2001. And for section 6? (mdoc(7) says .Ex is for 1, 6, 8.) I sure wish .Ex's output sounded less like guru-speak: The cat utility exits 0 on success, and >0 if an error occurs. To a newbie, that doesn't even sound like English. How can a utility exit zero? When did it enter zero? It's programmer's lingo. Maybe: The exit status will be 0 on success, and >0 if an error occurs. Even if readers don't know what "exit status" is, they will at least have a term to go searching for information about. The above rewording also makes the macro work for manpages with multiple command names and for commands which don't really qualify as utilities, like section 6 games and commands like (arguably) reboot(8), savecore(8), sendmail(8). To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message