[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