Use "script file" in test-version-check for maximum portability.

[nmh] / docs / README.manpages

diff --git a/docs/README.manpages b/docs/README.manpages
index 84275e946b58c18193631cff508d9f7ba8745b17..0976d6c439d7e92c399b42dae58ad1fa418ce12e 100644 (file)
--- a/docs/README.manpages
+++ b/docs/README.manpages
@@ -1,108 +1,106 @@
-NMH MANPAGE STYLE GUIDE
+                     NMH MANPAGE STYLE GUIDE
+                     =======================

 
 

-nmh manpages should be in this general form:
+Nmh manpages generally follow the traditional Bell Labs formatting
+conventions.  We do adopt a few conventions from BSD (primarily,
+section ordering), and have a few of our own (mostly related to
+indentation).

 
 

-.\"
-.\" %nmhwarning%
-.\" $Id$
-.\"
-.TH COMP %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
-.SH NAME
-comp \- compose a message
-.SH SYNOPSIS
-.HP 5
-.B comp 
-.RI [ +folder ]
-.RI [ msgs ]
-.RB [ \-form
-.IR formfile ]
-.RB [ \-use " | " \-nouse ]
-.RB [ \-version ]
-.RB [ \-help ]
-.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
+Troff Considerations

 
 

-.SH "PROFILE COMPONENTS"
-.fc ^ ~
-.nf
-.ta 2.4i
-.ta \w'ExtraBigProfileName  'u
-^Path:~^To determine the user's nmh directory
+       Proper sentences end with a period followed by a newline:

 
 

-.SH "SEE ALSO"
-dist(1), forw(1), repl(1), send(1), whatnow(1), mh-profile(5)
+               This is a sentence.
+               It is followed by another, longer, sentence, but
+               which makes no more sense than the previous one.

 
 

