Re: [Glsdk-devel] Documentation

[Branan R. <br...@gm...>]

Yes, technically XSLT is the only way to transform it. I meant there
are a number of programs already created that are already layered on
top of XSLT, at least in Linux. I don't know about the Windows and Mac
worlds. If we can use on of those, it saves us the trouble of writing
our own.

As for forcing people to build docs, I can add a GLSDK_DOCS flag just
like we have a GLSDK_TEST flag, so CMake only builds the docs when you
want it to.

Branan

On Fri, Aug 29, 2008 at 9:42 AM, Jason McKesson <ko...@gm...> wrote:
> 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.
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
> Build the coolest Linux based applications with Moblin SDK & win great prizes
> Grand prize is a trip for two to an Open Source event anywhere in the world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> Glsdk-devel mailing list
> Gls...@li...
> https://lists.sourceforge.net/lists/listinfo/glsdk-devel
>