Writing an O'Reilly Book Using Scrivener

I wrote the 1st edition of PGAE using Scrivener, the long-form prose drafting application by Literature & Latte. O'Reilly Media uses DocBook, the semantic XML-based format for technical books, so I set up a technique and tool for composing DocBook XML in Scrivener. This allowed me to draft in Scrivener and export interim versions to O'Reilly for Rough Cuts.

Starting the 2nd edition of the book compelled me to revisit the tool and extend it with the ability to import DocBook back into Scrivener, so I could preserve changes that have been made to O'Reilly's copy of the text since the 1st edition final draft. I also took the opportunity to clean the tool up a bit and release it publicly, in case anyone else wants to try this.

Scriv2DocBook is a simple workflow for writing technical books in Scrivener. The end result is DocBook XML suitable for delivery to a publisher, or rendering into other formats using DocBook tools. It includes a method for drafting a technical book in Scrivener, a process and tool for exporting a Scrivener project to DocBook XML, and a process and tool for importing DocBook XML back into Scrivener.

As with most home-grown writing tools by book authors, this workflow is personal to my tastes, and may not meet your needs or desires. The workflow involves writing DocBook XML markup directly into the Scrivener project text. Section and paragraph tags are handled automatically during export. For all other tags, you type them directly in your document. Scriv2DocBook does not make Scrivener into a WYSIWYG DocBook editor—though, to my taste, the automatic paragraph feature goes a long way to making the text easier to read and type while drafting.

But let's be clear: Scrivener is not an XML editor. You will encounter XML syntax and validation errors if you do this, you will not catch these errors until you export, and tracing the errors back to their locations in Scrivener will be tedious. In fact, my general recommendation is to not use Scriv2DocBook, and instead prefer a validate-as-you-type XML editor such as Oxygen, or Emacs with nxml mode. Only use Scriv2DocBook if you, like me, are overwhelmed by Scrivener's substantial charms, and are willing and patient enough to put up with the inherent drawbacks of using a non-XML editor to write XML markup.

Here's what Scrivener looks like with PGAE in it:

Scriv2DocBook also includes a tool for converting a subset of DocBook XML back into a Scrivener project. I wrote this specifically for importing the output of the original export, and the steps are cumbersome enough that this is probably not good for regular "round trip" conversions. I'm certain it won't work on all DocBook documents, though you're welcome to try. (A more general-purpose importer is technically feasible, I just don't have the time or the personal need.)

This workflow takes advantage of Scrivener's OPML export and import features, using OPML as the intermediate format for the conversion. Note that Scrivener 2.1 has an OPML import bug that interferes with Scriv2DocBook; I'm told this will be fixed in Scrivener 2.1.1, due out later this month. This bug does not affect exports. Currently, the OPML export and import are manual procedures, which I've written up in the Scriv2DocBook documentation. Perhaps there's an easier way to automate this, or will be in the future.

If that all sounds good to you, and you have a need for this kind of thing, give Scriv2DocBook a try, and let me know what you think. Suggestions and patches welcome, though I can't promise I'll have time to make regular updates—at least not until PGAE, 2nd ed. is done. :)