sbr/m_popen.c: Move prototypes from h/prototypes.h to new header.

[nmh] / docs / README.manpages

diff --git a/docs/README.manpages b/docs/README.manpages
index 8c6516a57dcf8b61373faef6cb6582d887fc9ffd..f5a802afa47857ab8715c3572ae2678fe94a659e 100644 (file)
--- a/docs/README.manpages
+++ b/docs/README.manpages
@@ -1,112 +1,99 @@
-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).

 
 

-.TH COMP %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
-.\"
-.\" %nmhwarning%
-.\"
-.SH NAME
-comp \- compose a message
-.SH SYNOPSIS
-.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
-.TP
-filename1
-description of filename1
-.TP
-filename2
-description of filename2
-.SH "PROFILE COMPONENTS"
-.TP
-Path
-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
-defaults to the current folder
-.\"
-.SH CONTEXT
-None
-.\" Leave out the BUGS section if there are none worth describing.
-.SH BUGS
-None

 
 

----------------------------------------
-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.
+Troff Considerations

 
 

+       Proper sentences end with a period followed by a newline:

 
 

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

 
 

-       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:
+       not

 
 

-               .PP
-               .RS 5
-               .nf
-               %components%
-               .fi
-               .RE
-               .PP
+               This is a sentence.  It is followed by another,
+               longer, sentence, but which makes no more sense
+               than the previous one.

 
 

-       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:
+       This allows troff to set the correct inter-sentence spacing
+       based on the output device.

 
 

-               echo '/%components%/r $(top_srcdir)/etc/components' >> $@
-               echo ' s,%components%,,g' >> $@
+       When quoting, use \*(lq and \*(rq. This ensures correct
+       formatting on typesetter-like devices.
+
+        A man page's source is ASCII, not UTF-8.  troff has escapes for
+        non-ASCII characters, e.g. \(em for an em-dash, U+2014, that are
+        mapped onto whatever the output device supports, e.g. UTF-8 or
+        PDF.
+
+
+Section Ordering
+
+       Always present sections in the following order:
+
+               NAME [*]
+               SYNOPSIS [*]
+               DESCRIPTION [*]
+               PROFILE COMPONENTS
+               DEFAULTS
+               CONTEXT
+               ENVIRONMENT
+               FILES
+               EXAMPLES
+               DIAGNOSTICS [*]
+               SEE ALSO
+               HISTORY
+               BUGS 
+
+       Sections marked with a [*] are mandatory.  Only include
+       the others if they are specifically applicable.
+
+       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.

 
 

-       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.

 
 

-Program names
+Dates

 
 

-       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:
+        The DATE in the .TH macro is in `yyyy-mm-dd' format, and should
+        reflect the most recent *non-trivial* update to the *content* of
+        the manpage; formatting changes don't count, nor does expanding
+        the `SEE ALSO' list.  Ask "Would the familiar user wish to
+        re-read this page to learn of this change?"
+
+
+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.

 
 

-               .IR 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


@@ -127,19 +114,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.


@@ -156,7 +143,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:
 


@@ -175,7 +176,70 @@ 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.
 

-Pointer manpages
+
+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
 
        Certain manpages are shared between one or more programs
        (such as folder/folders). The secondary program should


@@ -184,3 +248,106 @@ 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

+       
+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.
+
+Common errors and subjective conventions
+
+        Try to mention `nmh' in the NAME section if it's not too awkward.
+        The command-line `-foo' is an option, not a switch.
+        Describe the default behaviour, then how it can be altered,
+            e.g. an option.
+        It's `see foo(1)', not `see the foo(1) man page for more detail'.
+        Emails have `From' and `Date' headers, not `From:' and `Date:'.
+        An mbox-format file has `"From "' envelope-address headers.
+
+        A hyphen is input as an ASCII minus sign, `non-standard',
+            not as `\-' which is the input to output a minus sign.
+        Use an unbreakable space for RFCs: `RFC\ 822'.
+        Hyphenate compound adjectives, e.g. `mail-drop format'.
+        Don't SHOUT for emphasis.
+            Use `.I' for normal emphasis and `.B' for strongest.
+
+        Use `Unix', not `UNIX'.
+        Use `user ID' and `group ID', not `user-id'.
+        Use `zeroed', not `zero'd'.
+        Use `mail drop', not `maildrop' or `drop box'.
+        Use `messages', not `message(s)', ditto `folders', etc.
+        Use `e.g.', not `eg.', and `i.e.', not `ie.'.
+
+        Use a pair of commas, like this, for parenthetical asides.
+        Use `that' when the clause is essential, without a comma.
+            Use comma then `which' when it's non-essential.
+        `Hence' means `from here';  it's `thus' to introduce a conclusion.
+
+------------------------------------------------------------------------------
+
+[ 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
+