mirror of
https://github.com/mpv-player/mpv
synced 2024-12-24 07:42:17 +00:00
57c9037312
whitespace more generously, small updates. git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@8700 b3059339-0415-0410-9bf9-f77b7e298cf2
252 lines
7.3 KiB
Plaintext
252 lines
7.3 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, config files, controls, slave mode)
|
|
- 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).
|
|
cat mplayer.1 | sed s/SS\ 20/SS\ 4/ | groff -man -Thtml - > manpage.html
|
|
groff -rLL=64n -m man -Tascii mplayer.1 | col -bx > manpage.txt
|
|
The groff man page lists other output formats to use with -T.
|
|
- 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 > manpage.rman.html
|
|
The output is ugly as rman doesn't understand many of the
|
|
macros used.
|
|
- troffcvt: troff2html -man mplayer.1 > manpage.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 its features.
|
|
GENERAL NOTES
|
|
Some general notes about the options and a description of the config file
|
|
format.
|
|
PLAYER OPTIONS (MPLAYER ONLY)
|
|
User interface option descriptions (MPlayer only).
|
|
DEMUXER/STREAM OPTIONS
|
|
Demuxer and stream layer option descriptions.
|
|
OSD/SUB 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).
|
|
VIDEO OUTPUT OPTIONS (MPLAYER ONLY)
|
|
Video output layer (vo) option descriptions (MPlayer only).
|
|
DECODING/FILTERING OPTIONS
|
|
Decoding and filter layer options (ad, vd, vf, pl).
|
|
ENCODING OPTIONS (MENCODER ONLY)
|
|
Encoding option descriptions (ve) (MEncoder only).
|
|
KEYBOARD CONTROL
|
|
A description of MPlayer's input system and the default keyboard controls.
|
|
SLAVE MODE PROTOCOL
|
|
A description of the slave mode protocol (-slave).
|
|
FILES
|
|
A list and description of all installed/used files/directories.
|
|
EXAMPLES
|
|
Basic examples. Again: no long descriptions/processes.
|
|
BUGS
|
|
AUTHORS
|
|
STANDARD DISCLAIMER
|
|
|
|
|
|
|
|
The man page/groff format
|
|
-------------------------
|
|
|
|
Just read this and RTFS:
|
|
|
|
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, the backslash
|
|
before a '-' if it's needed, etc...
|
|
|
|
|
|
Option descriptions:
|
|
|
|
- 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).
|
|
|
|
|
|
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:
|
|
|
|
.DP 0
|
|
.RSs
|
|
.IPs "subopt1=<value>"
|
|
description1
|
|
.IPs "subopt2=<value>"
|
|
description2
|
|
[...]
|
|
.IPs "last subopt=<value>"
|
|
last description
|
|
.RE
|
|
.DP 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
|
|
.
|
|
[...]
|