Re: [Glsdk-devel] Documentation

[Jason M. <ko...@gm...>]

On Fri, Aug 29, 2008 at 11:19 AM, Branan Riley <br...@gm...> wrote:
> In most linux distributions, there are already tools that convert
> docbook to other formats - for example, the docbook-utils package has
> several commands that read docbook files and output PDF, html, man
> pages, even RTF.
>
> If there is a set of tools like this that is available cross-platform,
> we don't have to worry about writing any java/c/python/whatever code
> to handle docbook files - we just tell people that want to build the
> docs themselves what they need to download.
>
> If we just want to convert docbook to HTML or another XML format, a
> home-grown XSLT-based solution is probably fine. If we want to be able
> to make other formats, an already-written tool is probably better.
>
> Branan

Windows does not come with a set of DocBook tools. I can't speak to MacOSX.

But my other point still stands: we should not be relying on the user
to build their own documentation. Or, more specifically, the user
should not need to "build" documentation if they want it. Our
distribution should contain documentation in the final forms, not just
DocBook. With the exception of man pages, the final documentation is
all platform-neutral.

I know that's the *NIX thing to do, having a special build to make
documentation, but it's very much not standard procedure on other
platforms.

As for the tools themselves, DocBook XSL is the standard, which
produces reasonably decent documentation.