mirror of https://github.com/mpv-player/mpv
235 lines
7.5 KiB
Plaintext
235 lines
7.5 KiB
Plaintext
A documentation about MPlayer's man page
|
|
========================================
|
|
|
|
|
|
About the documentation
|
|
-----------------------
|
|
Yes it's true: This is the documentation about 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 to the man page?
|
|
-----------------------------
|
|
- option descriptions (all)
|
|
- usage (options, config files, controls, slave mode)
|
|
- basic examples
|
|
|
|
|
|
What doesn't belong to the man page?
|
|
------------------------------------
|
|
- instructions of a process (installation, encoding, etc)
|
|
- detailed valuations 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 seperately from the real
|
|
changes, be marked as cosmetic changes and shouldn't change the general
|
|
style without reasons/permissions
|
|
- The same applies for spellchecks
|
|
|
|
|
|
How do I create a html version of the man page?
|
|
-----------------------------------------------
|
|
The man pages was more or less designed for groff as it is the main tool for
|
|
it. Therefore only groff produces acceptable results without changes.
|
|
Additionaly, the SS variable should be set to either very low or very high
|
|
values to produce a better groff html output (~18 looks nice for man).
|
|
Here's an overview again:
|
|
|
|
- groff: groff -Thtml -m man mplayer.1 > manpage.groff.html
|
|
- man2html: You can view it over your cgi script:
|
|
http://localhost/cgi-bin/man2html?mplayer
|
|
The output is unuseable as the script doesn't seem to
|
|
support the macro definitions. Maybe a manual change of all
|
|
leads to acceptable results.
|
|
- rman: rman -f html mplayer.1 > manpage.rman.html
|
|
The output is ugly, you need to remove the .PDs to produce
|
|
at least acceptable results.
|
|
|
|
|
|
The structure
|
|
-------------
|
|
The options are divided into the the layer they belong to. The only exception
|
|
is the OSD/SUB section. Inside the section they're alphabetically ordered.
|
|
|
|
(Header)
|
|
Not visible, copyright and author informations.
|
|
(Macro definitions)
|
|
Not visible, some macro defintions.
|
|
NAME
|
|
The manpage 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)
|
|
Option descriptions about the user interface (mplayer only).
|
|
DEMUXER/STREAM OPTIONS
|
|
Option descriptions about the demuxer and stream layer.
|
|
OSD/SUB OPTIONS
|
|
This section is special: It contains all description about subtitles and
|
|
OSD. It is independent of the usual layer separation and was created
|
|
because of its size. The options may therefore come from any layer.
|
|
AUDIO OUTPUT OPTIONS (MPLAYER ONLY)
|
|
Option descriptions about the audio output layer (ao) (mplayer only).
|
|
VIDEO OUTPUT OPTIONS (MPLAYER ONLY)
|
|
Option descriptions about the video output layer (vo) (mplayer only).
|
|
DECODING/FILTERING OPTIONS
|
|
Options about the decoding and filter layer (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 about 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
|
|
|
|
|
|
Directives for the internal "style"
|
|
-----------------------------------
|
|
It was kept simple but there are still certain directives/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, .[R]B, .I, .br, .RS, .RE, macro
|
|
definitions, comments
|
|
- Don't forget the quotation marks around expressions or the backslash
|
|
before a '-' if it's needed.
|
|
|
|
Separations:
|
|
- Sections (.SH) 2 newlines before (3 visible because of .SH)
|
|
- Options not (it's done automatically over .TP)
|
|
- Sub options not (it's done automatically over .IP)
|
|
should be be separated over a comment (.) at the
|
|
beginning and the end to make the man page readable ;)
|
|
- Examples, notes 1 newline before
|
|
- Big parts better use .P (paragraph) or .br (equal to html's <BR>)
|
|
instead of newlines
|
|
- In general no newlines
|
|
never more than 2 spaces between anything
|
|
|
|
Option description:
|
|
- Option and/or suboption parameters should be short and descriptive.
|
|
- If the option is between a certain range, it should be specified at the
|
|
beginning (eg. <0\-100> or <\-100 \- 100>)
|
|
- All optional things are but between angular paranthesis ([])
|
|
- 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 hints to other options if they belong to each other
|
|
eg. (\-vo zr only) or (see \-alang option too)
|
|
- If a non trivial default parameter exist, write it down
|
|
eg. (default: 24)
|
|
- Options inside a section are all alphabetically ordered
|
|
- Examples and notes at the end of the description (before sub options)
|
|
- The end of the suboptions _always_ has to be followed by a paragraphs
|
|
(BUG).
|
|
|
|
Macro definitions (see beginning of man page):
|
|
- SS SS is the 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, sub options, examples structure:
|
|
- Normal options (note the '<' and '>'):
|
|
|
|
[...]
|
|
.TP
|
|
.B \-option <parameters>
|
|
description
|
|
[...]
|
|
|
|
- Long sub options:
|
|
|
|
[...]
|
|
description. Available options are:
|
|
.
|
|
.RSs
|
|
.IPs "subopt1=<value>"
|
|
description1
|
|
.IPs "subopt2=<value>"
|
|
description2
|
|
[...]
|
|
.IPs "last subopt=<value>"
|
|
last description
|
|
.RE
|
|
.
|
|
[...]
|
|
|
|
- Short sub options:
|
|
|
|
[...]
|
|
description. Available options are:
|
|
|
|
.DP 0
|
|
.RSs
|
|
.IPs "subopt1=<value>"
|
|
description1
|
|
.IPs "subopt2=<value>"
|
|
description2
|
|
[...]
|
|
.IPs "last subopt=<value>"
|
|
last description
|
|
.RE
|
|
.DP 1
|
|
.
|
|
[...]
|
|
|
|
|
|
- Sub options in sub options:
|
|
|
|
[...]
|
|
.IPs "subopt1=<value>"
|
|
description1
|
|
.RSss
|
|
subsubopt1: description1
|
|
.br
|
|
subsubopt2: description2
|
|
[...]
|
|
.REss
|
|
[...]
|
|
|
|
- Examples (like sub options, note: newline before and ':' after
|
|
.I EXAMPLE, .PD 0 before and .PD 1 after the examples):
|
|
|
|
[...]
|
|
|
|
.I EXAMPLE:
|
|
.PD 0
|
|
.RSs
|
|
.IP "-option used parameters"
|
|
description
|
|
[...]
|
|
.RE
|
|
.PD 1
|
|
.
|
|
[...]
|