diff options
Diffstat (limited to 'DOCS/OUTDATED-tech/manpage.txt')
| -rw-r--r-- | DOCS/OUTDATED-tech/manpage.txt | 283 |
1 files changed, 283 insertions, 0 deletions
diff --git a/DOCS/OUTDATED-tech/manpage.txt b/DOCS/OUTDATED-tech/manpage.txt new file mode 100644 index 0000000000..f3ad7fd355 --- /dev/null +++ b/DOCS/OUTDATED-tech/manpage.txt @@ -0,0 +1,283 @@ +======================================== +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 + . + [...] |