mirror of
https://github.com/mpv-player/mpv
synced 2024-10-30 04:46:41 +01:00
0602bf1fdd
git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@24904 b3059339-0415-0410-9bf9-f77b7e298cf2
284 lines
8.5 KiB
Plaintext
284 lines
8.5 KiB
Plaintext
========================================
|
|
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
|
|
.
|
|
[...]
|