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