Borkware Miniblog

August 17, 2007

The tools behind the book

Filed under: amosxp — Mark Dalrymple @ 9:10 pm

A discussion on my Local Linux User’s Group‘s mailing list talks about Open Source tools used to write books.For the curious and/or terminally bored, here are the tools that were used to make AMOSXP:

Along with makefiles and perl scripts to hold everything together. It was a real PITA to get build and configured. But once that horror was dealt with, it’s a fun toolchain.



  1. No wiki software?

    I’m going to be using a wiki to write mine.

    Comment by Christopher Humphries — August 24, 2007 @ 1:26 pm

  2. Nope, no wiki sofware. Wiki editing gives me hives.

    One interesting thing that fell out of the use of DocBook was being able to get just the structure of the book out of the source files, and we used that to build a database to hang things like errata and discussions off of.

    Turned out to not be *that* useful, so we didn’t do that for the second edition.

    Comment by Mark Dalrymple — August 24, 2007 @ 1:29 pm

  3. Wow, you used ALL those tools together? Sounds like a pain.

    I like the wiki because it is simple and can interconnect everything together, yet I haven’t written a book yet so have no experience or lessons-learned.

    Can you explain how you did use emacs (awesome) + TeX + DocBook?

    I’m missing the process flow, I guess. Can you enlighten a newbie writer?

    Comment by Christopher Humphries — August 24, 2007 @ 1:40 pm

  4. I liken it to AmWay. Aaron had the docbook toolchain installed and used that for Cocoa Programming for Mac OS X, and since this was my first book, I naturally used the tools of my co-author.

    The actual workflow is pretty simple. We’ve got a makefile that takes the docbook, runs it through openjade (which produces TeX), then PDFTex (which produces the PDF), and also through some perl scripts and magic happens so that an index is automatically made (I think TeX might do that too). So all I have to do is edit my DocBook files, type “make Book”, and then some period of time later I have a PDF. This PDF is what we deliver to the publisher.

    For emacs, I use sgml-mode and nxml mode. nxml mode gets confused occasionally when looking for errors because we’re using the SGML version of DocBook and not the XML version. sgml-mode gets used occasionally because it has a very nice ‘hide tags’ mode.

    For most folks, this is totally insane, and getting the toolchain set up is atrociously ugly. So many moving pieces. Don’t even think about using MacPorts or Fink, since it’ll fall over when dealing with TeX (a MacPorts apologist in a channel said “oh. Don’t use MacPorts for TeX. It’s awesome for everything else”). But for me it fell over when I needed it.

    Much will depend on your publisher. O’Reilly and Spiderworks want Word documents, so doing the DocBook thing would be crazy.

    Comment by Mark Dalrymple — August 24, 2007 @ 1:52 pm

RSS feed for comments on this post.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Blog at