I just posted two OpenGL tutorials. This is the start of what I hope will be a long series of tutorials. Right now there's just a "Hello, world!" tutorial for the post-OpenGL 3.1 world (i.e., no immediate mode, no fixed-function) and a more in-depth tutorial for vertex shader inputs.
Since I want to produce PDF and HTML output, I'm authoring them in DocBook (or is it SGML? WTF?). It's mostly working out, but there are some things that I just can't seem to get to work right. The most frustrating part is that documentation for all of the SGML toolchains that I can find are crap. It's kind of ironic that the documentation for a document creation tool is so lacking...
My two biggest peeves are the crap figure handling in the PDF output and the crap table formatting in the HTML output. I can fix the HTML problems with CSS, but how is the tool makeing the output so bad in the first place? For the PDFs, seriously, a page break in the middle of a figure? Whose genius plan is that?!?
The other problem that I initial had was the lack of XInclude support in Jade. I "fixed" that using xmllint, but this seems like a fundamental feature to be missing from the tool.
Before anyone comments, I did consider using LaTeX. The main problem I have with LaTeX is the HTML output that it generates make me want to stab somebody. Every single time I come across an academics webpage that has been generated from LaTeX, I shed a lonely tear...
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:
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.
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.
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.
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