X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/ffdced195920ef2cdd17a914b91e50ba0f801b45..c0a23a5450191c9c67b8ab7ce7b0aea382fa6da6:/docs/README.manpages?ds=sidebyside

diff --git a/docs/README.manpages b/docs/README.manpages
index fa423def..86cd725c 100644
--- a/docs/README.manpages
+++ b/docs/README.manpages
@@ -1,16 +1,17 @@
 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%"
 .\"
 .\" %nmhwarning%
-.\" $Id$
 .\"
-.TH COMP %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
 .SH NAME
 comp \- compose a message
+.\"
 .SH SYNOPSIS
 .HP 5
+.na
 .B comp 
 .RI [ +folder ]
 .RI [ msgs ]
@@ -19,39 +20,63 @@ 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
-.fc ^ ~
-.nf
-.ta \w'/usr/local/nmh/etc/ExtraBigFileName  'u
-^%etcdir%/components~^The standard message skeleton
-
+.\"
 .SH "PROFILE COMPONENTS"
-.fc ^ ~
-.nf
-.ta 2.4i
-.ta \w'ExtraBigProfileName  'u
-^Path:~^To determine the user's nmh directory
-
-.SH "SEE ALSO"
-dist(1), forw(1), repl(1), send(1), whatnow(1), mh-profile(5)
-
+.TP
+Path
+Location of the user's MH folder directory
+.TP
+moreproc
+The pager command name
+.\"
 .SH DEFAULTS
-.nf
-.RB ` +folder "' defaults to the current folder"
-
+.TP
+.RI + folder
+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
 
 ---------------------------------------
-In the FILES section, use a spacer of "/usr/local/nmh/etc" for now,
-we'll parametrize that into %etcdir% later.
+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 (no abbreviations or shortcuts):
+
+  January 2, 1904
+
+not the unparseable
+
+  01/02/04
+
+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 using a different directory layout.
 
 
 Source files
@@ -92,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:
 
-		.BR mh-draft (5)
+		.BR comp (1)
 
 SYNPOSIS section
 
@@ -180,3 +205,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.