Bring this up to best practices.

[nmh] / docs / README.manpages

diff --git a/docs/README.manpages b/docs/README.manpages
index ce9ac26e4b4c8e0549253815b0ac2416feaf7b01..33693df31a7a173447d0043b1d89fafefff3dc21 100644 (file)
--- a/docs/README.manpages
+++ b/docs/README.manpages
@@ -9,6 +9,8 @@ nmh manpages should be in this general form:
 .SH NAME
 comp \- compose a message
 .SH SYNOPSIS
 .SH NAME
 comp \- compose a message
 .SH SYNOPSIS

+.HP 5
+.na

 .B comp 
 .RI [ +folder ]
 .RI [ msgs ]
 .B comp 
 .RI [ +folder ]
 .RI [ msgs ]


@@ -17,6 +19,7 @@ comp \- compose a message
 .RB [ \-use " | " \-nouse ]
 .RB [ \-version ]
 .RB [ \-help ]
 .RB [ \-use " | " \-nouse ]
 .RB [ \-version ]
 .RB [ \-help ]

+.ad

 .SH DESCRIPTION
 .B Comp
 is used to create a new message to be mailed.  It copies something.
 .SH DESCRIPTION
 .B Comp
 is used to create a new message to be mailed.  It copies something.


@@ -52,11 +55,10 @@ None
 .SH BUGS
 None
 
 .SH BUGS
 None
 

----------------------------------------------------------------------
-
+---------------------------------------

 The DATE in the .TH macro should reflect the most recent non-trivial
 update to the content of the manpage; formatting changes don't count.
 The DATE in the .TH macro should reflect the most recent non-trivial
 update to the content of the manpage; formatting changes don't count.

-Spell out the date in English prose:  Month Day, Year
+Spell out the date (no abbreviations or shortcuts):

 
   January 2, 1904
 
 
   January 2, 1904
 


@@ -64,9 +66,7 @@ not the unparseable
 
   01/02/04
 
 
   01/02/04
 

-
-Don't include a CONTEXT section if contexts don't directly apply to what the
-manpage describes.
+Don't abbreviate the month.

 
 
 In the FILES section, prefer the default .TP indent. The pathnames are
 
 
 In the FILES section, prefer the default .TP indent. The pathnames are


@@ -74,9 +74,6 @@ variable and long, so any indentation value that works for you won't
 work for someone else.
 
 
 work for someone else.
 
 

-The BUGS section goes last.
-
-

 Source files
 
        There should be no ".so" commands to source an external file,
 Source files
 
        There should be no ".so" commands to source an external file,


@@ -115,8 +112,7 @@ Program names
                .B comp
                .BR comp ,
 
                .B comp
                .BR comp ,
 

-       If this is a manpage reference (outside of the SEE ALSO
-       section, which just uses regular text), use:
+       If this is a manpage reference, use:

 
                .IR mh-draft (5)
 
 
                .IR mh-draft (5)
 


@@ -203,3 +199,17 @@ Pointer manpages
                .so man1/folder.1
 
        Also, add this manpage to the appropriate section in Makefile.in
                .so man1/folder.1
 
        Also, add this manpage to the appropriate section in Makefile.in

+       
+
+CONTEXT
+    Don't include a CONTEXT section when contexts are out of context.
+
+
+AUTHOR and HISTORY sections
+
+    These have no place in a manpage.  If you want everlasting glory,
+    try the release notes.
+
+BUGS
+
+    The BUGS section goes last.