OpenGL tutorials

Use xmlto

2009-10-12T15:51:43Z

Ian,

If you use DocBook XML (not DocBook SGML), you can pretty easily use xmlto to handle all the tools for you. Furthermore, DocBook XML is typically converted using the stylesheets from DocBook XSL. There are a bunch of XSL parameters in the stylesheets that control the output.

See http://sagehill.net/docbookxsl/OptionsPart.html, http://docbook.sourceforge.net/release/xsl/current/doc/html/ and http://docbook.sourceforge.net/release/xsl/current/doc/fo/. Then you can do something like this:

$ xmlto --stringparam table.cell.border.style=solid xhtml myfile.xml

ReStructuredText+Sphinx and Asciidoc+Docbook

2009-10-12T19:00:11Z

Unless the DocBook is must-have, I'd also suggest to take a look on ReStructuredText and Sphinx-framework (http://sphinx.pocoo.org/). From my experience, it merges good sides from both DocBook and plaintext -format: technical documentation with easy-to-write -format.

Then again, there is also Asciidoc (http://www.methods.co.nz/asciidoc/), that can be turned transformed also into DocBook etc.

Math library

2009-10-12T19:00:11Z

Nice work! I've only skimmed those tutorials, but they sure will be useful to people.

One annoying thing I noticed when experimenting with foreward-compatible stuff is the lack of matrix manipulation functions. I think it would be nice to encourage people not to roll their own in this department. Personally, I've been happy with CML ( http://www.cmldev.net/ ), but there may be better alternatives out there.

RE: Math Library

2009-10-12T19:02:28Z

That's a good point about the math library. I've actually been working on a math library as well. My intention is for it to become a replacement for GLU on OpenGL 3.x systems. I still have a couple more things to do before I make it generally available, but it will show up in a future tutorial.

comment 5

2009-10-12T23:50:25Z

I use restructured text for documentation at work and it works pretty well. PDF looks nice and HTML output is clean.

The easy part is that it is very quick to type up documents. Most of the restructured syntax is just stuff I already did when working in plain text. Very easy, almost no markup to memorize.

RE: Use xmlto

2009-10-13T07:39:46Z

Too bad my document make PassiveTeX explode. I hit the same bug everyone else hits when using xmlto to generate PDF from DocBook. sigh...

Bad xmlto

2009-10-25T01:42:48Z

That sucks. You can try "xmlto --with-fop ...". I used to work on LinuxFromScratch, and the whole book was docbook. The PDFs were always generated using the fop toolchain and they came out pretty well. The xmlto default backend seems to be passivetex for producing dvi/pdf/ps. I don't know anything about that.

http://www.linuxfromscratch.org/lfs/downloads/stable/LFS-BOOK-6.5.pdf