[MPlayer-dev-eng] [PATCH] Another DOCS patch

[Diego Biurrun]

Andras Mohari writes:
 > Some of them are already in CVS. ;)  There were some cosmetical and
 > structural changes, like:
 > 
 > * "How to read this documentation" is not numbered. :-)
 >   (It's a <preface>).

Actually, I want to remove that section (outdated, wrong and full of
errors) and start with

0 Introduction
1 Installation

 > * Emphasized text is in <em>, since the <emphasis> DocBook tag is
 >   converted to the <em> HTML tag.

Moving <B> to <EM> and <STRONG> makes a lot of sense and is on my
ToDo-list now that we have proper headings.

 > * Many uppercase words are in lowercase and emphasized.

These should definitely be emphasized by markup, not by uppercase.

 > * Important notes/warnings/hints are displayed in separate blocks
 >   (I've put everything starting with NOTE:/WARNING:/HINT: between
 >   <note>/<warning>/<tip>/<important> tags).

I've been thinking about using something like the em.note and em.warn
styles from skin-en.html throughout the HTML docs.  Ideas welcome.

 > * Made key captions uppercase (i.e. h -> H, so capital H would be
 >   written as Shift+H).  The reason is that that's the way they are
 >   printed on keyboards and they are *more* readable.  BTW, I changed key
 >   combos to use "+" instead of "-" (e.g.  Ctrl+Alt+F1); we should choose
 >   one form and stick to it.

I think we should stick to "-", "+" seems to be more common with
Windows apps.  I am not completely sure whether capitals are a good
idea.  Since Unix is case sensitive this may confuse people, this
sounds a bit like a Windowsism again.  I looked at a few apps, XEmacs
and GNOME control center (Unix) use Ctrl-j, Mozilla (cross platform)
uses Ctrl+F.  I'd say stick to "-" and lowercase.

 > * Added table heads to some tables.

Sounds OK, show us some code.

 > * Moved "Developer cries" into the appendix.

OK.

 > * Converted some unnumbered "sections" into numbered sections.

Depends, probably OK.

 > * Procedurized some instructions that were presented as <UL> lists.
 >   They are numbered in the XML version.

dito

 > * Options are listed in variable lists instead of tables.

Sounds OK, show us some code.

 > * Replacable option arguments are displayed in italics.

We should settle for something.  I think we currently use mostly
<option>, but I doubt this is consistent.

 > * The sound card list is actually a list (not a table, as in the HTML
 >   docs).

Sounds OK, show us some code.

 > * Some examples use very long lines (>80 chars), especially in the
 >   MEncoder section.  I used \ to break them in half.  I should have
 >   left them as they were...

Yes, probably.

 > That's all for now.  Which of the above should go in the CVS?

I'd say most of them, as explained above.  Some could use some further
discussion, but a complete review of the structure of the docs is due
anyway.

Diego