[Scummvm-devel] Documentation

Max Horn max at quendi.de
Sat Dec 22 22:39:12 CET 2007


Am 22.12.2007 um 02:07 schrieb James 'Ender' Brown:

> I'm probably partly to blame with originally pushing for a  
> wiki'fication
> of the manual, as writing in DocBook or LaTeX is daunting to some
> people... and even people with SVN write access were on occasion
> updating the generated alternate formats instead of the source file.

Actually, no. You have no blame for this part of the manual story (if  
at all, I would slightly blame you for making me wait for months for  
some mysterious "HTML manual" you supposedly started, before I  
decided to create a DocBook one of my own ;-).

Truth is, this was an attempt to get more attention to the Wiki work.  
It initially failed, and only after a second push, trying to attract  
contributors, did it succeed to attract about 1.5-2 extra helpers *g*.

And for those, it seems it's not that LaTeX or DocBook is that  
daunting... Although being able to work on the manual from anywhere  
is of course a bonus!


>
> On the other hand, it is fairly simple to export the current manual in
> the Wiki as a variety of HTML formats (multi-page, single-page).

It is? Cool, please tell me how, because I have no idea how we would  
generate a single page version of the manual right now. That's an  
important requirement, and the lack of it is one of my main  
motivations to eventually move away from the Wiki again with the  
manual. But if you say it can be done, cool. But how?


> These
> can in turn be processed to fairly nice PDF using a variety of means,
> although there has been some argument in the past about optimization
> (personally, KDEs Print to PDF using KHTML to render and GS to  
> generate
> PDFs always seems to come out nicely for me).
>
> HTML is easy enough to render in plain text, PDF, eCHM, and of course
> multi-page and single-page HTML.

Actually, multi & single page HTML plus PDF are the only required  
ones, IMO.
But I don't think that plain text created from HTML is such a good  
idea. All methods I know of (which all essentially imply using some  
text browser to render the HTML as text) are lacking. I tried them a  
lot for the DocBook manual, and I don't like any of them. If we  
really want a plain text manual, we should consider using ReST or  
AsciiDoc to create the manual. Or export the Wiki source code  
directly (it contains lots of meta info which is lost in the dumb  
HTML->TXT conversion).

>
> The next step would actually be to use some kind of pseudo-template
> language if we _really_ wanted to produce multiple documents from the
> same source - eg, a cutdown README and a full-blown Manual. But how  
> much
> material is really shared verbatim?

Nah, I don't think we should do that. The README would become a very  
small static file, virtually unchanged between releases, which would  
simply point to the manual.

BTW, one advantage of having the manual version controlled (with  
tags) is that we can provide it in various versions (i.e. I imagine  
the 0.11.0 manual might look different from the 1.0 or 1.5 one in  
various regards).


Bye,
Max




More information about the Scummvm-devel mailing list