Hi,
here is a suggestion to improve the man page template in
the groff_mdoc(7) manual page.
Content improvements:
- Add the EXIT STATUS section.
It is widely used in at least NetBSD, FreeBSD, OpenBSD,
and DragonFly.
- Recommend the DIAGNOSTICS section for section 4 manuals.
Such usage is very widespread in particular for kernel
printf messages emitted by device drivers.
- Do not recommend the DIAGNOSTICS section for command return
values to the shell any longer. While such usage historically
existed, it does not seem common any nowadays, and in any case,
using the now well-established EXIT STATUS section seems
preferable to me.
- Mention the possibility to use ERRORS for section 4 manuals.
While most section 4 manuals have a DIAGNOSTICS section,
only some will need an ERRORS section, but these cases
aren't exactly rare, either. Quite some device driver
manuals explain how to use the device using system calls
like ioctl(2), open(2), read(2) or write(2), in which case
the ERRORS section is the natural place to explain which
errno values the driver may set during such system calls.
- Mentioning signal handling as a content of the ERRORS
section seems redundant, it is already covered by talking
about the errno. The case of errno == EINTR should be handled
just like all other errno cases. For an example showing that
there is no need to single out error handling in any way,
please look at a typical the read(2) manual page.
- Mention the CAVEATS section.
It first appeared in the 4.2BSD execve(2) manual in 1983,
was already used by several manuals by the time of 4.4BSD-Lite2
in 1995, is is in whidespread use today, not just in BSD
base system manuals, but for example in Perl manuals as well.
Formatting improvements:
- For uniformity, format all hints regarding the recommended
contents of the manual sections as one line in parantheses.
- In English enumerations, using a comma is widespread even before
the final "and" or "or", as opposed to some other languages
like German.
If this patch is accepted, i plan to do similar adjustments
in the mandoc(1) distribution and in the OpenBSD base system.
Thanks,
Ingo
diff --git a/ChangeLog b/ChangeLog
index 9c2c775..d09b2fc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2014-02-15 Ingo Schwarze <schwa...@openbsd.org>
+
+ * tmac/groff_mdoc.man: Improve the manual page template.
+
2014-02-14 Bernd Warken <groff-bernd.warken...@web.de>
* src/roff/grog/grog.pl: Add detection of glilypond-parts in groff
diff --git a/tmac/groff_mdoc.man b/tmac/groff_mdoc.man
index c3ad6b4..333f394 100644
--- a/tmac/groff_mdoc.man
+++ b/tmac/groff_mdoc.man
@@ -576,25 +576,28 @@ The body of a man page is easily constructed from a basic
template:
\&.\e" The following commands should be uncommented and
\&.\e" used where appropriate.
\&.\e" .Sh IMPLEMENTATION NOTES
-\&.\e" This next command is for sections 2, 3 and 9 function
-\&.\e" return values only.
+\&.\e" This next command is for sections 2, 3, and 9 only
+\&.\e" (function return values).
\&.\e" .Sh RETURN VALUES
-\&.\e" This next command is for sections 1, 6, 7 and 8 only.
+\&.\e" This next command is for sections 1, 6, 7, and 8 only.
\&.\e" .Sh ENVIRONMENT
\&.\e" .Sh FILES
+\&.\e" This next command is for sections 1, 6, and 8 only
+\&.\e" (command return values to the shell).
+\&.\e" .Sh EXIT STATUS
\&.\e" .Sh EXAMPLES
-\&.\e" This next command is for sections 1, 6, 7, 8 and 9 only
-\&.\e" (command return values (to shell) and
-\&.\e" fprintf/stderr type diagnostics).
+\&.\e" This next command is for sections 1, 4, 6, 7, 8, and 9 only
+\&.\e" (fprintf/stderr type diagnostics).
\&.\e" .Sh DIAGNOSTICS
\&.\e" .Sh COMPATIBILITY
-\&.\e" This next command is for sections 2, 3 and 9 error
-\&.\e" and signal handling only.
+\&.\e" This next command is for sections 2, 3, 4, and 9 only
+\&.\e" (settings of the errno variable).
\&.\e" .Sh ERRORS
\&.\e" .Sh SEE ALSO
\&.\e" .Sh STANDARDS
\&.\e" .Sh HISTORY
\&.\e" .Sh AUTHORS
+\&.\e" .Sh CAVEATS
\&.\e" .Sh BUGS
.Ed
.Pp
