X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/9dedfb15f516695e8d42403a229874220cc6f526..b9e0388a118e84f002ae0da6c7a31bdbd89a73bb:/docs/README.manpages

diff --git a/docs/README.manpages b/docs/README.manpages
index 806e3c79..86cd725c 100644
--- 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,7 +8,10 @@ nmh manpages should be in this general form:
 .\"
 .SH NAME
 comp \- compose a message
+.\"
 .SH SYNOPSIS
+.HP 5
+.na
 .B comp 
 .RI [ +folder ]
 .RI [ msgs ]
@@ -17,16 +20,11 @@ comp \- compose a message
 .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 FILES
-.TP
-filename1
-description of filename1
-.TP
-filename2
-description of filename2
+.\"
 .SH "PROFILE COMPONENTS"
 .TP
 Path
@@ -34,13 +32,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,6 +40,22 @@ defaults to the current folder
 .\"
 .SH CONTEXT
 None
+.\"
+.SH FILES
+.TP
+filename1
+description of filename1
+.TP
+filename2
+description of filename2
+.\"
+.SH "SEE ALSO"
+.BR dist (1),
+.BR forw (1),
+.BR repl (1),
+.BR send (1),
+.BR whatnow (1),
+.BR mh-profile (5)
 .\" Leave out the BUGS section if there are none worth describing.
 .SH BUGS
 None
@@ -68,7 +76,7 @@ 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.
+work for someone using a different directory layout.
 
 
 Source files
@@ -109,10 +117,10 @@ Program names
 		.B comp
 		.BR comp ,
 
-	If this is a manpage reference (outside of the SEE ALSO
-	section, which just uses regular text), use:
+	The first reference to a documented command should be in the form of
+	a manpage reference:
 
-		.IR mh-draft (5)
+		.BR comp (1)
 
 SYNPOSIS section
 
@@ -200,7 +208,8 @@ Pointer manpages
 	
 
 CONTEXT
-    Don't include a CONTEXT section when contexts are out of context.
+    Don't include a CONTEXT section when contexts are not
+    applicable.
 
 
 AUTHOR and HISTORY sections
@@ -210,4 +219,4 @@ AUTHOR and HISTORY sections
 
 BUGS
 
-    The BUGS section goes last.
+    The BUGS section goes last.