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

[Diego Biurrun]

gabucino at mplayerhq.hu wrote:
>> > * "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
> 
> How could it be outdated? :o Why remove?

It claims to be complete, which it isn't, it says you cannot do things 
that are not in the manual, which you can.  It contains an obnoxious 
quote from Chris Phillips that gives a wrong impression when first 
reading the manual.

>>0 Introduction
>>1 Installation
> 
> No way.. IMHO only "How to read" should be section 0, interpreted as
> "before you start reading the real docs.."

Introduction currently contains two different chapters: introduction and 
installation, this should be split in two.  Calling the introduction 
chapter 0 is a way to get around renumbering the whole manual.  But as 
Andras said, "How to read" is more of a foreword, so it should probably 
be left out of the numbering scheme entirely:

   How to read...
0 Introduction
1 Installation

>> > * Added table heads to some tables.
> 
> Only if needed and looks nice.

Yes, I'd also like to see it first.

>> > * Moved "Developer cries" into the appendix.
>>OK.
> 
> At first I though NO, but let's see.. Users should read it, that's the
> important.

It's basically historical anecdotes.  None of it is currently very 
relevant any more, so I think an appendix is OK.

>> > * Converted some unnumbered "sections" into numbered sections.
>>Depends, probably OK.
> 
> Probably not OK :) But depends.

Let's see what it looks like.

> I think it would be nice if we could trace the evolving of the XML DOCS
> in CVS. Why not commit it? Like DOCS/SGML. (that should be removed, BTW)

I was planning to remove SGML/ when I come home anyway.

XML should not be committed yet, we will only duplicate a lot of work. 
Let's try to get the HTML docs up to speed for 0.90 and then freeze them 
for the conversion.  The old version of the XML docs should still be up 
on the web or in the archive, but it was going out of sync very fast and 
contained some changes made by Andras.  If these get discussed and 
(partially) merged now, he won't be tempted to change the docs during 
the conversion ;)

>> > 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.
> 
> Yes. However, it would be nice to see the patch here before it gets
> commited.

Of course, but Andras does not have CVS privileges (yet) anyway.

Diego