Comments on: Building a new technical documentation tool chain

By: Steve

Steve — Sat, 06 Nov 2010 10:58:58 +0000

Thanks Francis, it’s interesting to see the Pygment route which I never got around to exploring.

By: Francis Shanahan

Francis Shanahan — Fri, 05 Nov 2010 18:21:33 +0000

Thanks Steve, this helped a lot. I documented my setup with Graphviz and Pygment for my own future reference and some updated versions of other software here:

http://francisshanahan.com/index.php/2010/setup-asciidoc-fop-pygment-on-windows/

Thanks again,
fs

By: Steve

Steve — Tue, 16 Mar 2010 10:14:01 +0000

No, but the output looks quite nice. Still, I do still like the ability to go via DocBook.

By: Andy

Andy — Tue, 16 Mar 2010 02:03:42 +0000

Did you happen to look at Sphinx at all (http://sphinx.pocoo.org/) ??

By: Steve

Steve — Tue, 09 Mar 2010 10:16:57 +0000

I hadn’t seen quickbook before, was quite hard to find even in Google unless you knew it was in Boost. Looking at it, I prefer AsciiDoc; the syntax is a bit nicer and AsciiDoc appears to be more regularly maintained.

By: OvermindDL1

OvermindDL1 — Tue, 09 Mar 2010 02:46:12 +0000

Oh, and yes Quick/BoostBook uses a Wiki-style syntax for the initial formatting, *FAR* easier to use then XML obviously.

By: OvermindDL1

OvermindDL1 — Tue, 09 Mar 2010 02:39:51 +0000

I am curious, have you not looked at quickbook? It is based on docbook with lots of bug fixes, a heavy emphasis on C++, doxygen integration, PDF/HTML/others output, etc… It is part of Boost (which you are already using in OGRE), and boost has a subproject called boostbook (specialized boost formatting and such for a universal look-n-feel for all projects in boost) that you can easily rip from. They encourage its use. Have you not looked it?

Boost.ASIO docs use just about every possible feature if you want a good example.

By: Steve

Steve — Mon, 08 Mar 2010 16:01:01 +0000

@Nicholas: yeah, the stylesheet link was buried a little there. I’ve edited that section and hopefully made it more useful.

@Stodge: no problem!

I successfully followed my own instructions here to get the same tool chain working on Mac OS X (I just added a couple of clarifications such as using ‘:’ instead of ‘;’ to separate classpath entries). It works like a charm! I have no reason to believe it wouldn’t work the same on Linux too.

By: Stodge

Stodge — Mon, 08 Mar 2010 15:42:21 +0000

Awesome – thanks for this. May be useful to us at work…

By: Nicholas

Nicholas — Sun, 07 Mar 2010 17:27:33 +0000

I get it.. style (as in bold/italic, etc.) is applied by importing the docbook transforms (aka stylesheets) into a custom transform (fo_steve.xsl). I zapped over your fo_steve.xsl.txt link!