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