[MPlayer-dev-eng] [DOCS] restructured faq.html

[Diego Biurrun]

Hi!

Gabucino and/or Arpi should probably also comment on this, here are my
opinions.

On Fri, Jul 12, 2002 at 12:42:05PM +0200, Andras Mohari wrote:
> On Fri, Jul 12, 2002 at 05:21:58 +0200, Diego Biurrun wrote:
> > Sorry for confusing you, if you convert the docs, they will be in
> > DocBook.  XHTML was discussed as one of the different alternatives and
> > I was thinking out aloud.  Conversion to XML/SGML has been planned for
> > so long that I have become somewhat sceptical :-(
> 
> OK, I thought I missed something. :)
> (As for the conversion: nearly all chapter and section titles are
> added, so the TOC is more or less complete.  'Introduction' is finished,
> and 'Features' is finished up to 'SDL'.)

Great!

> > While we are already at the subject..  Are there any steps we can take
> > to help you with the conversion?
> 
> Hm, I have some questions, and it would be great if I got some answers
> to clear things up a bit.
> * I've decided to use multiple XML files instead of one huge (>200K)
>   file.  The files are in different directories; this is the directory
>   structure:
> 
> 	|--html			(the generated HTML files (English))
> 	|  `--xx		(the same, but for language xx)
> 	`--xml			(Makefile, stylesheets, common files)
> 	   |--en		(source in English)
> 	   `--xx		(source in xx)
> 
>   Is it OK?

OK with me, I trust you with this since I do not have much experience with
XML.

> * I don't use the same filenames as in the documentation.  Is it OK?

OK with me.

> * Each HTML file contains a chapter.  This means that, for example,
>   everything in 'Features' goes into one big file...  Is it OK?
>   (The chunk depth can be set to chapters, sect1/2/3/... sections,
>   but I think it's not possible to output a specified section into a
>   separate file.)

Hmm, this will change the current structure.  I do not have a problem with
that.  We probably should rethink the whole structure at this point, since
it will get overhauled anyway.

> * I moved 'Developer cries' into the appendix, because it wouldn't have
>   fit into the structure of the documentation otherwise.  I hope it is
>   not a problem...

OK with me.

> * Should I put the contents of the DVB and DXR3 files in the
>   documentation, or should I add links to them?  (I can't add links now,
>   since I don't know the final path for the doc.)

These should be added to the documentation.  This has been on my ToDo list
for some time.  I'll do it in the next few days to help you.

> * Although I wasn't allowed to make changes to the documentation, there
>   are some things that I had to change.  I can't remember anything
>   specific now... (Maybe I should make the stuff available for download
>   so that you can see it for yourselves...)

Yes, please make it available for download, I'm interested.  Maybe we can
help you keep the DocBook in sync with the HTML then.

Don't worry too much about small changes, but try to remember what they
were, so they can easily be reviewed.

> * 'MPlayer is under GPL v2 license.' should be near the title (DocBook
>   has a nice tag for this).  Actually, the text should be replaced with
>   the usual short GPL license statement.  Can I do this?

Sounds nice.  OK with me.

> * There are some short 'Overview' and 'Summary' sections, while their
>   parent sections are empty (they are just placeholders for their
>   subsections).  May I move their contents into their parents?

Yes, makes a lot of sense.  OK with me.

> * (Sometimes I can hardly resist the temptation to change something.
>   Have you got anyting against this? ;-))

Changes are welcome but subject to review.  If you want to change something,
it would be best to send a patch here so that we can merge it into the
current documentation.  This way everybody can profit from your change
earlier and they will be recorded in the CVS history.

> > Does the stuff I described in this mail help you?
> > 
> > http://mplayerhq.hu/pipermail/mplayer-dev-eng/2002-July/009494.html
> 
> I agre with all those suggestions, but they don't really help me with the
> conversion:
> 1) DocBook adds titles automatically.
> 2) I've already added descriptive link labels (eg. swac3, hwac3,
>    users-vs-dev). I had to do it, because the TOC is generated
>    automatically, so I don't know the chapter/section numbers in advance
>    (and I wouldn't use them even if I knew them ;)).
>    By the way, these labels are used for the HTML filenames, so it's
>    very important not to use silly numbers.
> 3) The lack of heading tags for section titles isn't really a problem
>    for me, because I can find out the section level from the numbering.

OK.

> +1) I don't use the HTML source -- I cut&paste from a browser window,
>     and add the DocBook tags to the text.

Oh dear, you sure it isn't easier with some sort of search and replace over
the sources?

> > Do you prefer uppercase or lowercase or whatever ...
> 
> I prefer lowercase (easier to type).  Anyway, XML tags are
> case-sensitive, and the DocBook XML DTD uses lowercase tags,
> so uppercase tags are out of the question. ;)

Shouldn't make a difference if you cut+paste from a browser window, I was
thinking about search+replace.  But probably not a big difference anyway.
Regards

Diego