NMH MANPAGE STYLE GUIDE

nmh manpages should be in this general form:

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

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


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.

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:

		.B comp
		.BR comp ,

	If this is a manpage reference, use:

		.IR mh-draft (5)

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

		.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 (except
	in the DEFAULT section, which might be inconsistent, but
	seems a little clearer.

	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

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.

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
	

CONTEXT
    Don't include a CONTEXT section when contexts are out of context.


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.