annotate DOCS/tech/manpage.txt @ 20267:b0c44d5b9d6c

sync up to r20265 + some li'l fix
author ptt
date Mon, 16 Oct 2006 16:11:04 +0000
parents 5fe8793f0c17
children a45bc176a16d
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
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
19 - option descriptions (all)
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
20 - usage (options, configuration files, controls)
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
21 - basic examples
7286
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
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
28 - instructions for installation, encoding and similar processes
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
29 - detailed evaluations or hints
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
30 - tutorials, guides
7286
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
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
40 - Cosmetic patches are allowed but should be done separately from the real
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
41 changes, be marked as cosmetic changes and shouldn't change the general
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
42 style without reasons/permissions.
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
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
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
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
56 - groff: groff is the "official" tool to convert man pages.
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
57 To get good results you need a recent version (1.18.2).
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
58 groff -mman -Thtml mplayer.1 > mplayer.1.html
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
59 groff -mman -Tlatin1 -rLL=78n mplayer.1 | col -bx > mplayer.1.txt
5fe8793f0c17 cosmetics
diego
parents: 19879
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
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
62 - man2html: You can view it through a CGI script:
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
63 http://localhost/cgi-bin/man2html?mplayer
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
64 The output is unusable as the script doesn't seem to support
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
65 the macro definitions. Maybe manually changing all leads to
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
66 acceptable results.
11561
8fd848195f54 updates, fixes, cosmetics
diego
parents: 11303
diff changeset
67
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
68 - rman: rman -f html mplayer.1 > man_page.rman.html
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
69 The output is ugly as rman doesn't understand many of the
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
70 macros used.
11561
8fd848195f54 updates, fixes, cosmetics
diego
parents: 11303
diff changeset
71
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
72 - troffcvt: troff2html -man mplayer.1 > man_page.tcvt.html
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
73 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
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)
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
84 not visible, copyright and author information
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
85 (Macro definitions)
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
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
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
90 a description of MPlayer's playtree
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
91 DESCRIPTION
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
92 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
93 INTERACTIVE CONTROL
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
94 description of MPlayer's input system and interactive controls
11944
a4c9323779d1 new section structure
diego
parents: 11749
diff changeset
95 USAGE
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
96 some general notes about usage
17310
e80e942558fb CONFIGURATION FILES section added to the man page.
diego
parents: 17062
diff changeset
97 CONFIGURATION FILES
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
98 description of the configuration file format
11944
a4c9323779d1 new section structure
diego
parents: 11749
diff changeset
99 GENERAL OPTIONS
a4c9323779d1 new section structure
diego
parents: 11749
diff changeset
100 General options that are common to both MPlayer and MEncoder.
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
101 PLAYER OPTIONS (MPLAYER ONLY)
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
102 user interface option descriptions (MPlayer only)
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
103 DEMUXER/STREAM OPTIONS
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
104 demuxer and stream layer option descriptions
19047
bae8c4f93f10 Rename OSD/SUB section to OSD/SUBTITLES.
diego
parents: 17310
diff changeset
105 OSD/SUBTITLE OPTIONS
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
106 This section is special in that it contains all subtitle and OSD option
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
107 descriptions even if they might belong to one of the other sections. It
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
108 was created because of its size.
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
109 AUDIO OUTPUT OPTIONS (MPLAYER ONLY)
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
110 audio output layer (ao) option descriptions (MPlayer only)
12468
8c250171179b AUDIO OUTPUT DRIVERS section added.
diego
parents: 11944
diff changeset
111 AUDIO OUTPUT DRIVERS (MPLAYER ONLY)
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
112 audio output driver description (ao)
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
113 VIDEO OUTPUT OPTIONS (MPLAYER ONLY)
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
114 video output layer (vo) option descriptions (MPlayer only)
12716
296b1f6f6bf7 VIDEO OUTPUT DRIVERS moved right after VIDEO OUTPUT OPTIONS.
diego
parents: 12468
diff changeset
115 VIDEO OUTPUT DRIVERS (MPLAYER ONLY)
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
116 video output driver description (vo)
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
117 DECODING/FILTERING OPTIONS
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
118 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
119 VIDEO FILTERS
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
120 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
121 GENERAL ENCODING OPTIONS (MENCODER ONLY)
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
122 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
123 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
124 Codec specific option descriptions (lavc,divx4,xvid,lame) (MEncoder only).
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
125 FILES
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
126 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
127 EXAMPLES OF MPLAYER USAGE
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
128 basic examples, again: no long descriptions/processes
17062
007826f61f58 Sync man page structure description with actual man page structure.
diego
parents: 16688
diff changeset
129 EXAMPLES OF MENCODER USAGE
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
130 basic examples, again: no long descriptions/processes
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
131 BUGS
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
132 AUTHORS
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
133
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
134
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
135
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
136 The man page/groff format
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
137 -------------------------
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
138
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
139 Just read this and RTFS:
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
140
11561
8fd848195f54 updates, fixes, cosmetics
diego
parents: 11303
diff changeset
141 man 7 roff
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
142 http://www.tldp.org/HOWTO/mini/Man-Page.html
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
143 man 7 man
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
144 man 7 groff
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
145
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
146
8699
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 "Style" guidelines
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
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
151 This section was kept simple but there are certain guidelines/rules to get a
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
152 uniform man page. The best way is to read (and understand) the source.
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
153
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
154
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
155 General:
8699
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 - No line should contain more than 79 characters.
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
158 - 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
159 .nh, .ad, .hy, macro definitions, comments and some more
11099
1e0fbb8907b7 Explain some troff tricks.
diego
parents: 10702
diff changeset
160 - Don't forget the quotation marks around expressions, etc...
1e0fbb8907b7 Explain some troff tricks.
diego
parents: 10702
diff changeset
161 - Each new sentence should start on a line of its own.
1e0fbb8907b7 Explain some troff tricks.
diego
parents: 10702
diff changeset
162 - Put a backslash before a '-' if it denotes a range (1\-10), an option
11116
9fc4061337c4 stdin should be \-.
diego
parents: 11101
diff changeset
163 (\-fs), stdin (\-) or a dash (mplayer \- Movie Player for Linux).
9fc4061337c4 stdin should be \-.
diego
parents: 11101
diff changeset
164 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
165 it should be \-dvd-device and not \-dvd\-device.
12864
6626044764e0 Hint about . and ' in nroff.
diego
parents: 12744
diff changeset
166 - 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
167 - 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
168 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
169
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
170
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
171 Option descriptions:
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
172
11303
920b08da3091 alphabetical order
diego
parents: 11116
diff changeset
173 - Options should be in alphabetical order.
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
174 - 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
175 in angular brackets (e.g. \-vo <driver>).
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
176 - 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
177 the option (e.g. \-subpos <0\-100>).
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
178 - Optional things should be put in square brackets ([]).
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
179 - 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
180 (BETA CODE), etc.
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
181 - 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
182 are followed by (MPlayer only).
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
183 - 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
184 '(\-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
185 - 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
186 - 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
187 - The end of the suboptions _always_ has to be followed by a paragraph
7289
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
188 (BUG).
11303
920b08da3091 alphabetical order
diego
parents: 11116
diff changeset
189 - For flag options just document the non-default one of -XXX and -noXXX, if
920b08da3091 alphabetical order
diego
parents: 11116
diff changeset
190 the option is not a flag, describe both, one below the other (this is an
920b08da3091 alphabetical order
diego
parents: 11116
diff changeset
191 exception to the alphabetical order).
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
192
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
193
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
194 Macro definitions (see beginning of man page):
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
195
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
196 - .SS starting value of the suboption column
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
197 - .IPs Add new suboption (we use .TP for normal options and .IP for
19920
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
198 the rest).
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
199 - .RSs begin of suboptions, end with .RE
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
200 - .RSss begin of suboptions in a suboption
5fe8793f0c17 cosmetics
diego
parents: 19879
diff changeset
201 - .REss end of suboptions in a suboption
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
202
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
203
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
204 Options, suboptions, examples structure:
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
205
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
206 - Normal options (note the '<' and '>'):
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
207
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
208 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
209 .TP
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
210 .B \-option <parameter>
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
211 description
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
212 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
213
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
214 - Long suboptions:
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
215
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
216 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
217 description. Available options are:
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
218 .
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
219 .RSs
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
220 .IPs "subopt1=<value>"
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
221 description1
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
222 .IPs "subopt2=<value>"
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
223 description2
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
224 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
225 .IPs "last subopt=<value>"
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
226 last description
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
227 .RE
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
228 .
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
229 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
230
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
231 - Short suboptions:
7289
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
232
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
233 [...]
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
234 description. Available options are:
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
235
10702
diego
parents: 10380
diff changeset
236 .PD 0
7289
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
237 .RSs
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
238 .IPs "subopt1=<value>"
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
239 description1
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
240 .IPs "subopt2=<value>"
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
241 description2
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
242 [...]
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
243 .IPs "last subopt=<value>"
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
244 last description
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
245 .RE
10702
diego
parents: 10380
diff changeset
246 .PD 1
7289
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
247 .
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
248 [...]
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
249
8699
b3e78d22cae0 Spell checking, parts reworded for greater clarity, layout now uses
diego
parents: 8217
diff changeset
250 - Suboptions in suboptions:
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
251
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
252 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
253 .IPs "subopt1=<value>"
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
254 description1
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
255 .RSss
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
256 subsubopt1: description1
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
257 .br
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
258 subsubopt2: description2
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
259 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
260 .REss
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
261 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
262
7741
2c1336588588 remove some notes, more conversion notes
jonas
parents: 7289
diff changeset
263 - Examples:
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
264
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
265 [...]
12744
ffa2cbddc276 sync with mplayer.1, noticed by Sebastian Kr¸«£mer
diego
parents: 12716
diff changeset
266
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
267 .I EXAMPLE:
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
268 .PD 0
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
269 .RSs
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
270 .IP "-option used parameters"
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
271 description
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
272 [...]
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
273 .RE
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
274 .PD 1
7289
bfad437d4119 changes for rewrite
jonas
parents: 7286
diff changeset
275 .
7286
98dd8785cf24 man page documentation
jonas
parents:
diff changeset
276 [...]