-NMH MANPAGE STYLE GUIDE
+ NMH MANPAGE STYLE GUIDE
+ =======================
-nmh manpages should be in this general form and section order:
+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% "DATE" "%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 "PROFILE COMPONENTS"
-.TP
-Path
-Location of the user's MH folder directory
-.TP
-moreproc
-The pager command name
-.\"
-.SH DEFAULTS
-.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"
-.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 (no abbreviations or shortcuts):
+Troff Considerations
- January 2, 1904
+ Proper sentences end with a period followed by a newline:
-not the unparseable
+ This is a sentence.
+ It is followed by another, longer, sentence, but
+ which makes no more sense than the previous one.
- 01/02/04
+ not
-Don't abbreviate the month.
+ This is a sentence. It is followed by another,
+ longer, sentence, but which makes no more sense
+ than the previous one.
+ This allows troff to set the correct inter-sentence spacing
+ based on the output device.
-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.
+ 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.
-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.
+
+ 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 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?"
- 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
+Program Names
- 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:
+ 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 ,
+ .IR comp (1).
- If this is a manpage reference, 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
.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.
+
Subsections
Use ".SS" to denote a subsection
+
Tables
The folder manpage has an example of a table.
.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:
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
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.
-CONTEXT
- Don't include a CONTEXT section when contexts are not
- applicable.
+ 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.'.
-AUTHOR and HISTORY sections
+ 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.
- These have no place in a manpage. If you want everlasting glory,
- try the release notes.
+------------------------------------------------------------------------------
-BUGS
+[ 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
- The BUGS section goes last.
projects / nmh / blobdiff