[Scummvm-devel] Documentation

[Max Horn]

On Do, Dezember 20, 2007 12:40, Henry Bush wrote:
>

[...]

> Hopefully you can see where my concerns lie.

Yes, perfectly. I had and have those concerns myself.

> It would be great if,
> when something changes, the dev could add it to the docs in one place
> and run an "update docs" script or something, but I just can't see how
> that could work.

That was *precisely* why I went with DocBook back then -- the idea was
that this way it's trivial to produce a HTML version for the Website, as
well as a plain text / PDF version for inclusion in release tar balls.

However, the hurdle for editors is bigger with DocBook than it is with the
Wiki. It's just more convenient to edit the Wiki. But it's not quite as
easy to generate good single-page HTML or PDF versions of it (at least as
far as I know -- I'll be happy to learn how to do it, if there is a good
way!).

Maybe there are other formats than DocBook which are easier to setup. We
tried LaTeX, but it just isn't suitable, it seems (I say that even though
I am a big fan of it in general, for math papers at least ;).

Maybe e.g. AsciiDoc would be better... but in the end, a Wiki is probably
always more attractive for editors...
Maybe we could mitigate the problem a bit if we used DocBook (or AsciiDoc,
or whatever), but would put auto-generated versions of the Manual onto the
website ?

What would *you* prefer, as a very active editor?


> I've spent quite a bit of time on the wiki manual
> recently, but I'm loathed to spend much more if we're going to get to
> a 1.0 release (which would, admittedly, be great), then the docs just
> fall apart because they're too difficult to update.

Indeed. We suffer from the problem of content duplication. We have a
central compatibility list, but we also have several compat tables in the
Wiki, for example -- port specific ones as well as game specific ones.
Ideally, there would be a single "database" (and that could be a simple
text file or a real SQL db, I use the word in the most general sense)
which contains information like that, and other spots would
(semi)automatically be updated when it gets changed. Right now, that's not
really possible, I think.

Note that we do something like this already for the MD5 tables, as well as
for the AUTHORS/credits lists. It should be possible to do this for
compatibility data, in one of several possible ways.

Other parts of the docs, however, are relatively static. There, the main
problem is to keep the README and the "manual" in sync. However, once we
have a real manual, that will becomes a non-issue -- we will then just
change the README to a very very short file with only the bare bone
information, and referring to the manual.


>
> Does anyone share my worries?

Aye :)


Bye,
Max