Date: Fri, 7 Feb 2003 18:02:13 +0200 From: Ruslan Ermilov <ru@freebsd.org> To: "Gary W. Swearingen" <swear@attbi.com> Cc: Kazuo Horikawa <horikawa@jp.freebsd.org>, freebsd-doc@freebsd.org Subject: Re: manpage section ordering and mdoc(7) manpage Message-ID: <20030207160213.GA71529@sunbay.com> In-Reply-To: <4ty94tcbic.94t@localhost.localdomain> References: <6qel6qif5w.l6q@localhost.localdomain> <20030205.211427.59464356.horikawa@attbi.com> <20030206103215.GB82539@sunbay.com> <4ty94tcbic.94t@localhost.localdomain>
next in thread | previous in thread | raw e-mail | index | archive | help
--envbJBWh7q8WU6mo Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Thu, Feb 06, 2003 at 02:03:39PM -0800, Gary W. Swearingen wrote: > Ruslan Ermilov <ru@FreeBSD.ORG> writes: >=20 > > 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 > (Thank you, Kazuo; I should have thought of that.) >=20 > > RETURNS VALUES is NOT optional for sections 2, 3 and 9 functions, > > except when the only functions that are documented return "void". > >=20 > > IMPLEMENTATION NOTES is indeed optional, and "should be used > > where appropriate". >=20 > 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? >=20 I don't see any problems with the current scheme. The only required sessions are NAME, SYNOPSIS, and DESCRIPTION. Everything else should be uncommented and used where appropriate. "Where appropriate" is described individually for some sections (I mean the comments in the A MANUAL PAGE TEMPLATE section of mdoc(7)). Sections are also listed in the order they should be. > Note that the template (and some lines following it) disagree (about > order) from the "Page Structure Domain"/"Section Headers" subsection. >=20 Have I overlooked something when I was editing this back in 2001? > 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.) >=20 No PRs are needed. We should just work something out and then fix it. > > 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. >=20 > And for section 6? (mdoc(7) says .Ex is for 1, 6, 8.) >=20 Strictly speaking, yes, but none of the current section 6 manpages document their exit statuses. > I sure wish .Ex's output sounded less like guru-speak: >=20 > The cat utility exits 0 on success, and >0 if an error occurs. >=20 > 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: >=20 > The exit status will be 0 on success, and >0 if an error occurs. >=20 English speakers have to decide here. In Russian, we have this phrase sounding like "The cat utility returns 0 on successful termination, and >0 otherwise." Let me know if you can come up to an agreement on better wording; I can fix this fast and easily. > Even if readers don't know what "exit status" is, they will at least > have a term to go searching for information about. >=20 Well, readers that are unfamiliar with some manual section terms should first read the "intro" manpage for this section, like e.g. intro(1) which explains this in good details (IMO). > 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). >=20 I think the above wording is not good for at least one reason: if you document multiple utilities in a single manpage, it should be possible to explicitly document different exit statuses for different utilities. BTW, the .Ex macro is already "smart" with its wording when supplied multiple arguments. 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 --envbJBWh7q8WU6mo Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.1 (FreeBSD) iD8DBQE+Q9iFUkv4P6juNwoRAu1JAJ9WoMA2Tt6wXI33Jz7YA9GEjBwt3wCcCw7O uQGSFPm/4wAG+ovi05nmxvk= =5W05 -----END PGP SIGNATURE----- --envbJBWh7q8WU6mo-- 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?20030207160213.GA71529>