Re: [Glsdk-devel] Documentation

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

Branan Riley wrote:
> Since we've decided on DocBook files for our documentation, we now
> have the question of how we're going to convert those into HTML, PDF,
> or whatever format we decide upon.
>
> There are lots of tools for this, but I don't  know which ones are
> cross-platform, and which ones will meet our needs. I can't make CMake
> generate our docs until I know what tool we're using for it.
>   
There's really only 1 tool for transforming XML into other things: XSLT. 
It is a language for converting XML documents into other XML documents 
(though it can also output text and non-X-HTML).

The two most common XSLT processors are Saxon (Java) and the LibXML2 (C) 
XSLT processor. There are Saxon processors for XSLT 1 and 2, but LibXML2 
only supports XSLT 1. Fortunately (or unfortunately, if you like XSLT 
2), the only XSLT documents that are in the wild are version 1; the 
complexity of writing a version 2 processor tends to keep people away 
from it (despite the fact that Saxon's XSLT 2 implementation has been 
available for a good 2 years now).

DocBook XSL is generally the common way of transforming DocBook into 
various output formats. Converting DocBook to PDF requires an additional 
tool: Apache FOP (or another XSL-FO processor), which is a Java tool. 
Indeed, most XSL-FO processors are Java, but FOP is the only free one of 
any real quality that I know of.

Also, CMake should not be generating our docs at all. I wouldn't want to 
force Java on someone just to give them PDF. The documentation building 
should be done when we go about the process of making a release, and the 
final documents should be part of that release.

However, I would suggest we hold off on dealing with the documentation 
conversion issue for the time being. My main focus at present is on GLE, 
and document conversion needs to deal with formatting questions that I 
don't have time to focus on right now.