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 .\"
   6 .\" %nmhwarning%
   7 .\" $Id$
   8 .\"
   9 .TH COMP %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
  10 .SH NAME
  11 comp \- compose a message
  12 .SH SYNOPSIS
  13 .HP 5
  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 .SH DESCRIPTION
  23 .B Comp
  24 is used to create a new message to be mailed.  It copies something.
  25
  26 .SH FILES
  27 .fc ^ ~
  28 .nf
  29 .ta \w'/usr/local/nmh/etc/ExtraBigFileName  'u
  30 ^%etcdir%/components~^The standard message skeleton
  31
  32 .SH "PROFILE COMPONENTS"
  33 .fc ^ ~
  34 .nf
  35 .ta 2.4i
  36 .ta \w'ExtraBigProfileName  'u
  37 ^Path:~^To determine the user's nmh directory
  38
  39 .SH "SEE ALSO"
  40 dist(1), forw(1), repl(1), send(1), whatnow(1), mh-profile(5)
  41
  42 .SH DEFAULTS
  43 .nf
  44 .RB ` +folder "' defaults to the current folder"
  45
  46 .SH CONTEXT
  47 None
  48
  49 .SH BUGS
  50 None
  51
  52 ---------------------------------------
  53 In the FILES section, use a spacer of "/usr/local/nmh/etc" for now,
  54 we'll parametrize that into %etcdir% later.
  55
  56
  57 Source files
  58
  59         There should be no ".so" commands to source an external file,
  60         since these break on Linux, where the man program does not
  61         allow source files outside the man/ hierarchy. Instead, insert
  62         this fragment:
  63
  64                 .PP
  65                 .RS 5
  66                 .nf
  67                 %components%
  68                 .fi
  69                 .RE
  70                 .PP
  71
  72         Of course, replace "components" with a unique identifier that
  73         reflects the content being included, like "mts_conf" for
  74         etc/mts.conf. Then, add two lines to the man.sed target in
  75         Makefile.in like:
  76
  77                 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
  78                 echo ' s,%components%,,g' >> $@
  79
  80         At compile time, the contents of the file will physically
  81         incorporated into the body of the man page. This is somewhat
  82         unfortunate, since later modifications won't be reflected in
  83         the manpage, but on the other hand, the manpage will show the
  84         default configuration and not local modifications.
  85
  86 Program names
  87
  88         All nmh program names should be bolded. If there is punctuation
  89         after the name, use a .BR construct to avoid the automatic
  90         space that's inserted with just a .B:
  91
  92                 .B comp
  93                 .BR comp ,
  94
  95         If this is a manpage reference (outside of the SEE ALSO
  96         section, which just uses regular text), use:
  97
  98                 .BR mh-draft (5)
  99
 100 SYNPOSIS section
 101
 102         Literal text (such as flags) should be in bold. Parameters
 103         should be italicized. Mutually exclusive options (like
 104         "-foo" and "-nofoo") should be grouped together and seperated
 105         by a "|":
 106
 107                 .RI [ +folder ]              <---- parameter
 108                 .RI [ msgs ]                 <---- parameter
 109                 .RB [ \-version ]            <---- flag
 110                 .RB [ \-editor               <---- flag with
 111                 .IR editor ]                       parameter
 112                 .RB [ \-use " | " \-nouse ]  <---- exclusive parameters
 113
 114         References to these flags or parameters in the body text of the
 115         manpage should reflect these conventions:
 116
 117                 You may not supply both a
 118                 .B \-form
 119                 .I formfile
 120                 and a
 121                 .I +folder
 122                 or
 123                 .I msg
 124                 argument.
 125
 126         In particular, don't enclose them in single quotes (except
 127         in the DEFAULT section, which might be inconsistent, but
 128         seems a little clearer.
 129
 130         For "-flag param" situations, try to use a .B/.I combination
 131         instead of a single .BI, since it allows more flexibility in
 132         case of punctuation, and we get an automatic space between
 133         flag and param for free, without having to manual force it.
 134
 135 Subsections
 136
 137         Use ".SS" to denote a subsection
 138
 139 Tables
 140
 141         The folder manpage has an example of a table.
 142
 143         .PP
 144         .RS 5
 145         .nf
 146         .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
 147         FOLDER  \0\0\0\0\0\0# MESSAGES  RANGE   CUR     (OTHERS)
 148         ff      has \0no messages.
 149         inbox+  has \016 messages       (\03\-\022);    cur=\05.
 150         mh      has \076 messages       (15\-\076);     cur=70.
 151         .fi
 152         .RE
 153         .PP
 154
 155 Other italicized text
 156
 157         Italicize file names, profile entries, and folder names:
 158
 159                 If a file named
 160                 .RI \*(lq components \*(rq
 161                 exists in the user's nmh directory,
 162
 163                 If the user's profile contains a
 164                 .RI \*(lq "Msg\-Protect: nnn" \*(rq
 165                 entry, it
 166
 167                 The \*(lq+\*(rq after
 168                 .I inbox
 169                 indicates that it is the current folder.
 170
 171         Enclose the file names and profile entries in lq/rq
 172         quotes, too.
 173
 174 Pointer manpages
 175
 176         Certain manpages are shared between one or more programs
 177         (such as folder/folders). The secondary program should
 178         have a man page that only contains:
 179
 180                 .so man1/folder.1
 181
 182         Also, add this manpage to the appropriate section in Makefile.in