From owner-freebsd-doc Wed Feb 5 20:14:51 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 AEEEB37B401; Wed, 5 Feb 2003 20:14:49 -0800 (PST) Received: from sccrmhc02.attbi.com (sccrmhc02.attbi.com [204.127.202.62]) by mx1.FreeBSD.org (Postfix) with ESMTP id E9A6A43F85; Wed, 5 Feb 2003 20:14:44 -0800 (PST) (envelope-from horikawa@jp.freebsd.org) Received: from localhost (12-252-35-167.client.attbi.com[12.252.35.167]) by sccrmhc02.attbi.com (sccrmhc02) with SMTP id <2003020604143800200i3knve>; Thu, 6 Feb 2003 04:14:38 +0000 Date: Wed, 05 Feb 2003 21:14:27 -0700 (MST) Message-Id: <20030205.211427.59464356.horikawa@attbi.com> To: swear@attbi.com Cc: freebsd-doc@FreeBSD.ORG, ru@FreeBSD.ORG Subject: Re: manpage section ordering and mdoc(7) manpage From: Kazuo Horikawa In-Reply-To: <6qel6qif5w.l6q@localhost.localdomain> References: <6qel6qif5w.l6q@localhost.localdomain> X-Mailer: Mew version 3.1 on Emacs 21.2 / Mule 5.0 (SAKAKI) Mime-Version: 1.0 Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit 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 (Cc'ing mdoc(7) authority as he looks missing freebsd-doc mails.) swear@attbi.com (Gary W. Swearingen) wrote: > The mdoc(7) manpage seems to claim to be the FreeBSD standard for > manpages (or at least part of the standard). Is it? Should it be? > > Specifically, is the order of sections specified by the manpage the > FreeBSD standard, which, if violated, calls for a doc PR? > > For instance, should the mdoc(7) manpage have its own "FILES" and > "DIAGNOSTICS" sections re-ordered to match it's own rules? Or should > the manpage be modified to sound less like a standard? Ruslan, what do you think about section ordering Gary mentioned? I only sweeped section 8, but I found ac.8, getty.8, init.8, mount.8, nslookup.8 nsupdate.8, pppd.8, pw.8, restore.8, rlogind.8, rshd.8, rtadvd.8, rtsold.8 and sa.8 do not follow "this order." (FILES vs DIAGNOSTICS) > If it IS the standard, should it be modified to no longer require the > "IMPLEMENTATION NOTES" and "RETURN VALUES" sections, a "standard" which > is seldom followed as reflected in the manpage's own example template? Gary, I understand that IMPLEMENTATION NOTES and RETURN VALUES are optional sections, as they are listed under the explanation "The following commands should be uncommented and used where appropriate." as follow: .\" The following commands should be uncommented and .\" used where appropriate. .\" .Sh IMPLEMENTATION NOTES .\" This next command is for sections 2, 3 and 9 function .\" return values only. .\" .Sh RETURN VALUES [snip] -- Kazuo Horikawa To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message