summaryrefslogtreecommitdiffstats
path: root/DOCS/tech/manpage.txt
blob: f3ad7fd355521f34d04163ec1d3c6d53e401e697 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
========================================
A documentation about MPlayer's man page
========================================


About the documentation
-----------------------

Yes it's true: This is the documentation of the documentation (man page).
This guide should be used as a reference for questions about the man page
structure. It's not a strict guide but we recommend following it to get a
uniform man page.



What belongs in the man page?
-----------------------------

  - option descriptions (all)
  - usage (options, configuration files, controls)
  - basic examples



What doesn't belong in the man page?
------------------------------------

  - instructions for installation, encoding and similar processes
  - detailed evaluations or hints
  - tutorials, guides



How should patches look like?
-----------------------------

Follow the rules in patches.txt, they apply to the man page, too.
Exceptions are:

  - Cosmetic patches are allowed but should be done separately from the real
    changes, be marked as cosmetic changes and shouldn't change the general
    style without reasons/permissions.
  - The same applies to spell checking.



How do I create an HTML, text or other version of the man page?
---------------------------------------------------------------

The man page was more or less designed for groff as it is the main tool for
it. Therefore only groff produces acceptable results without changes.
Additionally, the SS variable should be set to either very low or very high
values to produce a better groff HTML output (Due to a bug of groff2html?).
A setting of 4 should look readable. Here's an overview again:

  - groff:
    groff is the "official" tool to convert man pages. To get good results you
    need a recent version (1.18.2).
    groff -mman -Thtml mplayer.1 > mplayer.1.html
    groff -mman -Tlatin1 -rLL=78n mplayer.1 | col -bxp > mplayer.1.txt
    The groff man page lists other output formats to use with -T.

    Unfortunately groff is not able to handle UTF-8 input as of version 1.19.2.
    groff-utf8 is a wrapper that works around these deficiencies:
      http://www.haible.de/bruno/packages-groff-utf8.html

  - man2html:
    You can view it through a CGI script:
    http://localhost/cgi-bin/man2html?mplayer
    The output is unusable as the script doesn't seem to support the macro
    definitions. Maybe manually changing all leads to acceptable results.

  - rman:
    rman -f html mplayer.1 > man_page.rman.html
    The output is ugly as rman doesn't understand many of the macros used.

  - troffcvt:
    troff2html -man mplayer.1 > man_page.tcvt.html
    The (good) output is similar to groff but simplified...



The structure
-------------

The option descriptions are divided into sections. Inside a section options are
alphabetically sorted. The sections are:

(Header)
    not visible, copyright and author information
(Macro definitions)
    not visible, some macro definitions
NAME
    The man page is used for both mplayer and mencoder.
SYNOPSIS
    a description of MPlayer's playtree
DESCRIPTION
    a general description of MPlayer, MEncoder, GMPlayer and their features
INTERACTIVE CONTROL
    description of MPlayer's input system and interactive controls
USAGE
    some general notes about usage
CONFIGURATION FILES
    description of the configuration file format
GENERAL OPTIONS
    General options that are common to both MPlayer and MEncoder.
PLAYER OPTIONS (MPLAYER ONLY)
    user interface option descriptions (MPlayer only)
DEMUXER/STREAM OPTIONS
    demuxer and stream layer option descriptions
OSD/SUBTITLE OPTIONS
    This section is special in that it contains all subtitle and OSD option
    descriptions even if they might belong to one of the other sections. It
    was created because of its size.
AUDIO OUTPUT OPTIONS (MPLAYER ONLY)
    audio output layer (ao) option descriptions (MPlayer only)
AUDIO OUTPUT DRIVERS (MPLAYER ONLY)
    audio output driver description (ao)
VIDEO OUTPUT OPTIONS (MPLAYER ONLY)
    video output layer (vo) option descriptions (MPlayer only)
VIDEO OUTPUT DRIVERS (MPLAYER ONLY)
    video output driver description (vo)
DECODING/FILTERING OPTIONS
    decoding/filtering layer options (ad, vd, pl)
VIDEO FILTERS
    video filter description (vf)
GENERAL ENCODING OPTIONS (MENCODER ONLY)
    Encoding option descriptions (ve) (MEncoder only).
