How to Convert AuthorIT to DocBook

Because the public demanded it! This is really just an overview of the process, but it should give you a basic idea about what to watch out for.

  1. Convert your AuthorIT book to DITA.

    DITA (Darwin Information Typing Architecture) is one of AuthorIT’s built-in publishing formats. Publishing to DITA results in a folder containing your book’s image files, a collection of *.dita files, and a toc.ditamap file.

    Sadly, you must take this opportunity to wave your index markers a fond farewell. They are apparently too old and frail to survive this stage of the journey.

  2. Download the DITA Open Toolkit.

    The DITA Open Toolkit (DITA-OT) is a collection of Apache Ant scripts, XSL stylesheets, and other goodies that enable you to transform DITA into other formats, including DocBook. For those of you who don’t live in the Java world, Ant is basically make for Java. Newer versions of DITA-OT conveniently include a copy of Ant, so you don’t need to install it separately.

    To install DITA-OT, unzip the toolkit’s files into any directory and run the script (or startcmd.bat script on Windows) to configure your CLASSPATH and other environment variables. If you forget to set your CLASSPATH, the toolkit will helpfully indicate this to you by bailing out mid-transformation and complaining that the Ant script is broken.

    Before you run any DocBook transformations, edit xsl/docbook/topic2db.xsl and comment out the template that contains “Related links”. The only thing this template does is riddle your DocBook with invalid itemizedlist elements.

    Do not waste time reading the toolkit’s documentation. The manual that ships with DITA-OT 1.3 actually applies to DITA-OT 1.2, so most of the examples are broken. As for grammar and clarity, let’s just say that the manual’s translation from the original Old Frisian leaves much to be desired.

  3. Transform the DITA document into DocBook.

    All the toolkit’s transformations involve running an Ant script:

    ant options targets

    To transform DITA to Docbook, run:

    ant -Dargs.input=path/toc.ditamap dita2docbook

    If the transform fails (and all your environment variables are set correctly), there might be errors lurking in your generated DITA source. This is AuthorIT’s way of telling you, “Don’t let the door hit you on the way out, jerk!”

    • If DITA-OT complains about a missing topic reference, there’s a good chance toc.ditamap is referencing a topic that doesn’t exist. Go back to the original AuthorIT doc and try to identify the missing topic. If all else fails, delete the reference from toc.ditamap and move on. Your readers already knew about the safety hazards of handling lithium deuteride, anyway.
    • If a topic contains a xref with a crazy relative path, this can really confuse DITA-OT. The good news is that the toolkit indicates the path that is causing the problem. The bad news is that AuthorIT dumps its DITA output in UTF-16, which is really annoying to grep through.
    • If you had any “Note” paragraph styles in your AuthorIT doc, these might disappear. Even more strangely, “Warning” paragraphs do make it through.
  4. Clean up the DocBook output with a script.

    Congratulations, your document is now DocBook! Well, more accurately, it’s “DocBook”. Just be happy your tables made it through, sort of.

    Fortunately, you can fix many issues pretty easily by running the document through a cleanup script. This script is particularly important if you’re converting multiple documents. The canonical language for the script is XSLT, but if you’d rather stick it to the W3C Man, Python or Perl would work fine too. Here’s what you’ll want to fix:

    • Remove all id attributes. These generated IDs are duplicated throughout the doc, and nothing points to them. Throw them away and start over.
    • Remove all remap attributes. In theory, these attributes contain useful information about the original DITA element, which in turn could help you design your post-processing script to provide better-quality DocBook markup. In practice… eh, not so much.
    • Remove all sectioninfo elements. They’re often invalid, and always contain nothing useful.
    • Remove empty type attributes. Not sure how those got there.
    • Remove empty para elements.
    • Change sidebar elements to section elements. Like the empty type attributes, these are another mystery guest.
    • Join programlisting elements. If you had any multi-line code samples, you might find that in the transformed DocBook, each line appears in its own programlisting. Join adjacent programlisting elements into a single programlisting (or screen, if appropriate).
    • (Optional) Change the article to a book, if appropriate. Add chapter elements as necessary.
    • (Optional) Try to improve the quality of the markup by changing emphasis role="bold" and literal elements to something more specific. For example, you define a list of commands that appear in your book and wrap each one in a command element. Creating explicit lists of commands, GUI buttons, and so on is tedious, but it’s still better to do these substitutions in the script.

    Finally, there’s the issue of broken IDs and links. Currently, every one of your AuthorIT hyperlinks is now a ulink that falls into one of these categories:

    • The ulink‘s url starts with “mailto:“. Convert these to email elements.
    • The ulink‘s url starts with “http://“, or “ftp://“, or “gopher://“. Leave these alone.
    • The ulink‘s url points to something like “D1228.xml“, a.k.a. nowhere. These are your former internal hyperlinks. They’re all broken.

    But don’t be discouraged, your script can actually “guess” at where many of these links should point. If a given internal ulink contains something like, “Configuring the MIRV Launch Sequence”, there’s an excellent chance that somewhere else in your document there’s a section with a title, “Configuring the MIRV Launch Sequence”! So all you have to do is:

    1. Convert the content of each ulink to a nicely-formatted ID. Replace whitespace with underscores, remove extraneous punctuation, and lower-casing everything.
    2. Convert the ulink to an xref, setting the linkend to the new ID.
    3. For each section element, apply the same ID-conversion algorithm to the section‘s title. Set this value as the section‘s id.

    A healthy fraction of your ids and linkends should now match up, fixing those broken links.

  5. Clean up the DocBook output manually.

    Oh, you’re not done yet! Here’s a non-exhaustive list of what’s left:

    • Fix the remaining invalid ids and broken links that your script didn’t catch.
    • Fix any other DocBook validity issues.
    • Add programlisting and screen elements where appropriate. Remove excess carriage returns as necessary.
    • Make your inline markup consistent. For example, all command-line tools should be consistently marked up as commands (assuming your organization chooses to use that element). You can partly script this, but mostly this is a manual job.
    • Remove any mysterious duplicate sections.
    • Rename your images from “898.png” to something more descriptive, such as “mirv_reentry_trajectory.png“. Embed the images in a figure with a proper title and id.
    • Add any missing front matter.
    • Rebuild your index by hand. By hand. Jesus H. Christ.

    Now put your feet up on the desk and pour yourself a well-deserved gin-and-tonic. If anyone asks you why you look so frazzled, do not under any circumstances tell the truth. Otherwise they’ll just respond with, “Well, why don’t you just move it all to the corporate wiki?” And there’s only one rational reaction to that. Don’t get me wrong, it’s not easy to inflict serious blunt force trauma using a 15″ Powerbook, but somehow, you’ll find a way.

