[MPlayer-dev-eng] documentation internal structure

[Diego Biurrun]

Hi!

I already posted this some time ago, Gabu and Arpi please comment if
you are against this, else I will begin in a few days..

I have a few changes to the structure of the documentation in mind:

1) Add a title to all the documents.

The "Untitled" MPlayer documents are annoying.  You never know which
window is which, especially when using tabbed browsers.
As titles I suggest

faq.html -->

FAQ
FAQ - MPlayer
FAQ - MPlayer the Linux movie player
(BTW shouldn't this be changed to Unix movie player?)

We should settle on one of the three forms.

MPlayer FAQ would also be a possibility of course, but I prefer the
other alternatives because the information that differentiates the
documents is up front - if you can only read the "MPlayer" in the
window/tab title you still cannot tell them apart...


2) Change the link labels to something more descriptive.

Currently we use the section numbers as labels.  This is very
fragile.  I have already corrected a few links that were pointing at
the wrong sections, apparently because some reordering had taken place
in the past.  With a descriptive label this should never be an issue.

As labels I suggest the section titles in lowercase or the most
important term from the title, like "Setting up MTRR" --> "mtrr".  If
there is no single descriptive term or it may be confused with
another, I suggest using underscores instead of blanks, since blanks
always cause quotation nightmares:

Software AC3 decoding --> software_ac3
Hardware AC3 decoding --> hardware_ac3

This also makes ordering subsections or inserting subsections at a
place that makes sense instead of the end a real PITA.


3) Make use of the different heading tags for section titles.

At the moment all section titles look like

<P><B>Some Title<P><B>

You cannot tell a section from a subsection at a glance.  The docs are
lacking semantical structure this way and customization with style
sheets becomes impossible.  I'd like to give sections h1 tags (would
h2 be better?), subsections h2, subsub...
This will also aid an eventual transition to XML/SGML as some
semantical structure will be present and conversion may be done
automatically.


Please let me know what you think of it.

Diego