Update manpages to use .TP for tagged paragraphs (part I).

[nmh] / docs / README.manpages

diff --git a/docs/README.manpages b/docs/README.manpages
index ce9ac26e4b4c8e0549253815b0ac2416feaf7b01..6d6111df8eb7616b768bf9a02866613154b6938f 100644 (file)
--- a/docs/README.manpages
+++ b/docs/README.manpages
@@ -1,6 +1,6 @@
 NMH MANPAGE STYLE GUIDE
 
-nmh manpages should be in this general form:
+nmh manpages should be in this general form and section order:
 
 .TH COMP %manext1% "DATE" "%nmhversion%"
 .\"
@@ -8,6 +8,7 @@ nmh manpages should be in this general form:
 .\"
 .SH NAME
 comp \- compose a message
+.\"
 .SH SYNOPSIS
 .B comp 
 .RI [ +folder ]
@@ -20,13 +21,7 @@ comp \- compose a message
 .SH DESCRIPTION
 .B Comp
 is used to create a new message to be mailed.  It copies something.
-.SH FILES
-.TP
-filename1
-description of filename1
-.TP
-filename2
-description of filename2
+.\"
 .SH "PROFILE COMPONENTS"
 .TP
 Path
@@ -34,13 +29,7 @@ Location of the user's MH folder directory
 .TP
 moreproc
 The pager command name
-.SH "SEE ALSO"
-.IR dist (1),
-.IR forw (1),
-.IR repl (1),
-.IR send (1),
-.IR whatnow (1),
-.IR mh-profile (5)
+.\"
 .SH DEFAULTS
 .TP
 .RI + folder
@@ -48,15 +37,30 @@ defaults to the current folder
 .\"
 .SH CONTEXT
 None
+.\"
+.SH FILES
+.TP
+filename1
+description of filename1
+.TP
+filename2
+description of filename2
+.\"
+.SH "SEE ALSO"
+.IR dist (1),
+.IR forw (1),
+.IR repl (1),
+.IR send (1),
+.IR whatnow (1),
+.IR mh-profile (5)
 .\" Leave out the BUGS section if there are none worth describing.
 .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.
-Spell out the date in English prose:  Month Day, Year
+Spell out the date (no abbreviations or shortcuts):
 
   January 2, 1904
 
@@ -64,17 +68,12 @@ not the unparseable
 
   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
 variable and long, so any indentation value that works for you won't
-work for someone else.
-
-
-The BUGS section goes last.
+work for someone using a different directory layout.
 
 
 Source files
@@ -115,8 +114,7 @@ Program names
                .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)
 
@@ -203,3 +201,18 @@ Pointer manpages
                .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 not
+    applicable.
+
+
+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.