NMH MANPAGE STYLE GUIDE
                     =======================

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


Troff Considerations

	Proper sentences end with a period followed by a newline:

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

	not

		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.

	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.


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?"


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 ,
		.IR comp (1).

	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.


SYNPOSIS Section

	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
		.RB [ \-version ]            <---- flag
		.RB [ \-editor               <---- flag with
		.IR editor ]                       parameter
		.RB [ \-use " | " \-nouse ]  <---- exclusive parameters

	References to these flags or parameters in the body text of the
	manpage should reflect these conventions:

		You may not supply both a
		.B \-form
		.I formfile
		and a
		.I +folder
		or
		.I msg
		argument.

	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.

	.PP
	.RS 5
	.nf
	.ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
	FOLDER  \0\0\0\0\0\0# MESSAGES  RANGE   CUR     (OTHERS)
	ff      has \0no messages.
	inbox+  has \016 messages       (\03\-\022);    cur=\05.
	mh      has \076 messages       (15\-\076);     cur=70.
	.fi
	.RE
	.PP


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:

		If a file named
		.RI \*(lq components \*(rq
		exists in the user's nmh directory,

		If the user's profile contains a
		.RI \*(lq "Msg\-Protect: nnn" \*(rq
		entry, it

		The \*(lq+\*(rq after
		.I inbox
		indicates that it is the current folder.

	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.

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