[Gd-hackers] GD library documentation

[Dustin Voss]

On 14 Feb 2007, at 4:47 AM, Andreas Bogk wrote:

> Not that it matters much if you're going to restructure everything
> anyways, but you are aware that gdlibs.sgml is the source, and the  
> HTML
> file generated?

Yeah. But I'm not about to wade through the SGML. :)

I think the only difference between the SGML and the HTML is the  
table macro docs I added to the former. But it wouldn't hurt to  
update the HTML pages, just in case. Can someone take care of that?

> Dustin Voss wrote:
>> SO, that's the plan so far. I didn't want this to be a surprise to
>> anyone, hence this e-mail. Comments/concerns/suggestions?
>
> I have the feeling that it might be better to have some form of
> intermediate XML structure to be the documentation to edit, and  
> generate
> HTML, and possibly later print documentation, from that using XSLT,
> instead of editing the final HTML.

I propose that people edit the text files that generate the HTML, not  
the HTML itself. I agree, that would be Bad.

You can see what the text files look like from the "source  
material.zip" file in the same directory as the "html.zip" file I  
mention in the first e-mail.

I did consider using DITA plus the Dylan API extension. There are  
compelling advantages, but in the end I decided not to.

It is a tedious task to edit XML documents, especially when the  
documentation on how to use said XML structure is spotty. The  
simplicity of the text files means that they can be edited without  
studying how to use DITA tags.

Additionally, Natural Docs does some heavy lifting to set up indices;  
I don't know how to achieve that with a DITA document.

Finally, I greatly prefer static web pages to those generated on the  
fly, and the Dylan API extensions currently only work with the  
toolchain and CGI script that Peter Housel has set up on the server.

I hope that when the time comes to generate printed documentation,  
NaturalDocs will support that directly, or that the HTML pages could  
be converted to a more print-based layout using XSLT+CSS.