Why XML for writing?

Around 2000, I started keeping my writing in XML. What began as a way to manage an online refactoring catalog quickly became my preferred method for all long-form work, including my book Patterns of Enterprise Application Architecture. The core idea is simple: keep content in a logical, text-based markup and let stylesheets handle presentation for different outputs.

My early experiments were crude by today's standards. The refactoring catalog was originally authored in Framemaker and saved to XML using the tool's vocabulary. A small XSLT transform mapped those tags to ones I actually wanted on the website, and a second stylesheet rendered everything as HTML. Because the source files were plain text with known structure, I could also write a Java program to scan the directory and regenerate an index page automatically. The whole site rebuilt from a single Ant script.

That experience led me to try XML for articles, and eventually for a full book. Framemaker had served me well but its closed file formats made scripting and web conversion difficult. XML removed those blockers: any text editor works, build tools apply straightforwardly, and XSLT produces clean HTML without the formatting noise that comes with direct HTML authoring.

Tools for typing

The question people ask first is what I type into. The answer is a text editor — not a specialized XML tool. XML's plain-text nature means collaborators need no expensive software to contribute sections, which made co-authoring with David Rice across hemispheres far easier than it would otherwise have been.

During the book I used TextPad for most of the writing. Its clips library made tagging text quick, and its lightweight feel worked for me. More recently I have moved to XEmacs for editing, especially the Windows ports of version 21.4, where I also rely on the SGML major mode. I tried XML Spy but found it too data-oriented and less suited to comfortably reading and producing substantial prose.

Two output paths

XML to HTML via XSLT is my favorite part of this approach. That said, XSLT is not a pleasure to write. Its functional nature means loops become recursion, and its complexity invites errors. A few practices help:

  • Treat it as pattern matching. Prefer xsl:template match="foo" over xsl:for-each whenever reasonable.
  • Assume you will need a reference. Michael Kay's XSLT Programmer's Reference is dense but works well for answers to detailed questions.
  • Wrap everything in a build script. An Ant script that runs the transform makes regeneration — which you will do often while iterating on structure — painless.

The separation between content and formatting is precisely what I wanted, and it keeps my pages free of chunky HTML markup, but the same advantage extends beyond the browser.

Print output is harder. For an early attempt I used XSL-FO with Apache's FOP. The standard clearly covers what you need, but in early 2002 the implementation could not handle a book of that size, and my publisher was not ready for the FO workflow either. I consider that a temporary limitation — by the time my next book needs typesetting, I plan to revisit XSL-FO.

Instead, I wrote a two-stage conversion back to Framemaker. First, an XSLT transform rewrote my book's XML into a Framemaker-like XML vocabulary. Second, a Ruby script converted that intermediate representation into Framemaker's textual MIF format. That split used each tool well: XSLT for heavy tag juggling, Ruby for precise text formatting needs.

Since then, two other paths have appeared that I intend to explore. Open Office stores documents as zipped XML with separate content and formatting layers, so an XSLT transform can inject book content and the formatting can be applied afterward. Microsoft Word is likely to support similar flows in its next release.

Handling diagrams and code

I draw most diagrams in Visio — not the standard UML templates, which try to be intelligent about UML but end up merely being awkward for anyone who already understands it. Pavel Hruby's custom templates avoid that issue. Visio's gif output has annoying clipping artifacts at the top of rendered figures; better SVG browser support will eventually help here.

A build-level detail worth copying: a script exports every Visio file to gif only when the source is newer than the output image. Ruby drives Visio's object model without trouble, and this script keeps diagrams in sync with the markup.

Automatic code import was a revelation. All sample code for the book lives in directories that Ant can compile and run tests against. Comment markers in the source delimit the fragments intended for the text. A simple Java program scans the tree and generates XML fragments from those sections, which then feed into the XSLT pipeline during the build. Because code shown in the book is the actual code on disk — compiled and tested — the usual copy-paste drift never appears.

Versioning every edit

Collaboration and safety both point to version control, even for prose. CVS worked well for two authors working across continents. Any edit went to the repository, which gave me a full history and let me experiment freely while never losing a prior state. We versioned everything — the book text, the sample Java libraries, and the .NET assemblies that the environment depended on.

Authors should treat version control as core infrastructure just as much as programmers do. XML's plain-text basis is what makes that possible in the first place.

Why XML Earned Its Place in My Workflow

After using XML to write a full-length book, I've adopted it for nearly all my writing, including the article you're reading now. The single exception is my column for IEEE Software, which requires Word files—but those pieces are short enough that the usual XML benefits don't matter much there.

The experience convinced me that XML is a legitimate, even preferable, way to produce long documents. What makes it work is the clear separation of structure from formatting: content lives in plain, semantically tagged text, and presentation is handled separately by XSLT or other tools. That removes the usual friction of fighting a word processor's formatting engine as a document grows.

Who Should Try It Now

XML-based writing is a strong fit if you're comfortable in a technical environment—someone happy to work with XSLT, scripts, and a build process. Under those conditions, I warmly recommend it for web sites, reports, or books. If you're less inclined toward that kind of tooling, the current state of XML authoring tools probably isn't ready for you yet. That's not a reason to ignore the space, though.

Keep an eye on XML-aware word processors. If the next version of Microsoft Word lives up to the rumors, XML writing will become far more approachable for a mainstream audience. The pieces are in place; what's missing is the right tool to make it transparent.