[MPlayer-dev-eng] documentation structure

[Alex Beregszaszi]

Hi,

> 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?)
what about "MPlayer FAQ" ?

> 
> We should settle on one of the three forms.
> 
> 
> 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

nice idea

> 
> 
> 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.

-
alex