debian/manpage.example

   1 .\" Based on template /usr/share/man-db/examples/manpage.example provided by
   2 .\" Tom Christiansen <tchrist@jhereg.perl.com>.
   3 .\"
   4 .\" vim: set syn=nroff:
   5 .TH FOO SECTION
   6 .SH NAME
   7 foo, bar \- programs to do something
   8 .SH SYNOPSIS
   9 .PP
  10 .B foo
  11 {
  12 .BR this | that
  13 }
  14 [
  15 .B -flags
  16 ]
  17 [
  18 .B \-o
  19 .I option
  20 ]
  21 .I argument
  22 [
  23 .I more...
  24 ]
  25 .SH DESCRIPTION
  26 .\" Putting a newline after each sentence can generate better output.
  27 Long drawn-out discussion of the program.
  28 It's a good idea to break this up into subsections using the .SS macro,
  29 like these:
  30 .SS "A Sample Subsection"
  31 .SS "Yet Another Sample Subsection"
  32 References to the
  33 .BR foo (SECTION)
  34 (or other) manual page should use the .BR macro as here.
  35 .PP
  36 Use the .PP macro to start a new paragraph within a section.
  37 .SH OPTIONS
  38 Some people make this separate from the description.
  39 The following style is typically used to document options:
  40 .TP
  41 .BR this | that
  42 The user MUST specify either
  43 .B this
  44 or
  45 .B that
  46 to run the program.
  47 The { and } braces mean one of the enclosed is required.
  48 The bar (|) separates exclusive options (i.e. you cannot have both at once).
  49 .TP
  50 .B \-o
  51 Pass the user-supplied
  52 .I option
  53 to
  54 .B foo
  55 to change its behaviour.
  56 The fact that
  57 .I option
  58 is underlined or in italics means that the user replaces it with a valid
  59 value for this option.
  60 The [ and ] brackets mean it isn't required.
  61 .IP
  62 Use \(oq\e-\(cq rather than \(oq-\(cq for dashes in command-line options.
  63 \(oq-\(cq means hyphen, and formats differently when using certain output
  64 devices.
  65 .TP
  66 .I argument
  67 The last
  68 .I argument
  69 is required, because it is not in brackets.
  70 .TP
  71 .I more
  72 means that the user can optionally specify additional arguments at the end.
  73 The ellipses (...) indicate one or more of this parameter is allowed.
  74 .SH "RETURN VALUE"
  75 What the program or function returns if successful.
  76 .SH ERRORS
  77 Return codes, either exit status or errno settings.
  78 .SH EXAMPLES
  79 Give some example uses of the program.
  80 .SH ENVIRONMENT
  81 Environment variables this program might care about.
  82 .SH FILES
  83 All files used by the program.
  84 Typical usage is like this:
  85 .br
  86 .nf
  87 .\" set tabstop to longest possible filename, plus a wee bit
  88 .ta \w'/usr/lib/perl/getopts.pl   'u
  89 \fI/usr/man\fR  default man tree
  90 \fI/usr/man/man*/*.*\fR unformatted (nroff source) man pages
  91 .SH NOTES
  92 Miscellaneous commentary.
  93 .SH CAVEATS
  94 Things to take special care with, sometimes called WARNINGS.
  95 .SH DIAGNOSTICS
  96 All the possible error messages the program can print out,
  97 what they mean, and how to correct them if applicable.
  98 .SH BUGS
  99 Things that are broken or just don't work quite right.
 100 .SH RESTRICTIONS
 101 Bugs you don't plan to fix. :-)
 102 .SH AUTHOR
 103 Who wrote it (or AUTHORS if multiple).
 104 .SH HISTORY
 105 Programs derived from other sources sometimes have this.
 106 .SH "SEE ALSO"
 107 .\" Always quote multiple words for .SH
 108 Other man pages to check out, like
 109 .BR man (1),
 110 .BR man (7),
 111 .BR mandb (8),
 112 .BR catman (8).