From owner-freebsd-doc Thu Feb 6 2:32:54 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 D0F1337B401 for ; Thu, 6 Feb 2003 02:32:51 -0800 (PST) Received: from whale.sunbay.crimea.ua (whale.sunbay.crimea.ua [212.110.138.65]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0F49243FB1 for ; Thu, 6 Feb 2003 02:32:44 -0800 (PST) (envelope-from ru@whale.sunbay.crimea.ua) Received: from whale.sunbay.crimea.ua (root@localhost) by whale.sunbay.crimea.ua (8.12.6/8.12.6/Sunbay) with SMTP id h16AWYon088543 for ; Thu, 6 Feb 2003 12:32:34 +0200 (EET) (envelope-from ru@whale.sunbay.crimea.ua) Received: from whale.sunbay.crimea.ua (ru@localhost [127.0.0.1]) by whale.sunbay.crimea.ua (8.12.6/8.12.6/Sunbay) with ESMTP id h16AWWxQ088525 (version=TLSv1/SSLv3 cipher=EDH-RSA-DES-CBC3-SHA bits=168 verify=NO); Thu, 6 Feb 2003 12:32:34 +0200 (EET) (envelope-from ru@whale.sunbay.crimea.ua) Received: (from ru@localhost) by whale.sunbay.crimea.ua (8.12.6/8.12.6/Submit) id h16AWFsE088495; Thu, 6 Feb 2003 12:32:15 +0200 (EET) Date: Thu, 6 Feb 2003 12:32:15 +0200 From: Ruslan Ermilov To: Kazuo Horikawa Cc: swear@attbi.com, freebsd-doc@freebsd.org Subject: Re: manpage section ordering and mdoc(7) manpage Message-ID: <20030206103215.GB82539@sunbay.com> References: <6qel6qif5w.l6q@localhost.localdomain> <20030205.211427.59464356.horikawa@attbi.com> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="Fig2xvG2VGoz8o/s" Content-Disposition: inline In-Reply-To: <20030205.211427.59464356.horikawa@attbi.com> User-Agent: Mutt/1.5.1i 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 --Fig2xvG2VGoz8o/s Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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.) >=20 Yes, sorry, I'm unable to keep up with the mail load, so I unsubscribed from -doc. > 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? > > Yes, it was designed with this in mind. > > Specifically, is the order of sections specified by the manpage the > > FreeBSD standard, which, if violated, calls for a doc PR? > > Yes, the order of sections in the manpage (documented under the A MANUAL PAGE TEMPLATE and Section Headers) was specifically aligned with our /usr/share/examples/mdoc/ templates. > > 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? >=20 Yes, DIAGNOSTICS in the mdoc(7) manpage should be moved where appropriate. > Ruslan, what do you think about section ordering Gary mentioned? >=20 > 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) >=20 Fixing this globally would be highly appreciated. I have this task of ordering sections sitting in my mdocNG/TODO. So, you may leave it to me, or you may do it yourself, if you have enough time now. > > 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? >=20 > 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: >=20 > .\" 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] >=20 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". 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. Cheers, --=20 Ruslan Ermilov Sysadmin and DBA, ru@sunbay.com Sunbay Software AG, ru@FreeBSD.org FreeBSD committer, +380.652.512.251 Simferopol, Ukraine http://www.FreeBSD.org The Power To Serve http://www.oracle.com Enabling The Information Age --Fig2xvG2VGoz8o/s Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.1 (FreeBSD) iD8DBQE+QjmvUkv4P6juNwoRAg7pAKCHmhNGieTr+jZUVQiRp5GEkaEJ+gCfURlt 2t2KUijoMvnhbQQ7183Zj7E= =zZ8a -----END PGP SIGNATURE----- --Fig2xvG2VGoz8o/s-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message