glsdk-devel

[Glsdk-devel] Documentation

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

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.

Branan

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.

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
>

Re: [Glsdk-devel] Documentation

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

On Fri, Aug 29, 2008 at 9:46 AM, Branan Riley <br...@gm...> wrote:
> 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.

I'm not sure I understand what you're talking about when you refer to
programs that are "layered on top of XSLT." Can you give me an
example?

We should not be looking for any XSLT implementation on the host
system. Instead, our system for building documents should use a
specific XSLT implementation (which takes specific command-line
arguments), and we should simply deliver the results.

Re: [Glsdk-devel] Documentation

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

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

On Fri, Aug 29, 2008 at 11:01 AM, Jason McKesson <ko...@gm...> wrote:
> On Fri, Aug 29, 2008 at 9:46 AM, Branan Riley <br...@gm...> wrote:
>> 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.
>
> I'm not sure I understand what you're talking about when you refer to
> programs that are "layered on top of XSLT." Can you give me an
> example?
>
> We should not be looking for any XSLT implementation on the host
> system. Instead, our system for building documents should use a
> specific XSLT implementation (which takes specific command-line
> arguments), and we should simply deliver the results.
>
> -------------------------------------------------------------------------
> 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
>

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.