======================================== 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 ). - 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 description [...] - Long suboptions: [...] description. Available options are: . .RSs .IPs "subopt1=" description1 .IPs "subopt2=" description2 [...] .IPs "last subopt=" last description .RE . [...] - Short suboptions: [...] description. Available options are: .DP 0 .RSs .IPs "subopt1=" description1 .IPs "subopt2=" description2 [...] .IPs "last subopt=" last description .RE .DP 1 . [...] - Suboptions in suboptions: [...] .IPs "subopt1=" description1 .RSss subsubopt1: description1 .br subsubopt2: description2 [...] .REss [...] - Examples: [...] .I EXAMPLE: .PD 0 .RSs .IP "-option used parameters" description [...] .RE .PD 1 . [...]