[Scummvm-devel] Documentation

[Max Horn]

Am 06.02.2004 um 03:56 schrieb James 'Ender' Brown:

[...]

> There are various automated tools which do a good job if given nice
> clean HTML. Text output is quite easy - I prefer using w3m's dump
> capability. Worst-case scenario is using something like KDE's "print to
> PDF" and "print to PS" functionality which produces quite nice output.
> Not as optimised as something thrown through specialist programs such
> as, for example, Distiller of course.

The major concern I have with using HTML as a source format is that 
with it you only specify the formatting/look of the docs, but not their 
logical meaning...

What I mean is this:With formats like TeX or DocBook and the others I 
listed, you write documentation structured by content and meaning; this 
then is (with the help of a preprocessor/XSLT engine/etc.) turned into 
a user viewable representation. Specifying the content by its semantic 
meaning allows for nice things, like automatically generated TOC / 
index; very easy to change the look (just transform the data 
differently); etc. Want to reorder everything? No problem, since 
chapters and tables are numbered automatically. Want all code sections 
to be in a different font than they are now? Trivial.

You can achieve that to an extent by writing pure HTML coupled with 
CSS, of course. But then, while I know how to turn that into PDF, you 
won't get a native PDF TOC, because the existing tools can't really 
know what should be in the TOC and what not. And none of the HTML->PDF 
conversions you mention above (and I might add in OSX' ability to turn 
anything into PDF via a simple "Print" command) approaches the quality 
of Latex/Docbook/... generated PDF. IMHO :-)


>>> If not, I suppose I could just write it in HTML and then convert it 
>>> to LaTeX that
>>> way.
>> That's always possible, of course.
>
> If nobody has any particular objections to using HTML, I would like to
> start on it next week.
>
I am not that comfortable with it, but once again, in the worst case we 
could convert it to yet another format...


Cheers,

Max