annotate DOCS/tech/manpage.txt @ 13682:aedf94d36d2a

support function for vcd on darwin
author nplourde
date Mon, 18 Oct 2004 21:06:50 +0000
parents 1916851d90a3
children e7f1ce608789
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
1 ========================================
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
2 A documentation about MPlayer's man page
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
3 ========================================
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
4
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
5
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
6 About the documentation
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
10 This guide should be used as a reference for questions about the man page
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
11 structure. It's not a strict guide but we recommend following it to get a
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
12 uniform man page.
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
13
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
17 -----------------------------
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
18
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
19 - option descriptions (all)
11561
8fd848195f54 updates, fixes, cosmetics
diego
parents: 11303
diff changeset
20 - usage (options, configuration files, controls)
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
21 - basic examples
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
22
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
30 - tutorials, guides
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
31
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
32
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
33
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
34 How should patches look like?
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
45
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
2c1336588588 remove some notes, more conversion notes
jonas
parents: 7289
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
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
8fd848195f54 updates, fixes, cosmetics
diego
parents: 11303
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
8fd848195f54 updates, fixes, cosmetics
diego
parents: 11303
diff changeset
67
8fd848195f54 updates, fixes, cosmetics
diego
parents: 11303
diff changeset
68 - rman: rman -f html mplayer.1 > man_page.rman.html
7741
2c1336588588 remove some notes, more conversion notes
jonas
parents: 7289
diff changeset
69 The output is ugly as rman doesn't understand many of the
2c1336588588 remove some notes, more conversion notes
jonas
parents: 7289
diff changeset
70 macros used.
11561
8fd848195f54 updates, fixes, cosmetics
diego
parents: 11303
diff changeset
71
8fd848195f54 updates, fixes, cosmetics
diego
parents: 11303
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
75
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
76
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
77 The structure
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
82
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
89 SYNOPSIS
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
90 A description of MPlayer's playtree.
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
91 DESCRIPTION
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
92 A general description of MPlayer, MEncoder, GMPlayer and its features.
11944
a4c9323779d1 new section structure
diego
parents: 11749
diff changeset
93 KEYBOARD CONTROL
a4c9323779d1 new section structure
diego
parents: 11749
diff changeset
94 A description of MPlayer's input system and the default keyboard controls.
a4c9323779d1 new section structure
diego
parents: 11749
diff changeset
95 USAGE
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
96 Some general notes about the options and a description of the config file
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
97 format.
11944
a4c9323779d1 new section structure
diego
parents: 11749
diff changeset
98 GENERAL OPTIONS
a4c9323779d1 new section structure
diego
parents: 11749
diff changeset
99 General options that are common to both MPlayer and MEncoder.
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
8c250171179b AUDIO OUTPUT DRIVERS section added.
diego
parents: 11944
diff changeset
110 AUDIO OUTPUT DRIVERS (MPLAYER ONLY)
8c250171179b AUDIO OUTPUT DRIVERS section added.
diego
parents: 11944
diff changeset
111 Audio output driver description (ao)
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
124 FILES
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
125 A list and description of all installed/used files/directories.
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
126 EXAMPLES
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
127 Basic examples. Again: no long descriptions/processes.
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
128 BUGS
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
129 AUTHORS
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
130 STANDARD DISCLAIMER
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
131
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
132
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
133
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
134 The man page/groff format
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
8fd848195f54 updates, fixes, cosmetics
diego
parents: 11303
diff changeset
139 man 7 roff
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
140 http://www.tldp.org/HOWTO/mini/Man-Page.html
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
141 man 7 man
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
142 man 7 groff
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
143
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
150 uniform man page. The best way is to read (and understand) the source.
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
151
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
152
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
1e0fbb8907b7 Explain some troff tricks.
diego
parents: 10702
diff changeset
158 - Don't forget the quotation marks around expressions, etc...
1e0fbb8907b7 Explain some troff tricks.
diego
parents: 10702
diff changeset
159 - Each new sentence should start on a line of its own.
1e0fbb8907b7 Explain some troff tricks.
diego
parents: 10702
diff changeset
160 - Put a backslash before a '-' if it denotes a range (1\-10), an option
11116
9fc4061337c4 stdin should be \-.
diego
parents: 11101
diff changeset
161 (\-fs), stdin (\-) or a dash (mplayer \- Movie Player for Linux).
9fc4061337c4 stdin should be \-.
diego
parents: 11101
diff changeset
162 Use just '-' if it is a hyphen (A-V) or a minus (-1). Please note that
9fc4061337c4 stdin should be \-.
diego
parents: 11101
diff changeset
163 it should be \-dvd-device and not \-dvd\-device.
12864
6626044764e0 Hint about . and ' in nroff.
diego
parents: 12744
diff changeset
164 - Don't start a line with "'" or ".", nroff treats them specially.
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
920b08da3091 alphabetical order
diego
parents: 11116
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
177 - MPlayer only options in a section which isn't marked this way
12744
ffa2cbddc276 sync with mplayer.1, noticed by Sebastian Kr¸«£mer
diego
parents: 12716
diff changeset
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
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
184 (BUG).
11303
920b08da3091 alphabetical order
diego
parents: 11116
diff changeset
185 - For flag options just document the non-default one of -XXX and -noXXX, if
920b08da3091 alphabetical order
diego
parents: 11116
diff changeset
186 the option is not a flag, describe both, one below the other (this is an
920b08da3091 alphabetical order
diego
parents: 11116
diff changeset
187 exception to the alphabetical order).
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
188
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
189
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
193 - .IPs Add new suboption (we use .TP for normal options and .IP for
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
194 the rest)
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
195 - .RSs Begin of suboptions, end with .RE
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
196 - .RSss Begin of suboptions in a suboption
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
197 - .REss End of suboptions in a suboption
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
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
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
202 - Normal options (note the '<' and '>'):
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
203
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
204 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
205 .TP
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
206 .B \-option <parameter>
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
207 description
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
208 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
209
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
210 - Long suboptions:
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
211
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
212 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
213 description. Available options are:
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
214 .
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
215 .RSs
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
216 .IPs "subopt1=<value>"
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
217 description1
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
218 .IPs "subopt2=<value>"
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
219 description2
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
220 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
221 .IPs "last subopt=<value>"
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
222 last description
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
223 .RE
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
224 .
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
225 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
226
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
227 - Short suboptions:
7289
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
228
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
229 [...]
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
230 description. Available options are:
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
231
10702
diego
parents: 10380
diff changeset
232 .PD 0
7289
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
233 .RSs
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
234 .IPs "subopt1=<value>"
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
235 description1
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
236 .IPs "subopt2=<value>"
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
237 description2
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
238 [...]
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
239 .IPs "last subopt=<value>"
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
240 last description
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
241 .RE
10702
diego
parents: 10380
diff changeset
242 .PD 1
7289
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
243 .
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
244 [...]
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
245
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
246 - Suboptions in suboptions:
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
247
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
248 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
249 .IPs "subopt1=<value>"
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
250 description1
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
251 .RSss
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
252 subsubopt1: description1
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
253 .br
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
254 subsubopt2: description2
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
255 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
256 .REss
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
257 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
258
7741
2c1336588588 remove some notes, more conversion notes
jonas
parents: 7289
diff changeset
259 - Examples:
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
260
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
261 [...]
12744
ffa2cbddc276 sync with mplayer.1, noticed by Sebastian Kr¸«£mer
diego
parents: 12716
diff changeset
262
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
263 .I EXAMPLE:
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
264 .PD 0
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
265 .RSs
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
266 .IP "-option used parameters"
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
267 description
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
268 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
269 .RE
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
270 .PD 1
7289
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
271 .
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
272 [...]