Mercurial > mplayer.hg
annotate DOCS/tech/manpage.txt @ 14561:a226d301eec1
Handle missing palettes in the info part of VobSubs in Matroska files correctly by giving mplayer a NULL pointer. This way it will use a default palette instead of black only. Patch by Csillag Kristof (fenwick () freemail ! hu)
author | mosu |
---|---|
date | Fri, 21 Jan 2005 18:25:44 +0000 |
parents | 1916851d90a3 |
children | e7f1ce608789 |
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 |
7286 | 19 - option descriptions (all) |
11561 | 20 - usage (options, configuration files, controls) |
7286 | 21 - basic examples |
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 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
28 - instructions for installation, encoding and similar processes |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
29 - detailed evaluations or hints |
7286 | 30 - tutorials, guides |
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 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
40 - Cosmetic patches are allowed but should be done separately from the real |
7286 | 41 changes, be marked as cosmetic changes and shouldn't change the general |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
42 style without reasons/permissions. |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
43 - The same applies to spell checking. |
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 |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
56 - groff: Groff is the "official" tool to convert man pages. |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
57 To get good results you need a recent version (1.18.2). |
13380
1916851d90a3
Use the same names as on mphq for the generated man pages.
diego
parents:
13140
diff
changeset
|
58 groff -m man -T html mplayer.1 > mplayer.1.html |
1916851d90a3
Use the same names as on mphq for the generated man pages.
diego
parents:
13140
diff
changeset
|
59 groff -m man -T latin1 -rLL=78n mplayer.1 | col -bx > mplayer.1.txt |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
60 The groff man page lists other output formats to use with -T. |
11561 | 61 |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
62 - man2html: You can view it through a CGI script: |
7286 | 63 http://localhost/cgi-bin/man2html?mplayer |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
64 The output is unusable as the script doesn't seem to support |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
65 the macro definitions. Maybe manually changing all leads to |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
66 acceptable results. |
11561 | 67 |
68 - rman: rman -f html mplayer.1 > man_page.rman.html | |
7741 | 69 The output is ugly as rman doesn't understand many of the |
70 macros used. | |
11561 | 71 |
72 - troffcvt: troff2html -man mplayer.1 > man_page.tcvt.html | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
73 The (good) output is similar to groff but simplified... |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
74 |
7286 | 75 |
76 | |
77 The structure | |
78 ------------- | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
79 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
80 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
|
81 alphabetically sorted. The sections are: |
7286 | 82 |
83 (Header) | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
84 Not visible, copyright and author information. |
7286 | 85 (Macro definitions) |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
86 Not visible, some macro definitions. |
7286 | 87 NAME |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
88 The man page is used for both mplayer and mencoder. |
7286 | 89 SYNOPSIS |
90 A description of MPlayer's playtree. | |
91 DESCRIPTION | |
92 A general description of MPlayer, MEncoder, GMPlayer and its features. | |
11944 | 93 KEYBOARD CONTROL |
94 A description of MPlayer's input system and the default keyboard controls. | |
95 USAGE | |
7286 | 96 Some general notes about the options and a description of the config file |
97 format. | |
11944 | 98 GENERAL OPTIONS |
99 General options that are common to both MPlayer and MEncoder. | |
7286 | 100 PLAYER OPTIONS (MPLAYER ONLY) |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
101 User interface option descriptions (MPlayer only). |
7286 | 102 DEMUXER/STREAM OPTIONS |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
103 Demuxer and stream layer option descriptions. |
7286 | 104 OSD/SUB OPTIONS |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
105 This section is special in that it contains all subtitle and OSD option |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
106 descriptions even if they might belong to one of the other sections. It was |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
107 created because of its size. |
7286 | 108 AUDIO OUTPUT OPTIONS (MPLAYER ONLY) |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
109 Audio output layer (ao) option descriptions (MPlayer only). |
12468 | 110 AUDIO OUTPUT DRIVERS (MPLAYER ONLY) |
111 Audio output driver description (ao) | |
7286 | 112 VIDEO OUTPUT OPTIONS (MPLAYER ONLY) |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
113 Video output layer (vo) option descriptions (MPlayer only). |
12716
296b1f6f6bf7
VIDEO OUTPUT DRIVERS moved right after VIDEO OUTPUT OPTIONS.
diego
parents:
12468
diff
changeset
|
114 VIDEO OUTPUT DRIVERS (MPLAYER ONLY) |
296b1f6f6bf7
VIDEO OUTPUT DRIVERS moved right after VIDEO OUTPUT OPTIONS.
diego
parents:
12468
diff
changeset
|
115 Video output driver description (vo) |
7286 | 116 DECODING/FILTERING OPTIONS |
10218
f82646fc1431
Moved video filters to a separate section, moved slave mode section to the
jonas
parents:
8699
diff
changeset
|
117 Decoding/Filtering layer options (ad, vd, pl). |
f82646fc1431
Moved video filters to a separate section, moved slave mode section to the
jonas
parents:
8699
diff
changeset
|
118 VIDEO FILTERS |
f82646fc1431
Moved video filters to a separate section, moved slave mode section to the
jonas
parents:
8699
diff
changeset
|
119 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
|
120 GENERAL ENCODING OPTIONS (MENCODER ONLY) |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
121 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
|
122 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
|
123 Codec specific option descriptions (lavc,divx4,xvid,lame) (MEncoder only). |
7286 | 124 FILES |
125 A list and description of all installed/used files/directories. | |
126 EXAMPLES | |
127 Basic examples. Again: no long descriptions/processes. | |
128 BUGS | |
129 AUTHORS | |
130 STANDARD DISCLAIMER | |
131 | |
132 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
133 |
7286 | 134 The man page/groff format |
135 ------------------------- | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
136 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
137 Just read this and RTFS: |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
138 |
11561 | 139 man 7 roff |
7286 | 140 http://www.tldp.org/HOWTO/mini/Man-Page.html |
141 man 7 man | |
142 man 7 groff | |
143 | |
144 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
145 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
146 "Style" guidelines |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
147 ------------------ |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
148 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
149 This section was kept simple but there are certain guidelines/rules to get a |
7286 | 150 uniform man page. The best way is to read (and understand) the source. |
151 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
152 |
7286 | 153 General: |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
154 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
155 - No line should contain more than 79 characters. |
7744
6d41f5e905e2
reversed some changes as they produced ugly html output
jonas
parents:
7742
diff
changeset
|
156 - Used commands: .TH, .SH, .TP, .IP, .PP, .[R]B, .I, .br, .RS, .RE, .na, |
6d41f5e905e2
reversed some changes as they produced ugly html output
jonas
parents:
7742
diff
changeset
|
157 .nh, .ad, .hy, macro definitions, comments and some more |
11099 | 158 - Don't forget the quotation marks around expressions, etc... |
159 - Each new sentence should start on a line of its own. | |
160 - Put a backslash before a '-' if it denotes a range (1\-10), an option | |
11116 | 161 (\-fs), stdin (\-) or a dash (mplayer \- Movie Player for Linux). |
162 Use just '-' if it is a hyphen (A-V) or a minus (-1). Please note that | |
163 it should be \-dvd-device and not \-dvd\-device. | |
12864 | 164 - Don't start a line with "'" or ".", nroff treats them specially. |
7286 | 165 |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
166 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
167 Option descriptions: |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
168 |
11303 | 169 - Options should be in alphabetical order. |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
170 - 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
|
171 in angular brackets (e.g. \-vo <driver>). |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
172 - 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
|
173 the option (e.g. \-subpos <0\-100>). |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
174 - Optional things should be put in square brackets ([]). |
7286 | 175 - 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
|
176 (BETA CODE), etc. |
7286 | 177 - MPlayer only options in a section which isn't marked this way |
12744 | 178 are followed by (MPlayer only). |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
179 - 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
|
180 '(\-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
|
181 - 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
|
182 - 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
|
183 - The end of the suboptions _always_ has to be followed by a paragraph |
7289 | 184 (BUG). |
11303 | 185 - For flag options just document the non-default one of -XXX and -noXXX, if |
186 the option is not a flag, describe both, one below the other (this is an | |
187 exception to the alphabetical order). | |
7286 | 188 |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
189 |
7286 | 190 Macro definitions (see beginning of man page): |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
191 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
192 - SS Starting value of the suboption column |
7286 | 193 - .IPs Add new suboption (we use .TP for normal options and .IP for |
194 the rest) | |
195 - .RSs Begin of suboptions, end with .RE | |
196 - .RSss Begin of suboptions in a suboption | |
197 - .REss End of suboptions in a suboption | |
198 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
199 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
200 Options, suboptions, examples structure: |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
201 |
7286 | 202 - Normal options (note the '<' and '>'): |
203 | |
204 [...] | |
205 .TP | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
206 .B \-option <parameter> |
7286 | 207 description |
208 [...] | |
209 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
210 - Long suboptions: |
7286 | 211 |
212 [...] | |
213 description. Available options are: | |
214 . | |
215 .RSs | |
216 .IPs "subopt1=<value>" | |
217 description1 | |
218 .IPs "subopt2=<value>" | |
219 description2 | |
220 [...] | |
221 .IPs "last subopt=<value>" | |
222 last description | |
223 .RE | |
224 . | |
225 [...] | |
226 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
227 - Short suboptions: |
7289 | 228 |
229 [...] | |
230 description. Available options are: | |
231 | |
10702 | 232 .PD 0 |
7289 | 233 .RSs |
234 .IPs "subopt1=<value>" | |
235 description1 | |
236 .IPs "subopt2=<value>" | |
237 description2 | |
238 [...] | |
239 .IPs "last subopt=<value>" | |
240 last description | |
241 .RE | |
10702 | 242 .PD 1 |
7289 | 243 . |
244 [...] | |
245 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
246 - Suboptions in suboptions: |
7286 | 247 |
248 [...] | |
249 .IPs "subopt1=<value>" | |
250 description1 | |
251 .RSss | |
252 subsubopt1: description1 | |
253 .br | |
254 subsubopt2: description2 | |
255 [...] | |
256 .REss | |
257 [...] | |
258 | |
7741 | 259 - Examples: |
7286 | 260 |
261 [...] | |
12744 | 262 |
7286 | 263 .I EXAMPLE: |
264 .PD 0 | |
265 .RSs | |
266 .IP "-option used parameters" | |
267 description | |
268 [...] | |
269 .RE | |
270 .PD 1 | |
7289 | 271 . |
7286 | 272 [...] |