[MPlayer-dev-eng] documentation HOWTO

[Diego Biurrun]

Moving this thread here from mplayer-cvslog.

Gabucino writes:
 > Diego Biurrun wrote:
 > >  > Log Message:
 > >  > changing "switch" -> "option" (unwritten DOCS rule)
 > > Whatever you wish, but these will have to be written down some day.
 > Good idea.
 > 
 > > have a half-baked documentation.txt in my local tree, but it's just
 > > notes.
 > Post it if you wish and we could complete it.

It's just random notes that I have been collecting.  We might also add
the most common spelling errors and many more things.  Ideas?

Here it goes:


  HTML docs
  - UPPERCASE, keep document style
  - <CODE> for '/etc/mplayer.conf'</CODE>
  - MPlayer, not mplayer, unless you mean <CODE>mplayer</CODE>
  - MEncoder, not mencoder, unless you mean <CODE>mencoder</CODE>
  - no HTML editors, please
  - punctuation directly after a word. not word .
  - A'rpi
  - 79 (80?) chars wide text
  - don't forget to update the TOC
  - labels should be of the form "section_subsection"
  - say option instead of switch
  
  - whitespace:
    - two linebreaks after each section
    - one after each paragraph
    - no trailing whitespace
  
  - prefer definition lists for explaining parameters
  
  text docs
  - 79 chars wide text
  
  man page
  - 2 spaces between options and descriptions
  - check columns to fit 80 character displays