Initial import of MPlayer SVN rev 28382 and FFmpeg SVN rev 16846.
[vaapi:miks-mplayer.git] / 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       [...]