[Scummvm-devel] Documentation

Max Horn max at quendi.de
Thu Feb 5 18:28:09 CET 2004


Am 06.02.2004 um 02:50 schrieb James 'Ender' Brown:

>
> On Fri, 2004-02-06 at 05:46, Max Horn wrote:
>> Hiya folks,
>>
>>
>> I am sure all of you will agree that better docs would be nice... 
>> well,
>> I at least do think so :-). Of course writing docs is not something
>> everybody likes *cough* *cough*. :-)
>
> *snipidysnip*
>
> Believe it or not, I am actually good at writing proper manuals, coming
> from my previous incarnation as a tech-writer.

Great to hear :-)

>  My spelling and grammer
> aside (all of which just require somebody to proof-read).
<g> Seriously though, no matter who writes something, it's always good 
to have multiple other people proof read it. I don't think your 
spelling is particularly bad at all, Ender -- just that by using a 
spell checker, like other people (e.g. me) at least the most obvious 
mistakes could easily be avoided (like 'compatability' :-). In any 
case, I don't even know why I am spending so many words on this moot 
and obvious point... :-)

>  However, my
> main problem is that I do not know, and at first glance dislike, LaTeX.

Gah. That's always seems to be your reaction towards tech you don't 
know :-). No matter, though, while I love LaTeX, I wouldn't have chosen 
it for this particular task either...


> I agree with all your points, although I would suggest dedicating a
> portion to each supported game with a description and any release notes
> for it. And we really are 'complex' enough at this stage that a proper
> manual is indeed needed.

Yup yup. I have no problem with having a section on each supported game 
either. The whole TOC I posted was, after all, a quickly sketched up 
draft, so I imagine we'll change more of it anyway :-)

>
> Would anyone be willing to accept HTML as the source markup format? It
> is still easily convertable to text, PDF, Postscript, ectera.

Are there actually converters which produce nice PDF/PS/Text output 
from HTML? All the ways I know to convert HTML to PDF in the end are 
bad and I then prefer to stick to the HTML. Compared to pdflatex 
output, at least, which is very nice (including such things as a PDF 
TOC, and hyperlinks, etc., in the PDF). From the sounds of it, you have 
more experience with using HTML as a base for docs than I, so I hope 
you can shed some light on this :-)

>  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.


Cheers,

Max





More information about the Scummvm-devel mailing list