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