[Groff] patch: improve the man page template in groff_mdoc(7)

[Ingo Schwarze]

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  <address@hidden>
+
+       * tmac/groff_mdoc.man: Improve the manual page template.
+
 2014-02-14  Bernd Warken  <address@hidden>
 
        * 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