mirror of
https://github.com/mpv-player/mpv
synced 2024-12-15 19:35:49 +00:00
a53786f6c5
git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@8218 b3059339-0415-0410-9bf9-f77b7e298cf2
228 lines
7.3 KiB
Plaintext
228 lines
7.3 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, text or other versions 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 (IMHO due to a bug off gro2html).
|
|
A setting of 4 looks readable IMHO. Here's an overview again:
|
|
|
|
- groff: Groff is the "official" tool to convert man pages afaik.
|
|
To get good results you really 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
|
|
Check -T for other output formats.
|
|
- 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 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 it simplified...
|
|
|
|
|
|
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, .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 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 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:
|
|
|
|
[...]
|
|
|
|
.I EXAMPLE:
|
|
.PD 0
|
|
.RSs
|
|
.IP "-option used parameters"
|
|
description
|
|
[...]
|
|
.RE
|
|
.PD 1
|
|
.
|
|
[...]
|