[MPlayer-dev-eng] documentation structure

Diego Biurrun diego at biurrun.de
Mon Jul 8 03:50:02 CEST 2002


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

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

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

Please let me know what you think of it.


More information about the MPlayer-dev-eng mailing list