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

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