Date: 07 Feb 2003 18:15:45 -0800 From: swear@attbi.com (Gary W. Swearingen) To: Ruslan Ermilov <ru@FreeBSD.ORG> Cc: Kazuo Horikawa <horikawa@jp.freebsd.org>, freebsd-doc@FreeBSD.ORG Subject: Re: manpage section ordering and mdoc(7) manpage Message-ID: <h7adh7cyb2.dh7@localhost.localdomain> In-Reply-To: <20030207160213.GA71529@sunbay.com> References: <6qel6qif5w.l6q@localhost.localdomain> <20030205.211427.59464356.horikawa@attbi.com> <20030206103215.GB82539@sunbay.com> <4ty94tcbic.94t@localhost.localdomain> <20030207160213.GA71529@sunbay.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Ruslan Ermilov <ru@FreeBSD.ORG> writes:
> 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.
According to the template, "RETURN VALUES" is always optional (like
"ENVIRONMENT", while, as you said here and later in the manpage, it is
required for sections 2, 3, and 9. (Except that the "void" thing isn't
documented in the manpage -- corrected in patch below.)
> > Note that the template (and some lines following it) disagree (about
> > order) from the "Page Structure Domain"/"Section Headers" subsection.
> >
> Have I overlooked something when I was editing this back in 2001?
I think so. (There's a lot to overlook.) Corrected awkwardly (because
of the "grouping" problem) in the patch below. (I slipped in a couple
of other (minor) changes, too. I suggest you slip one in to describe
"document date"; some old manpages have old dates, some have new dates.)
> > > 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.
That will require some rewording near the word "DIAGNOSTICS" in several
places, of course.
> > I sure wish .Ex's output sounded less like guru-speak:
> >
> > The cat utility exits 0 on success, and >0 if an error occurs.
...
> 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."
That's a lot better than "exits 0", but I think using "exit status"
would be good, at least until "EXIT STATUS" sections are more common.
With few exceptions, is the term used throughout the sh, csh, bash,
pdksh, and (almost) intro(1) manpages). Considering your other comment,
I propose the following. If nobody else joins the discussion, I can
raise the issue in a new thread at a later date.
The exit status of *cat* will be 0 on success and >0 otherwise.
Thanks.
Here's the patch based on a 4.7-STABLE file from about 11'OCT'2002
--- /pr/work/mdoc..orig.7 Fri Feb 7 16:20:21 2003
+++ /pr/work/mdoc.7 Fri Feb 7 17:55:40 2003
@@ -571,10 +571,10 @@
\&.Sh SYNOPSIS
\&.Sh DESCRIPTION
\&.\e" The following requests should be uncommented and
-\&.\e" used where appropriate.
+\&.\e" used when appropriate.
\&.\e" .Sh IMPLEMENTATION NOTES
-\&.\e" This next request is for sections 2, 3 and 9 function
-\&.\e" return values only.
+\&.\e" This next request is required for sections 2, 3 and 9 function
+\&.\e" return values (except when void) only.
\&.\e" .Sh RETURN VALUES
\&.\e" This next request is for sections 1, 6, 7 and 8 only.
\&.\e" .Sh ENVIRONMENT
@@ -2591,11 +2591,6 @@
.
.Ss "Section Headers"
.
-The following
-.Ql .Sh
-section header macros are required in every man page.
-The remaining section headers are recommended at the discretion of the
-author writing the manual page.
The
.Ql .Sh
macro is parsed but not generally callable.
@@ -2603,8 +2598,12 @@
.Ql .Sh
only; it then reactivates the default font for
.Ql .Sh .
-.Pp
The default width is 8n.
+.Pp
+The following
+.Ql .Sh
+section header macros are required in every man page,
+except as noted.
.
.Bl -tag -width ".Li .Sh\ RETURN\ VALUES"
.It Li ".Sh NAME"
@@ -2623,7 +2622,9 @@
.Ql .Nd ,
which separates the subject name from the third item, which is the
description.
-The description should be the most terse and lucid possible, as the space
+The description should be the most terse and lucid possible (while giving
+.Xr apropos 1
+users apropos words to match), as the space
available is small.
.Pp
.Ql .Nd
@@ -2701,7 +2702,10 @@
below).
.
.It Li ".Sh IMPLEMENTATION NOTES"
-Implementation specific information should be placed here.
+Implementation-specific information should be placed here.
+This is optional in all man pages as explained above the
+.Li ".Sh ENVIRONMENT"
+description.
.
.It Li ".Sh RETURN VALUES"
Sections 2, 3 and\~9 function return values should go here.
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?h7adh7cyb2.dh7>