documentation internal structure
Hi! I already posted this some time ago, Gabu and Arpi please comment if you are against this, else I will begin in a few days.. 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?) We should settle on one of the three forms. MPlayer FAQ would also be a possibility of course, but I prefer the other alternatives because the information that differentiates the documents is up front - if you can only read the "MPlayer" in the window/tab title you still cannot tell them apart... 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 This also makes ordering subsections or inserting subsections at a place that makes sense instead of the end a real PITA. 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. Please let me know what you think of it. Diego
Hi,
Hi!
I already posted this some time ago, Gabu and Arpi please comment if you are against this, else I will begin in a few days..
Please let me know what you think of it.
i like the idea but do we really need it, close to teh xml conversion so to the generated html files? A'rpi / Astral & ESP-team -- Developer of MPlayer, the Movie Player for Linux - http://www.MPlayerHQ.hu
Arpi writes:
I already posted this some time ago, Gabu and Arpi please comment if you are against this, else I will begin in a few days..
Please let me know what you think of it.
i like the idea but do we really need it, close to teh xml conversion so to the generated html files?
How close is close? Looking at the ToDo 0.90 still seems to be some time away and the docs will remain with 0.90 until the next release which will probably take quite a few more month or a year, who knows... I believe it is worth the effort. The conversion should become much easier after this cleanup. Andras copied and pasted the text from his browser (!) into his editor to convert. Hopefully with structured HTML this can be done in a semiautomatic way. Changing the labels from numbers to something sane has to be done in the XML anyway, so the sooner the better. Diego
Hi,
I already posted this some time ago, Gabu and Arpi please comment if you are against this, else I will begin in a few days..
Please let me know what you think of it.
i like the idea but do we really need it, close to teh xml conversion so to the generated html files?
How close is close? Looking at the ToDo 0.90 still seems to be some time away and the docs will remain with 0.90 until the next release which will probably take quite a few more month or a year, who knows... I believe it is worth the effort.
hmm. you're right :)
The conversion should become much easier after this cleanup. Andras copied and pasted the text from his browser (!) into his editor to convert. Hopefully with structured HTML this can be done in a semiautomatic way. Changing the labels from numbers to something sane has to be done in the XML anyway, so the sooner the better.
ok A'rpi / Astral & ESP-team -- Developer of MPlayer, the Movie Player for Linux - http://www.MPlayerHQ.hu
but do we really need it, close to teh xml conversion so to the generated html files? My 2 cents: the XML conversion will never occur :) (I'd like if I'd be wrong...)
-- Gabucino / Worshipping Niedermayer 4ever / "Do you always look at it encoded?" (C) D. R. F.
Am Son, 2002-08-04 um 19.59 schrieb gabucino@woodstock.localdomain:
My 2 cents: the XML conversion will never occur :) (I'd like if I'd be wrong...)
I wouldn't bet on it.... :) -- Servus, Daniel
Daniel Egger writes:
Am Son, 2002-08-04 um 19.59 schrieb gabucino@woodstock.localdomain:
My 2 cents: the XML conversion will never occur :) (I'd like if I'd be wrong...)
I wouldn't bet on it.... :)
Me neither, but at the moment it looks like Andras will have the last word on this... Diego
On Mon, Aug 05, 2002 at 00:25:37 +0200, Diego Biurrun wrote:
Daniel Egger writes:
Am Son, 2002-08-04 um 19.59 schrieb gabucino@woodstock.localdomain:
My 2 cents: the XML conversion will never occur :) (I'd like if I'd be wrong...)
I wouldn't bet on it.... :)
Me neither, but at the moment it looks like Andras will have the last word on this...
I'm here, still alive, and ready to do the conversion. But as I wrote in my previous mail, I don't have too much time, maybe just this year. P.S.: Diego, don't worry about cut&paste -- I realized that using the source is not that bad at all. :) -- Andras Mohari mayday@mail.nagyatad.hu
Hi,
but do we really need it, close to teh xml conversion so to the generated html files? My 2 cents: the XML conversion will never occur :) (I'd like if I'd be wrong...)
at least you do everything possible to avoid it... A'rpi / Astral & ESP-team -- Developer of MPlayer, the Movie Player for Linux - http://www.MPlayerHQ.hu
On Sun, Aug 04, 2002 at 19:59:43 +0200, Gabucino wrote:
but do we really need it, close to teh xml conversion so to the generated html files? My 2 cents: the XML conversion will never occur :) (I'd like if I'd be wrong...)
If 0.90 will be released next year, then you are probably right. I'm not sure if I'll have net access (or even a job) next year...but some chapters are already converted, so someone can convert the rest if I can't. -- Andras Mohari mayday@mail.nagyatad.hu
1) Add a title to all the documents. I don't need it (I use Opera:) but do it if you want.
2) Change the link labels to something more descriptive. Agreed with all the ideas. Apparently I didn't think of the future when I designed the TOC.. :( And already saw this problem when I was doing HTML->SGML
3) Make use of the different heading tags for section titles. Maybe. Do it if you have time :)
-- Gabucino / Worshipping Niedermayer 4ever / "Do you always look at it encoded?" (C) D. R. F.
Gabucino <gabucino@localhost.localdomain>, <gabucino@woodstock.localdomain> writes:
1) Add a title to all the documents. I don't need it (I use Opera:) but do it if you want.
Done already. Opera also displays the titles ;)
2) Change the link labels to something more descriptive. Agreed with all the ideas. Apparently I didn't think of the future when I designed the TOC.. :( And already saw this problem when I was doing HTML->SGML
You did not even think of the present ;) Some links were pointing to the wrong location, because their section apparently got renumbered. Anyway, it's done now, just remind me to hit you with a big stick if we meet in person ;-)
3) Make use of the different heading tags for section titles. Maybe. Do it if you have time :)
Not today, but I will do it. Expect it for 0.90. Diego
participants (5)
-
Andras Mohari -
Arpi -
Daniel Egger -
Diego Biurrun -
Gabucino