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

[Andras Mohari]

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

> 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?
* I don't use the same filenames as in the documentation.  Is it OK?
* 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.)
* 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...
* 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.)
* 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...)
* '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?
* 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?
* (Sometimes I can hardly resist the temptation to change something.
  Have you got anyting against this? ;-))

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

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


Oops, it's lengthy, but this is my last chance to reply
this week -- I don't have inet access at home.

-- 
Andras Mohari
mayday at mail.nagyatad.hu