Date: Thu, 6 Feb 2003 12:32:15 +0200 From: Ruslan Ermilov <ru@freebsd.org> To: Kazuo Horikawa <horikawa@jp.freebsd.org> Cc: swear@attbi.com, freebsd-doc@freebsd.org Subject: Re: manpage section ordering and mdoc(7) manpage Message-ID: <20030206103215.GB82539@sunbay.com> In-Reply-To: <20030205.211427.59464356.horikawa@attbi.com> References: <6qel6qif5w.l6q@localhost.localdomain> <20030205.211427.59464356.horikawa@attbi.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030206103215.GB82539>