diplodocus.org Git - nmh/blob - docs/README.manpages

   1 NMH MANPAGE STYLE GUIDE
   2
   3 nmh manpages should be in this general form:
   4
   5 .TH COMP %manext1% "DATE" "%nmhversion%"
   6 .\"
   7 .\" %nmhwarning%
   8 .\"
   9 .SH NAME
  10 comp \- compose a message
  11 .SH SYNOPSIS
  12 .HP 5
  13 .na
  14 .B comp
  15 .RI [ +folder ]
  16 .RI [ msgs ]
  17 .RB [ \-form
  18 .IR formfile ]
  19 .RB [ \-use " | " \-nouse ]
  20 .RB [ \-version ]
  21 .RB [ \-help ]
  22 .ad
  23 .SH DESCRIPTION
  24 .B Comp
  25 is used to create a new message to be mailed.  It copies something.
  26 .SH FILES
  27 .TP
  28 filename1
  29 description of filename1
  30 .TP
  31 filename2
  32 description of filename2
  33 .SH "PROFILE COMPONENTS"
  34 .TP
  35 Path
  36 Location of the user's MH folder directory
  37 .TP
  38 moreproc
  39 The pager command name
  40 .SH "SEE ALSO"
  41 .IR dist (1),
  42 .IR forw (1),
  43 .IR repl (1),
  44 .IR send (1),
  45 .IR whatnow (1),
  46 .IR mh-profile (5)
  47 .SH DEFAULTS
  48 .TP
  49 .RI + folder
  50 defaults to the current folder
  51 .\"
  52 .SH CONTEXT
  53 None
  54 .\" Leave out the BUGS section if there are none worth describing.
  55 .SH BUGS
  56 None
  57
  58 ---------------------------------------
  59 The DATE in the .TH macro should reflect the most recent non-trivial
  60 update to the content of the manpage; formatting changes don't count.
  61 Spell out the date (no abbreviations or shortcuts):
  62
  63   January 2, 1904
  64
  65 not the unparseable
  66
  67   01/02/04
  68
  69 Don't abbreviate the month.
  70
  71
  72 In the FILES section, prefer the default .TP indent. The pathnames are
  73 variable and long, so any indentation value that works for you won't
  74 work for someone else.
  75
  76
  77 Source files
  78
  79         There should be no ".so" commands to source an external file,
  80         since these break on Linux, where the man program does not
  81         allow source files outside the man/ hierarchy. Instead, insert
  82         this fragment:
  83
  84                 .PP
  85                 .RS 5
  86                 .nf
  87                 %components%
  88                 .fi
  89                 .RE
  90                 .PP
  91
  92         Of course, replace "components" with a unique identifier that
  93         reflects the content being included, like "mts_conf" for
  94         etc/mts.conf. Then, add two lines to the man.sed target in
  95         Makefile.in like:
  96
  97                 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
  98                 echo ' s,%components%,,g' >> $@
  99
 100         At compile time, the contents of the file will physically
 101         incorporated into the body of the man page. This is somewhat
 102         unfortunate, since later modifications won't be reflected in
 103         the manpage, but on the other hand, the manpage will show the
 104         default configuration and not local modifications.
 105
 106 Program names
 107
 108         All nmh program names should be bolded. If there is punctuation
 109         after the name, use a .BR construct to avoid the automatic
 110         space that's inserted with just a .B:
 111
 112                 .B comp
 113                 .BR comp ,
 114
 115         If this is a manpage reference, use:
 116
 117                 .IR mh-draft (5)
 118
 119 SYNPOSIS section
 120
 121         Literal text (such as flags) should be in bold. Parameters
 122         should be italicized. Mutually exclusive options (like
 123         "-foo" and "-nofoo") should be grouped together and seperated
 124         by a "|":
 125
 126                 .RI [ +folder ]              <---- parameter
 127                 .RI [ msgs ]                 <---- parameter
 128                 .RB [ \-version ]            <---- flag
 129                 .RB [ \-editor               <---- flag with
 130                 .IR editor ]                       parameter
 131                 .RB [ \-use " | " \-nouse ]  <---- exclusive parameters
 132
 133         References to these flags or parameters in the body text of the
 134         manpage should reflect these conventions:
 135
 136                 You may not supply both a
 137                 .B \-form
 138                 .I formfile
 139                 and a
 140                 .I +folder
 141                 or
 142                 .I msg
 143                 argument.
 144
 145         In particular, don't enclose them in single quotes (except
 146         in the DEFAULT section, which might be inconsistent, but
 147         seems a little clearer.
 148
 149         For "-flag param" situations, try to use a .B/.I combination
 150         instead of a single .BI, since it allows more flexibility in
 151         case of punctuation, and we get an automatic space between
 152         flag and param for free, without having to manual force it.
 153
 154 Subsections
 155
 156         Use ".SS" to denote a subsection
 157
 158 Tables
 159
 160         The folder manpage has an example of a table.
 161
 162         .PP
 163         .RS 5
 164         .nf
 165         .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
 166         FOLDER  \0\0\0\0\0\0# MESSAGES  RANGE   CUR     (OTHERS)
 167         ff      has \0no messages.
 168         inbox+  has \016 messages       (\03\-\022);    cur=\05.
 169         mh      has \076 messages       (15\-\076);     cur=70.
 170         .fi
 171         .RE
 172         .PP
 173
 174 Other italicized text
 175
 176         Italicize file names, profile entries, and folder names:
 177
 178                 If a file named
 179                 .RI \*(lq components \*(rq
 180                 exists in the user's nmh directory,
 181
 182                 If the user's profile contains a
 183                 .RI \*(lq "Msg\-Protect: nnn" \*(rq
 184                 entry, it
 185
 186                 The \*(lq+\*(rq after
 187                 .I inbox
 188                 indicates that it is the current folder.
 189
 190         Enclose the file names and profile entries in lq/rq
 191         quotes, too.
 192
 193 Pointer manpages
 194
 195         Certain manpages are shared between one or more programs
 196         (such as folder/folders). The secondary program should
 197         have a man page that only contains:
 198
 199                 .so man1/folder.1
 200
 201         Also, add this manpage to the appropriate section in Makefile.in
 202
 203
 204 CONTEXT
 205     Don't include a CONTEXT section when contexts are out of context.
 206
 207
 208 AUTHOR and HISTORY sections
 209
 210     These have no place in a manpage.  If you want everlasting glory,
 211     try the release notes.
 212
 213 BUGS
 214
 215     The BUGS section goes last.