-.SH DEFAULTS
-.nf
-.RB ` +folder "' defaults to the current folder"
+       not

 
 

-.SH CONTEXT
-None
+               This is a sentence.  It is followed by another,
+               longer, sentence, but which makes no more sense
+               than the previous one.

 
 

-.SH BUGS
-None
+       This allows troff to set the correct inter-sentence spacing
+       based on the output device.

 
 

----------------------------------------
-In the FILES section, use a spacer of "/usr/local/nmh/etc" for now,
-we'll parametrize that into %etcdir% later.
+       When quoting, use \*(lq and \*(rq. This ensures correct
+       formatting on typesetter-like devices.

 
 

+       Don't use UTF-8 characters in the manpage source.  We still
+       build and run on systems that can't handle this.  And most
+       anything you would want to use has an internal troff character
+       escape sequence, anyway.

 
 

-Source files

 
 

-       There should be no ".so" commands to source an external file,
-       since these break on Linux, where the man program does not
-       allow source files outside the man/ hierarchy. Instead, insert
-       this fragment:
+Section Ordering

 
 

-               .PP
-               .RS 5
-               .nf
-               %components%
-               .fi
-               .RE
-               .PP
+       Always present sections in the following order:

 
 

-       Of course, replace "components" with a unique identifier that
-       reflects the content being included, like "mts_conf" for
-       etc/mts.conf. Then, add two lines to the man.sed target in
-       Makefile.in like:
+               NAME [*]
+               SYNOPSIS [*]
+               DESCRIPTION [*]
+               PROFILE COMPONENTS
+               DEFAULTS
+               CONTEXT
+               ENVIRONMENT
+               FILES
+               EXAMPLES
+               DIAGNOSTICS [*]
+               SEE ALSO
+               HISTORY
+               BUGS 

 
 

-               echo '/%components%/r $(top_srcdir)/etc/components' >> $@
-               echo ' s,%components%,,g' >> $@
+       Sections marked with a [*] are mandatory.  Only include
+       the others if they are specifically applicable.

 
 

-       At compile time, the contents of the file will physically
-       incorporated into the body of the man page. This is somewhat
-       unfortunate, since later modifications won't be reflected in
-       the manpage, but on the other hand, the manpage will show the
-       default configuration and not local modifications.
+       DIAGNOSTICS must document any non-zero exit codes, and can
+       provide context to error messages.  Obviously it only applies
+       to section 1 and 8 manpages.
+
+
+Dates
+
+       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

 
 

-Program names
+         01/02/04

 
 

-       All nmh program names should be bolded. If there is punctuation
-       after the name, use a .BR construct to avoid the automatic
-       space that's inserted with just a .B:
+       Don't abbreviate the month.
+
+
+Program Names
+
+       In running text, nmh program names should be set in bold,
+       unless you are explicitly referring to the command's
+       documentation, in which case use manpage cross-reference
+       style.

 
                .B comp
                .BR comp ,
 
                .B comp
                .BR comp ,

+               .IR comp (1).

 
 

-       If this is a manpage reference (outside of the SEE ALSO
-       section, which just uses regular text), use:
+       Be careful when referring to programs that are not part of
+       nmh itself.  For commands that are almost guaranteed to be
+       part of the base OS, use a manpage cross-reference (e.g.
+       ".IR cat (1)").  For other third-party utilities, it might
+       be best to set the command name in double quotes. Use your
+       best judgement to make it clear when you're referring to
+       tools that might not be present.

 
 

-               .BR mh-draft (5)

 
 

-SYNPOSIS section
+SYNPOSIS Section

 
 

-       Literal text (such as flags) should be in bold. Parameters
-       should be italicized. Mutually exclusive options (like
-       "-foo" and "-nofoo") should be grouped together and seperated
-       by a "|":
+       Set literal text (such as flags) in bold.  Set parameters
+       in italic.  Mutually exclusive options (like "-foo" and
+       "-nofoo") should be grouped together and separated by a
+       "|":

 
                .RI [ +folder ]              <---- parameter
                .RI [ msgs ]                 <---- parameter
 
                .RI [ +folder ]              <---- parameter
                .RI [ msgs ]                 <---- parameter


@@ -123,19 +121,19 @@ SYNPOSIS section
                .I msg
                argument.
 
                .I msg
                argument.
 

-       In particular, don't enclose them in single quotes (except
-       in the DEFAULT section, which might be inconsistent, but
-       seems a little clearer.
+       In particular, don't enclose them in single quotes.

 
        For "-flag param" situations, try to use a .B/.I combination
        instead of a single .BI, since it allows more flexibility in
        case of punctuation, and we get an automatic space between
        flag and param for free, without having to manual force it.
 
 
        For "-flag param" situations, try to use a .B/.I combination
        instead of a single .BI, since it allows more flexibility in
        case of punctuation, and we get an automatic space between
        flag and param for free, without having to manual force it.
 

+

 Subsections
 
        Use ".SS" to denote a subsection
 
 Subsections
 
        Use ".SS" to denote a subsection
 

+

 Tables
 
        The folder manpage has an example of a table.
 Tables
 
        The folder manpage has an example of a table.


@@ -152,7 +150,21 @@ Tables
        .RE
        .PP
 
        .RE
        .PP
 

-Other italicized text
+
+Environment Variables
+
+       These are always set in roman text.  The surrounding text
+       should make clear you are referring to an environment
+       variable.  In some cases, like when dealing with all-lower-case
+       variable names, setting the name inside double quotes can
+       help clarify the context.
+
+       Never prepend a '$' character to an environment variable
+       name, unless you are directly referring to a variable
+       substitution in, say, a pathname.
+
+
+Other Italicized Text

 
        Italicize file names, profile entries, and folder names:
 
 
        Italicize file names, profile entries, and folder names:
 


@@ -171,3 +183,149 @@ Other italicized text
        Enclose the file names and profile entries in lq/rq
        quotes, too.
 
        Enclose the file names and profile entries in lq/rq
        quotes, too.
 

+
+Relative Indentation
+
+       Use .RS 5 / .RE to indent paragraphs, etc. '.IP 5' can
+       be useful, too.  Try to use an offset of '5' as much as
+       possible to maintain visual consistency.
+
+
+Tagged Lists
+
+       In PROFILE COMPONENTS, DEFAULTS, ENVIRONMENT, and FILES,
+       use tagged paragraphs with an offset of 20.  Do not set
+       the tag in bold or italic, or wrap it in quotes, unless
+       this is absolutely necessary to make the context clear.
+
+               .SH DEFAULTS
+               .PD 0
+               .TP 20
+               +folder
+               defaults to the current folder
+               .TP
+               msgs
+               defaults to
+               .I cur
+               .TP
+               -decodetext 8bit
+               .TP
+               -decodetypes text,application/ics
+               .TP
+               -crlflinebreaks
+               .PD
+               .SH [...]
+
+Source Files
+
+       There should be no ".so" commands to source an external file,
+       since these break on Linux, where the man program does not
+       allow source files outside the man/ hierarchy. Instead, insert
+       this fragment:
+
+               .PP
+               .RS 5
+               .nf
+               %components%
+               .fi
+               .RE
+               .PP
+
+       Of course, replace "components" with a unique identifier that
+       reflects the content being included, like "mts_conf" for
+       etc/mts.conf. Then, add two lines to the man.sed target in
+       Makefile.in like:
+
+               echo '/%components%/r $(top_srcdir)/etc/components' >> $@
+               echo ' s,%components%,,g' >> $@
+
+       At compile time, the contents of the file will physically
+       incorporated into the body of the man page. This is somewhat
+       unfortunate, since later modifications won't be reflected in
+       the manpage, but on the other hand, the manpage will show the
+       default configuration and not local modifications.
+
+
+Pointer Manpages
+
+       Certain manpages are shared between one or more programs
+       (such as folder/folders). The secondary program should
+       have a man page that only contains:
+
+               .so man1/folder.1
+
+       Also, add this manpage to the appropriate section in Makefile.in
+       
+AUTHOR and HISTORY Sections
+
+       These have no place in a manpage.  If you want everlasting
+       glory, try the release notes.  But note that a HISTORY
+       section might be appropriate for documenting incompatibility
+       with older versions of MH.
+
+------------------------------------------------------------------------------
+
+[ This template is a bit behind the times. I will bring it into
+  conformance with the notes above once the notes settle down.
+  --lyndon ]
+
+
+.TH COMP %manext1% "DATE" "%nmhversion%"
+.\"
+.\" %nmhwarning%
+.\"
+.SH NAME
+comp \- compose a message
+.\"
+.SH SYNOPSIS
+.HP 5
+.na
+.B comp 
+.RI [ +folder ]
+.RI [ msgs ]
+.RB [ \-form
+.IR formfile ]
+.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 "PROFILE COMPONENTS"
+.TP 20
+Path
+Location of the user's MH folder directory
+.TP
+moreproc
+The pager command name
+.\"
+.SH DEFAULTS
+.TP 20
+.RI + folder
+defaults to the current folder
+.\"
+.SH CONTEXT
+None
+.\"
+.SH FILES
+.TP 20
+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
+