Mercurial > mplayer.hg
annotate DOCS/tech/manpage.txt @ 9302:e23939b2ac30
sync
author | gabucino |
---|---|
date | Thu, 06 Feb 2003 21:25:48 +0000 |
parents | b3e78d22cae0 |
children | f82646fc1431 |
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) |
20 - usage (options, config files, controls, slave mode) | |
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). |
7741 | 58 cat mplayer.1 | sed s/SS\ 20/SS\ 4/ | groff -man -Thtml - > manpage.html |
8217 | 59 groff -rLL=64n -m man -Tascii mplayer.1 | col -bx > manpage.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. |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
61 - man2html: You can view it through a CGI script: |
7286 | 62 http://localhost/cgi-bin/man2html?mplayer |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
63 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
|
64 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
|
65 acceptable results. |
7742 | 66 - rman: rman -f html mplayer.1 > manpage.rman.html |
7741 | 67 The output is ugly as rman doesn't understand many of the |
68 macros used. | |
69 - troffcvt: troff2html -man mplayer.1 > manpage.tcvt.html | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
70 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
|
71 |
7286 | 72 |
73 | |
74 The structure | |
75 ------------- | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
76 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
77 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
|
78 alphabetically sorted. The sections are: |
7286 | 79 |
80 (Header) | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
81 Not visible, copyright and author information. |
7286 | 82 (Macro definitions) |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
83 Not visible, some macro definitions. |
7286 | 84 NAME |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
85 The man page is used for both mplayer and mencoder. |
7286 | 86 SYNOPSIS |
87 A description of MPlayer's playtree. | |
88 DESCRIPTION | |
89 A general description of MPlayer, MEncoder, GMPlayer and its features. | |
90 GENERAL NOTES | |
91 Some general notes about the options and a description of the config file | |
92 format. | |
93 PLAYER OPTIONS (MPLAYER ONLY) | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
94 User interface option descriptions (MPlayer only). |
7286 | 95 DEMUXER/STREAM OPTIONS |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
96 Demuxer and stream layer option descriptions. |
7286 | 97 OSD/SUB OPTIONS |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
98 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
|
99 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
|
100 created because of its size. |
7286 | 101 AUDIO OUTPUT OPTIONS (MPLAYER ONLY) |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
102 Audio output layer (ao) option descriptions (MPlayer only). |
7286 | 103 VIDEO OUTPUT OPTIONS (MPLAYER ONLY) |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
104 Video output layer (vo) option descriptions (MPlayer only). |
7286 | 105 DECODING/FILTERING OPTIONS |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
106 Decoding and filter layer options (ad, vd, vf, pl). |
7286 | 107 ENCODING OPTIONS (MENCODER ONLY) |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
108 Encoding option descriptions (ve) (MEncoder only). |
7286 | 109 KEYBOARD CONTROL |
110 A description of MPlayer's input system and the default keyboard controls. | |
111 SLAVE MODE PROTOCOL | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
112 A description of the slave mode protocol (-slave). |
7286 | 113 FILES |
114 A list and description of all installed/used files/directories. | |
115 EXAMPLES | |
116 Basic examples. Again: no long descriptions/processes. | |
117 BUGS | |
118 AUTHORS | |
119 STANDARD DISCLAIMER | |
120 | |
121 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
122 |
7286 | 123 The man page/groff format |
124 ------------------------- | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
125 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
126 Just read this and RTFS: |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
127 |
7286 | 128 http://www.tldp.org/HOWTO/mini/Man-Page.html |
129 man 7 man | |
130 man 7 groff | |
131 | |
132 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
133 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
134 "Style" guidelines |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
135 ------------------ |
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 This section was kept simple but there are certain guidelines/rules to get a |
7286 | 138 uniform man page. The best way is to read (and understand) the source. |
139 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
140 |
7286 | 141 General: |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
142 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
143 - No line should contain more than 79 characters. |
7744
6d41f5e905e2
reversed some changes as they produced ugly html output
jonas
parents:
7742
diff
changeset
|
144 - 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
|
145 .nh, .ad, .hy, macro definitions, comments and some more |
7741 | 146 - Don't forget the quotation marks around expressions, the backslash |
147 before a '-' if it's needed, etc... | |
7286 | 148 |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
149 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
150 Option descriptions: |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
151 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
152 - 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
|
153 in angular brackets (e.g. \-vo <driver>). |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
154 - 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
|
155 the option (e.g. \-subpos <0\-100>). |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
156 - Optional things should be put in square brackets ([]). |
7286 | 157 - 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
|
158 (BETA CODE), etc. |
7286 | 159 - MPlayer only options in a section which isn't marked this way |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
160 are followed by (MPLAYER only). |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
161 - 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
|
162 '(\-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
|
163 - 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
|
164 - 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
|
165 - The end of the suboptions _always_ has to be followed by a paragraph |
7289 | 166 (BUG). |
7286 | 167 |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
168 |
7286 | 169 Macro definitions (see beginning of man page): |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
170 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
171 - SS Starting value of the suboption column |
7286 | 172 - .IPs Add new suboption (we use .TP for normal options and .IP for |
173 the rest) | |
174 - .RSs Begin of suboptions, end with .RE | |
175 - .RSss Begin of suboptions in a suboption | |
176 - .REss End of suboptions in a suboption | |
177 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
178 |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
179 Options, suboptions, examples structure: |
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
180 |
7286 | 181 - Normal options (note the '<' and '>'): |
182 | |
183 [...] | |
184 .TP | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
185 .B \-option <parameter> |
7286 | 186 description |
187 [...] | |
188 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
189 - Long suboptions: |
7286 | 190 |
191 [...] | |
192 description. Available options are: | |
193 . | |
194 .RSs | |
195 .IPs "subopt1=<value>" | |
196 description1 | |
197 .IPs "subopt2=<value>" | |
198 description2 | |
199 [...] | |
200 .IPs "last subopt=<value>" | |
201 last description | |
202 .RE | |
203 . | |
204 [...] | |
205 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
206 - Short suboptions: |
7289 | 207 |
208 [...] | |
209 description. Available options are: | |
210 | |
211 .DP 0 | |
212 .RSs | |
213 .IPs "subopt1=<value>" | |
214 description1 | |
215 .IPs "subopt2=<value>" | |
216 description2 | |
217 [...] | |
218 .IPs "last subopt=<value>" | |
219 last description | |
220 .RE | |
221 .DP 1 | |
222 . | |
223 [...] | |
224 | |
8699
b3e78d22cae0
Spell checking, parts reworded for greater clarity, layout now uses
diego
parents:
8217
diff
changeset
|
225 - Suboptions in suboptions: |
7286 | 226 |
227 [...] | |
228 .IPs "subopt1=<value>" | |
229 description1 | |
230 .RSss | |
231 subsubopt1: description1 | |
232 .br | |
233 subsubopt2: description2 | |
234 [...] | |
235 .REss | |
236 [...] | |
237 | |
7741 | 238 - Examples: |
7286 | 239 |
240 [...] | |
241 | |
242 .I EXAMPLE: | |
243 .PD 0 | |
244 .RSs | |
245 .IP "-option used parameters" | |
246 description | |
247 [...] | |
248 .RE | |
249 .PD 1 | |
7289 | 250 . |
7286 | 251 [...] |