[Groff-commit] [groff] 01/01: * tmac/groff_mdoc.man: Improve the manual page template.

[Werner LEMBERG]

wl pushed a commit to branch master
in repository groff.

commit 6d9c6728213e047bccd622bfb0944332d2bbaaf4
Author: Ingo Schwarze <address@hidden>
Date:   Sun Feb 16 08:26:46 2014 +0100

    * tmac/groff_mdoc.man: Improve the manual page template.
    
     - Add the EXIT STATUS section.  It is widely used in at least
       NetBSD, FreeBSD, OpenBSD, and DragonFly manuals.
     - 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 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 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, and is in whidespread use
       today, not just in BSD base system manuals, but for example in
       Perl manuals as well.
---
 ChangeLog           |   34 ++++++++++++++++++++++++++++++++++
 tmac/groff_mdoc.man |   19 +++++++++++--------
 2 files changed, 45 insertions(+), 8 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 9c2c775..4f26218 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,37 @@
+2014-02-15  Ingo Schwarze  <address@hidden>
+
+       * tmac/groff_mdoc.man: Improve the manual page template.
+
+        - Add the EXIT STATUS section.  It is widely used in at least
+          NetBSD, FreeBSD, OpenBSD, and DragonFly manuals.
+        - 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 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 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, and is in whidespread use
+          today, not just in BSD base system manuals, but for example in
+          Perl manuals as well.
+
 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