Josh Saddler

Another day, another release. Another handbook written.

I'm so happy I finished writing those things. Once 2008.0 final is released, the only change I know I'll have to make at this point is changing the release name from 2008.0_beta1 to 2008.0, and as others have mentioned, that change is easy to make. Keys in the TOC allow me to make conditional evaluations in each handbook. So in the XML source, if I write:

<p>
Stage3 tarballs can be downloaded from <keyval id="release-dir"/>
</p>

This will replace release-dir with the location of the release, as fetched from the corresponding key. So depending on the handbook you're reading, you'll see something like:

Stage3 tarballs can be downloaded from releases/amd64/2008.0_beta1/stages/

Simple, but oh-so-maintainable. I don't just use keys in the handbook TOC, but I also can add conditional evaluations that pull in paragraphs, sections, subsections, code blocks, you name it. These can also be from external files, too. That's one of the things I've been doing for this release -- finding duplicate content for all arches, and moving that text into a separate external file.

One example is the text that explains block devices. Each arch used to have similar text, sometimes slightly (or significantly!) different. I unified all arches -- put them on the same page, so to speak -- by creating an external include. I first pitched the includes proposal back in March 2007, and it's finally coming to fruition with the 2008.0 release.

By using the following tidbit:

<section>
<title>Introduction to Block Devices</title>

<subsection>
<include href="../hb-install-blockdevices.xml"/>
</subsection>

<subsection>
<title>Partitions</title>

I can drop the contents of hb-install-blockdevices.xml into place, providing the same descriptive text. If it ever needs changing, rather than having to change 16 handbooks, I can change just one, and all 16 will use it. This example is taken from a file in /handbook/2008.0/, so it refers to the included file one level up, in /handbook/. The included content doesn't even have to be in the same directory as the file using it!

I'll be implementing even more of these kinds of changes in the future. They increase maintainability, increase uniformity, and, more importantly, preserve my sanity when editing handbooks. And if I stay sane, I don't retire.