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