Mercurial > mplayer.hg
annotate DOCS/tech/manpage.txt @ 28287:dbebb78dda3c
Add VDPAU hardware accelerated decoding for MPEG1 and MPEG2 which will
be used by MPlayer.
Original patch by NVIDIA corporation.
author | cehoyos |
---|---|
date | Fri, 16 Jan 2009 02:14:25 +0000 |
parents | d9afff01e632 |
children |
rev | line source |
---|---|
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
1 ======================================== |
7286 | 2 A documentation about MPlayer's man page |
3 ======================================== | |
4 | |
5 | |
6 About the documentation | |
7 ----------------------- | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
8 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
9 Yes it's true: This is the documentation of the documentation (man page). |
7286 | 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 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
15 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
16 What belongs in the man page? |
7286 | 17 ----------------------------- |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
18 |
19920 | 19 - option descriptions (all) |
20 - usage (options, configuration files, controls) | |
21 - basic examples | |
7286 | 22 |
23 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
24 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
25 What doesn't belong in the man page? |
7286 | 26 ------------------------------------ |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
27 |
19920 | 28 - instructions for installation, encoding and similar processes |
29 - detailed evaluations or hints | |
30 - tutorials, guides | |
7286 | 31 |
32 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
33 |
7286 | 34 How should patches look like? |
35 ----------------------------- | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
36 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
37 Follow the rules in patches.txt, they apply to the man page, too. |
7286 | 38 Exceptions are: |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
39 |
19920 | 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. | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
44 |
7286 | 45 |
46 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
47 How do I create an HTML, text or other version of the man page? |
7741 | 48 --------------------------------------------------------------- |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
49 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
50 The man page was more or less designed for groff as it is the main tool for |
7286 | 51 it. Therefore only groff produces acceptable results without changes. |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
52 Additionally, the SS variable should be set to either very low or very high |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
53 values to produce a better groff HTML output (Due to a bug of groff2html?). |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
54 A setting of 4 should look readable. Here's an overview again: |
7289 | 55 |
20568 | 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 | |
20569
02de8bb9bbba
The col utility eats non-ASCII characters without the -p option it seems.
diego
parents:
20568
diff
changeset
|
60 groff -mman -Tlatin1 -rLL=78n mplayer.1 | col -bxp > mplayer.1.txt |
20568 | 61 The groff man page lists other output formats to use with -T. |
11561 | 62 |
20568 | 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 | |
20567 | 66 |
20568 | 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. | |
11561 | 72 |
20568 | 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. | |
11561 | 76 |
20568 | 77 - troffcvt: |
78 troff2html -man mplayer.1 > man_page.tcvt.html | |
79 The (good) output is similar to groff but simplified... | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
80 |
7286 | 81 |
82 | |
83 The structure | |
84 ------------- | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
85 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
86 The option descriptions are divided into sections. Inside a section options are |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
87 alphabetically sorted. The sections are: |
7286 | 88 |
89 (Header) | |
19920 | 90 not visible, copyright and author information |
7286 | 91 (Macro definitions) |
19920 | 92 not visible, some macro definitions |
7286 | 93 NAME |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
94 The man page is used for both mplayer and mencoder. |
7286 | 95 SYNOPSIS |
19920 | 96 a description of MPlayer's playtree |
7286 | 97 DESCRIPTION |
19920 | 98 a general description of MPlayer, MEncoder, GMPlayer and their features |
16688
ad9c4e9ca5bd
Keyboard control section renamed to interactive control, small structure change.
diego
parents:
15703
diff
changeset
|
99 INTERACTIVE CONTROL |
19920 | 100 description of MPlayer's input system and interactive controls |
11944 | 101 USAGE |
19920 | 102 some general notes about usage |
17310 | 103 CONFIGURATION FILES |
19920 | 104 description of the configuration file format |
11944 | 105 GENERAL OPTIONS |
106 General options that are common to both MPlayer and MEncoder. | |
7286 | 107 PLAYER OPTIONS (MPLAYER ONLY) |
19920 | 108 user interface option descriptions (MPlayer only) |
7286 | 109 DEMUXER/STREAM OPTIONS |
19920 | 110 demuxer and stream layer option descriptions |
19047 | 111 OSD/SUBTITLE OPTIONS |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
112 This section is special in that it contains all subtitle and OSD option |
19920 | 113 descriptions even if they might belong to one of the other sections. It |
114 was created because of its size. | |
7286 | 115 AUDIO OUTPUT OPTIONS (MPLAYER ONLY) |
19920 | 116 audio output layer (ao) option descriptions (MPlayer only) |
12468 | 117 AUDIO OUTPUT DRIVERS (MPLAYER ONLY) |
19920 | 118 audio output driver description (ao) |
7286 | 119 VIDEO OUTPUT OPTIONS (MPLAYER ONLY) |
19920 | 120 video output layer (vo) option descriptions (MPlayer only) |
12716
296b1f6f6bf7
VIDEO OUTPUT DRIVERS moved right after VIDEO OUTPUT OPTIONS.
diego
parents:
12468
diff
changeset
|
121 VIDEO OUTPUT DRIVERS (MPLAYER ONLY) |
19920 | 122 video output driver description (vo) |
7286 | 123 DECODING/FILTERING OPTIONS |
19920 | 124 decoding/filtering layer options (ad, vd, pl) |
10218
f82646fc1431
Moved video filters to a separate section, moved slave mode section to the
jonas
parents:
8699
diff
changeset
|
125 VIDEO FILTERS |
19920 | 126 video filter description (vf) |
10380
8627ec205af8
moved -af options to the filter section (should work with mencoder), split encoding options in general and codec specific part, some small (cosmetic) changes
jonas
parents:
10227
diff
changeset
|
127 GENERAL ENCODING OPTIONS (MENCODER ONLY) |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
128 Encoding option descriptions (ve) (MEncoder only). |
10380
8627ec205af8
moved -af options to the filter section (should work with mencoder), split encoding options in general and codec specific part, some small (cosmetic) changes
jonas
parents:
10227
diff
changeset
|
129 CODEC SPECIFIC ENCODING OPTIONS (MENCODER ONLY) |
8627ec205af8
moved -af options to the filter section (should work with mencoder), split encoding options in general and codec specific part, some small (cosmetic) changes
jonas
parents:
10227
diff
changeset
|
130 Codec specific option descriptions (lavc,divx4,xvid,lame) (MEncoder only). |
7286 | 131 FILES |
19920 | 132 a list and description of all installed/used files/directories |
17062
007826f61f58
Sync man page structure description with actual man page structure.
diego
parents:
16688
diff
changeset
|
133 EXAMPLES OF MPLAYER USAGE |
19920 | 134 basic examples, again: no long descriptions/processes |
17062
007826f61f58
Sync man page structure description with actual man page structure.
diego
parents:
16688
diff
changeset
|
135 EXAMPLES OF MENCODER USAGE |
19920 | 136 basic examples, again: no long descriptions/processes |
7286 | 137 BUGS |
138 AUTHORS | |
139 | |
140 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
141 |
7286 | 142 The man page/groff format |
143 ------------------------- | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
144 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
145 Just read this and RTFS: |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
146 |
11561 | 147 man 7 roff |
7286 | 148 http://www.tldp.org/HOWTO/mini/Man-Page.html |
149 man 7 man | |
150 man 7 groff | |
151 | |
152 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
153 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
154 "Style" guidelines |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
155 ------------------ |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
156 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
157 This section was kept simple but there are certain guidelines/rules to get a |
7286 | 158 uniform man page. The best way is to read (and understand) the source. |
159 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
160 |
7286 | 161 General: |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
162 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
163 - No line should contain more than 79 characters. |
19920 | 164 - used commands: .TH, .SH, .TP, .IP, .PP, .[R]B, .I, .br, .RS, .RE, .na, |
7744
6d41f5e905e2
reversed some changes as they produced ugly html output
jonas
parents:
7742
diff
changeset
|
165 .nh, .ad, .hy, macro definitions, comments and some more |
11099 | 166 - Don't forget the quotation marks around expressions, etc... |
167 - Each new sentence should start on a line of its own. | |
24872
eff35a417aea
Explain the difference between '-' and '\-', correctly now.
diego
parents:
24871
diff
changeset
|
168 - There is a typographical difference between a hyphen, a minus and an |
eff35a417aea
Explain the difference between '-' and '\-', correctly now.
diego
parents:
24871
diff
changeset
|
169 en-dash or em-dash. For the man page this means that you should put a |
eff35a417aea
Explain the difference between '-' and '\-', correctly now.
diego
parents:
24871
diff
changeset
|
170 backslash before a '-' if it denotes a range (1\-10), an option (\-fs), |
24876 | 171 stdin (\-), a dash (mplayer \- movie player) or a minus (\-1). Use just |
24872
eff35a417aea
Explain the difference between '-' and '\-', correctly now.
diego
parents:
24871
diff
changeset
|
172 '-' if it is a hyphen (A-V). |
12864 | 173 - Don't start a line with "'" or ".", nroff treats them specially. |
19879
def3e3fbb458
Add hint about how to check man pages for markup errors.
diego
parents:
19047
diff
changeset
|
174 - To quickly check a manual page for markup errors, just run |
def3e3fbb458
Add hint about how to check man pages for markup errors.
diego
parents:
19047
diff
changeset
|
175 man DOCS/man/XX/mplayer.1 > /dev/null |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
176 |
19920 | 177 |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
178 Option descriptions: |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
179 |
11303 | 180 - Options should be in alphabetical order. |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
181 - Option and/or suboption parameters should be short, descriptive and put |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
182 in angular brackets (e.g. \-vo <driver>). |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
183 - If the option has a parameter in a certain range, specify it right after |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
184 the option (e.g. \-subpos <0\-100>). |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
185 - Optional things should be put in square brackets ([]). |
7286 | 186 - Obsolete options are followed by (OBSOLETE), beta options by |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
187 (BETA CODE), etc. |
19920 | 188 - MPlayer-only options in a section which isn't marked this way |
12744 | 189 are followed by (MPlayer only). |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
190 - Add references to other options if they belong to each other, e.g. |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
191 '(\-vo zr only)' or '(also see \-alang)' or are commonly used together. |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
192 - If a nontrivial default parameter exists, mention it, e.g. (default: 24). |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
193 - Put examples and notes at the end of the description (before suboptions). |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
194 - The end of the suboptions _always_ has to be followed by a paragraph |
7289 | 195 (BUG). |
24870 | 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). | |
7286 | 199 |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
200 |
7286 | 201 Macro definitions (see beginning of man page): |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
202 |
19920 | 203 - .SS starting value of the suboption column |
7286 | 204 - .IPs Add new suboption (we use .TP for normal options and .IP for |
19920 | 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 | |
7286 | 209 |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
210 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
211 Options, suboptions, examples structure: |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
212 |
7286 | 213 - Normal options (note the '<' and '>'): |
214 | |
215 [...] | |
216 .TP | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
217 .B \-option <parameter> |
7286 | 218 description |
219 [...] | |
220 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
221 - Long suboptions: |
7286 | 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 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
238 - Short suboptions: |
7289 | 239 |
240 [...] | |
241 description. Available options are: | |
242 | |
10702 | 243 .PD 0 |
7289 | 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 | |
10702 | 253 .PD 1 |
7289 | 254 . |
255 [...] | |
256 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
257 - Suboptions in suboptions: |
7286 | 258 |
259 [...] | |
260 .IPs "subopt1=<value>" | |
261 description1 | |
262 .RSss | |
263 subsubopt1: description1 | |
264 .br | |
265 subsubopt2: description2 | |
266 [...] | |
267 .REss | |
268 [...] | |
269 | |
7741 | 270 - Examples: |
7286 | 271 |
272 [...] | |
12744 | 273 |
7286 | 274 .I EXAMPLE: |
275 .PD 0 | |
276 .RSs | |
24870 | 277 .IP "\-option used parameters" |
7286 | 278 description |
279 [...] | |
280 .RE | |
281 .PD 1 | |
7289 | 282 . |
7286 | 283 [...] |