You Heard It Here First: Ticketmaster Sucks

So yesterday evening SJSU held a reading and book signing for the incomparably awesome Neil Gaiman. I went to the SJSU website, and discovered the tickets were being sold through Ticketmaster.


$15.00 to buy the ticket and hold it at will-call. $5.00 for the Ticketmaster service charge. Then, after you’ve entered your name and email address, another $4.80 “processing fee”. Screw that.[1],[2]

If SJSU can’t figure out how to sell $15.00 tickets without charging another 66% in fees, I guess it’s not really my concern. But perhaps they should take note: this could help explain why there were still tickets available on Thursday afternoon. Or maybe Neil Gaiman just isn’t very popular with the kids these days?

1. The contrast between the fees of Ticketmaster and the fees of other online companies that actually ship physical products are especially striking. Monopolies are awesome.

2. Although I do like the time-pressure aspect. They’re holding the ticket for 2:00 minutes! The clock is ticking… can our hero create a new user account in time? Cut the red wire — no, the blue!

The Spider in the Rearview Mirror

I have a spider in my rearview mirror.

This not a metaphorical spider in a symbolic mirror; I’m talking about a garden-variety California orb-weaver. I’ve only seen it once, but it lives in the gap between the rearview mirror’s glass and housing. Every night it comes out, spins a little web between the mirror and the window, and retreats back to its lair. Every morning I destroy the web.

Occasionally, I try to root out the spider with a twig, but I can’t seem to get at it. I could probably flush it out with a blast of water from the hose. But I haven’t bothered yet, because what really fascinates me about the spider is its tenacity, its single-mindedness. It doesn’t get discouraged. It doesn’t move its home to a more promising location. It seems to have no ability to process this particular input and react accordingly. The spider and I, we have a failure to communicate.

Fundamentally, I think this is why arachnids and insects are so creepy. Sam raised this idea a while back. If you’re hiking and you step near a snake, it will rear up and hiss at you to warn you off. You scared it, it’s trying to scare you. Message sent, message received. Reptiles, mammals, birds… there’s something comforting about how you can communicate with these creatures, at least at some very basic level. The Brotherhood of the Vertebrates.

But arthropods are alien creatures. Little unfathomable machines. Is it going to bite me? Scuttle away? Ignore me? What is the spider thinking when it fastens those eight beady little eyes on me?

Unhappy Predictions

The flu and some random colds are sweeping through the office. It’s like the plague hit. It’s so bad that on Friday, even I felt like I was getting the sniffles. Fortunately nothing came of it. I think this is how my ancestors managed to survive into the modern era. We weren’t even close to being the biggest or toughest or meanest SOBs around, but we did have a kick-ass immune system. Also we could sprint surprisingly fast when hard-pressed.

Of course, it goes without saying that whenever I start bragging about not getting sick, I get sick. As long as I keep my mouth shut, I can be fine for years. But this blog post has pretty much guaranteed that in short order, I’ll be deathly ill for at least a week.

For another dose of pre-Holiday cheer, I’m going to come right out and predict that the Republicans are going to maintain control of both the Senate and the House. I also predict much jawing by the pundits Wednesday about “the incredible last-minute Republican surge!” Somehow the polls were 3-4 sigma out again! Amazing!

Although the prospect of the Republicans winning again is awful enough, the thing that is orders of magnitude more horrifying is what that victory would prove, once and for all, about our electoral system. I really, really hope I’m wrong about this.

Update: Well, I must say, it has never felt so good to be so colossally wrong. I’m just glad I didn’t have a few hundred extra bucks burning a hole in my pocket, or I would have lost it all betting at