DOCS/tech/manpage.txt

   1 ========================================
   2 A documentation about MPlayer's man page
   3 ========================================
   4
   5
   6 About the documentation
   7 -----------------------
   8
   9 Yes it's true: This is the documentation of the documentation (man page).
  10 This guide should be used as a reference for questions about the man page
  11 structure. It's not a strict guide but we recommend following it to get a
  12 uniform man page.
  13
  14
  15
  16 What belongs in the man page?
  17 -----------------------------
  18
  19   - option descriptions (all)
  20   - usage (options, configuration files, controls)
  21   - basic examples
  22
  23
  24
  25 What doesn't belong in the man page?
  26 ------------------------------------
  27
  28   - instructions for installation, encoding and similar processes
  29   - detailed evaluations or hints
  30   - tutorials, guides
  31
  32
  33
  34 How should patches look like?
  35 -----------------------------
  36
  37 Follow the rules in patches.txt, they apply to the man page, too.
  38 Exceptions are:
  39
  40   - Cosmetic patches are allowed but should be done separately from the real
  41     changes, be marked as cosmetic changes and shouldn't change the general
  42     style without reasons/permissions.
  43   - The same applies to spell checking.
  44
  45
  46
  47 How do I create an HTML, text or other version of the man page?
  48 ---------------------------------------------------------------
  49
  50 The man page was more or less designed for groff as it is the main tool for
  51 it. Therefore only groff produces acceptable results without changes.
  52 Additionally, the SS variable should be set to either very low or very high
  53 values to produce a better groff HTML output (Due to a bug of groff2html?).
  54 A setting of 4 should look readable. Here's an overview again:
  55
  56   - groff:
  57     groff is the "official" tool to convert man pages. To get good results you
  58     need a recent version (1.18.2).
  59     groff -mman -Thtml mplayer.1 > mplayer.1.html
  60     groff -mman -Tlatin1 -rLL=78n mplayer.1 | col -bxp > mplayer.1.txt
  61     The groff man page lists other output formats to use with -T.
  62
  63     Unfortunately groff is not able to handle UTF-8 input as of version 1.19.2.
  64     groff-utf8 is a wrapper that works around these deficiencies:
  65       http://www.haible.de/bruno/packages-groff-utf8.html
  66
  67   - man2html:
  68     You can view it through a CGI script:
  69     http://localhost/cgi-bin/man2html?mplayer
  70     The output is unusable as the script doesn't seem to support the macro
  71     definitions. Maybe manually changing all leads to acceptable results.
  72
  73   - rman:
  74     rman -f html mplayer.1 > man_page.rman.html
  75     The output is ugly as rman doesn't understand many of the macros used.
  76
  77   - troffcvt:
  78     troff2html -man mplayer.1 > man_page.tcvt.html
  79     The (good) output is similar to groff but simplified...
  80
  81
  82
  83 The structure
  84 -------------
  85
  86 The option descriptions are divided into sections. Inside a section options are
  87 alphabetically sorted. The sections are:
  88
  89 (Header)
  90     not visible, copyright and author information
  91 (Macro definitions)
  92     not visible, some macro definitions
  93 NAME
  94     The man page is used for both mplayer and mencoder.
  95 SYNOPSIS
  96     a description of MPlayer's playtree
  97 DESCRIPTION
  98     a general description of MPlayer, MEncoder, GMPlayer and their features
  99 INTERACTIVE CONTROL
 100     description of MPlayer's input system and interactive controls
 101 USAGE
 102     some general notes about usage
 103 CONFIGURATION FILES
 104     description of the configuration file format
 105 GENERAL OPTIONS
 106     General options that are common to both MPlayer and MEncoder.
 107 PLAYER OPTIONS (MPLAYER ONLY)
 108     user interface option descriptions (MPlayer only)
 109 DEMUXER/STREAM OPTIONS
 110     demuxer and stream layer option descriptions
 111 OSD/SUBTITLE OPTIONS
 112     This section is special in that it contains all subtitle and OSD option
 113     descriptions even if they might belong to one of the other sections. It
 114     was created because of its size.
 115 AUDIO OUTPUT OPTIONS (MPLAYER ONLY)
 116     audio output layer (ao) option descriptions (MPlayer only)
 117 AUDIO OUTPUT DRIVERS (MPLAYER ONLY)
 118     audio output driver description (ao)
 119 VIDEO OUTPUT OPTIONS (MPLAYER ONLY)
 120     video output layer (vo) option descriptions (MPlayer only)
 121 VIDEO OUTPUT DRIVERS (MPLAYER ONLY)
 122     video output driver description (vo)
 123 DECODING/FILTERING OPTIONS
 124     decoding/filtering layer options (ad, vd, pl)
 125 VIDEO FILTERS
 126     video filter description (vf)
 127 GENERAL ENCODING OPTIONS (MENCODER ONLY)
 128     Encoding option descriptions (ve) (MEncoder only).
 129 CODEC SPECIFIC ENCODING OPTIONS (MENCODER ONLY)
 130     Codec specific option descriptions (lavc,divx4,xvid,lame) (MEncoder only).
 131 FILES
 132     a list and description of all installed/used files/directories
 133 EXAMPLES OF MPLAYER USAGE
 134     basic examples, again: no long descriptions/processes
 135 EXAMPLES OF MENCODER USAGE
 136     basic examples, again: no long descriptions/processes
 137 BUGS
 138 AUTHORS
 139
 140
 141
 142 The man page/groff format
 143 -------------------------
 144
 145 Just read this and RTFS:
 146
 147     man 7 roff
 148     http://www.tldp.org/HOWTO/mini/Man-Page.html
 149     man 7 man
 150     man 7 groff
 151
 152
 153
 154 "Style" guidelines
 155 ------------------
 156
 157 This section was kept simple but there are certain guidelines/rules to get a
 158 uniform man page. The best way is to read (and understand) the source.
 159
 160
 161 General:
 162
 163     - No line should contain more than 79 characters.
 164     - used commands: .TH, .SH, .TP, .IP, .PP, .[R]B, .I, .br, .RS, .RE, .na,
 165                      .nh, .ad, .hy, macro definitions, comments and some more
 166     - Don't forget the quotation marks around expressions, etc...
 167     - Each new sentence should start on a line of its own.
 168     - There is a typographical difference between a hyphen, a minus and an
 169       en-dash or em-dash. For the man page this means that you should put a
 170       backslash before a '-' if it denotes a range (1\-10), an option (\-fs),
 171       stdin (\-), a dash (mplayer \- movie player) or a minus (\-1). Use just
 172       '-' if it is a hyphen (A-V).
 173     - Don't start a line with "'" or ".", nroff treats them specially.
 174     - To quickly check a manual page for markup errors, just run
 175         man DOCS/man/XX/mplayer.1 > /dev/null
 176
 177
 178 Option descriptions:
 179
 180     - Options should be in alphabetical order.
 181     - Option and/or suboption parameters should be short, descriptive and put
 182       in angular brackets (e.g. \-vo <driver>).
 183     - If the option has a parameter in a certain range, specify it right after
 184       the option (e.g. \-subpos <0\-100>).
 185     - Optional things should be put in square brackets ([]).
 186     - Obsolete options are followed by (OBSOLETE), beta options by
 187       (BETA CODE), etc.
 188     - MPlayer-only options in a section which isn't marked this way
 189       are followed by (MPlayer only).
 190     - Add references to other options if they belong to each other, e.g.
 191       '(\-vo zr only)' or '(also see \-alang)' or are commonly used together.
 192     - If a nontrivial default parameter exists, mention it, e.g. (default: 24).
 193     - Put examples and notes at the end of the description (before suboptions).
 194     - The end of the suboptions _always_ has to be followed by a paragraph
 195       (BUG).
 196     - For flag options just document the non-default one of \-XXX and \-noXXX.
 197       If the option is not a flag, describe both, one below the other (this is
 198       an exception to the alphabetical order).
 199
 200
 201 Macro definitions (see beginning of man page):
 202
 203     - .SS     starting value of the suboption column
 204     - .IPs    Add new suboption (we use .TP for normal options and .IP for
 205               the rest).
 206     - .RSs    begin of suboptions, end with .RE
 207     - .RSss   begin of suboptions in a suboption
 208     - .REss   end of suboptions in a suboption
 209
 210
 211 Options, suboptions, examples structure:
 212
 213     - Normal options (note the '<' and '>'):
 214
 215       [...]
 216       .TP
 217       .B \-option <parameter>
 218       description
 219       [...]
 220
 221     - Long suboptions:
 222
 223       [...]
 224       description. Available options are:
 225       .
 226       .RSs
 227       .IPs "subopt1=<value>"
 228       description1
 229       .IPs "subopt2=<value>"
 230       description2
 231       [...]
 232       .IPs "last subopt=<value>"
 233       last description
 234       .RE
 235       .
 236       [...]
 237
 238     - Short suboptions:
 239
 240       [...]
 241       description. Available options are:
 242
 243       .PD 0
 244       .RSs
 245       .IPs "subopt1=<value>"
 246       description1
 247       .IPs "subopt2=<value>"
 248       description2
 249       [...]
 250       .IPs "last subopt=<value>"
 251       last description
 252       .RE
 253       .PD 1
 254       .
 255       [...]
 256
 257     - Suboptions in suboptions:
 258
 259       [...]
 260       .IPs "subopt1=<value>"
 261       description1
 262       .RSss
 263       subsubopt1: description1
 264       .br
 265       subsubopt2: description2
 266       [...]
 267       .REss
 268       [...]
 269
 270     - Examples:
 271
 272       [...]
 273
 274       .I EXAMPLE:
 275       .PD 0
 276       .RSs
 277       .IP "\-option used parameters"
 278       description
 279       [...]
 280       .RE
 281       .PD 1
 282       .
 283       [...]