CODEC SPECIFIC ENCODING OPTIONS (MENCODER ONLY)
    Codec specific option descriptions (lavc,divx4,xvid,lame) (MEncoder only).
FILES
    a list and description of all installed/used files/directories
EXAMPLES OF MPLAYER USAGE
    basic examples, again: no long descriptions/processes
EXAMPLES OF MENCODER USAGE
    basic examples, again: no long descriptions/processes
BUGS
AUTHORS



The man page/groff format
-------------------------

Just read this and RTFS:

    man 7 roff
    http://www.tldp.org/HOWTO/mini/Man-Page.html
    man 7 man
    man 7 groff



"Style" guidelines
------------------

This section was kept simple but there are certain guidelines/rules to get a
uniform man page. The best way is to read (and understand) the source.


General:

    - No line should contain more than 79 characters.
    - used commands: .TH, .SH, .TP, .IP, .PP, .[R]B, .I, .br, .RS, .RE, .na,
                     .nh, .ad, .hy, macro definitions, comments and some more
    - Don't forget the quotation marks around expressions, etc...
    - Each new sentence should start on a line of its own.
    - There is a typographical difference between a hyphen, a minus and an
      en-dash or em-dash. For the man page this means that you should put a
      backslash before a '-' if it denotes a range (1\-10), an option (\-fs),
      stdin (\-), a dash (mplayer \- movie player) or a minus (\-1). Use just
      '-' if it is a hyphen (A-V).
    - Don't start a line with "'" or ".", nroff treats them specially.
    - To quickly check a manual page for markup errors, just run
        man DOCS/man/XX/mplayer.1 > /dev/null


Option descriptions:

    - Options should be in alphabetical order.
    - Option and/or suboption parameters should be short, descriptive and put
      in angular brackets (e.g. \-vo <driver>).
    - If the option has a parameter in a certain range, specify it right after
      the option (e.g. \-subpos <0\-100>).
    - Optional things should be put in square brackets ([]).
    - Obsolete options are followed by (OBSOLETE), beta options by
      (BETA CODE), etc.
    - MPlayer-only options in a section which isn't marked this way
      are followed by (MPlayer only).
    - Add references to other options if they belong to each other, e.g.
      '(\-vo zr only)' or '(also see \-alang)' or are commonly used together.
    - If a nontrivial default parameter exists, mention it, e.g. (default: 24).
    - Put examples and notes at the end of the description (before suboptions).
    - The end of the suboptions _always_ has to be followed by a paragraph
      (BUG).
    - For flag options just document the non-default one of \-XXX and \-noXXX.
      If the option is not a flag, describe both, one below the other (this is
      an exception to the alphabetical order).


Macro definitions (see beginning of man page):

    - .SS     starting value of the suboption column
    - .IPs    Add new suboption (we use .TP for normal options and .IP for
              the rest).
    - .RSs    begin of suboptions, end with .RE
    - .RSss   begin of suboptions in a suboption
    - .REss   end of suboptions in a suboption


Options, suboptions, examples structure:

    - Normal options (note the '<' and '>'):

      [...]
      .TP
      .B \-option <parameter>
      description
      [...]

    - Long suboptions:

      [...]
      description. Available options are:
      .
      .RSs
      .IPs "subopt1=<value>"
      description1
      .IPs "subopt2=<value>"
      description2
      [...]
      .IPs "last subopt=<value>"
      last description
      .RE
      .
      [...]

    - Short suboptions:

      [...]
      description. Available options are:

      .PD 0
      .RSs
      .IPs "subopt1=<value>"
      description1
      .IPs "subopt2=<value>"
      description2
      [...]
      .IPs "last subopt=<value>"
      last description
      .RE
      .PD 1
      .
      [...]

    - Suboptions in suboptions:

      [...]
      .IPs "subopt1=<value>"
      description1
      .RSss
      subsubopt1: description1
      .br
      subsubopt2: description2
      [...]
      .REss
      [...]

    - Examples:

      [...]

      .I EXAMPLE:
      .PD 0
      .RSs
      .IP "\-option used parameters"
      description
      [...]
      .RE
      .PD 1
      .
      [...]