Getting Started

Big Changes to O’Reilly’s Authoring Tools

If you worked with us on a book prior to fall 2012, you probably committed your files to a Subversion repository and used a special commit string to trigger PDF builds. You probably even accessed these very guidelines via an SVN repo. Well, our developers have been at work creating a new authoring platform called Atlas that is now available to you as a replacement for SVN. Atlas is a git-managed, wiki-like authoring platform for creating books, and we’re excited about it. See the Atlas guidelines for more info.

Although Atlas was originally designed for working with AsciiDoc files—because AsciiDoc is a lightweight language and can be easily written in a web interface—it can support DocBook files as well. There are several advantages to using Atlas with DocBook:

  • Manage your files in git.

  • Build PDFs that use the new CSS-based stylesheets.[1]

  • More tolerant PDF builds.[2]

These guidelines are still very much relevant—you’ll still need to use an XML editor, make correct markup decisions, and deliver valid files to Production.

How Atlas works

  1. Receive an invite from an O’Reilly editor, Tools staff member, or another author, and create an account.

  2. Write in DocBook as described in these guidelines.

  3. Commit and push your files to your Atlas git repo.

  4. When you’re ready, build your book. Atlas interfaces with O’Reilly’s publishing toolchain and can generate PDF, EPUB, and Mobi files for you on the fly. These files look just like those for sale on oreilly.com.

Please see the Atlas guidelines for more on the following:

The Atlas guidelines often refer to .asciidoc files, but you can do pretty much all the same steps using .xml files. One difference to note is that when working with XML, if you go to the Build tab, you will see the message, “This book has a book.xml file, so the index creator is disabled.” That’s nothing to worry about—just select the formats you wish to generate and click the “Build!” button.

If you have already started working in a Subversion repository and you’d like to switch to Atlas, just send a request to and we’ll move your files over. We can also convert your DocBook files to AsciiDoc if you’d like to switch formats.

Why DocBook?

DocBook is an OASIS standard for XML that is ideal for writing long, technical documents that have complex structure and cross-references. With its semantic tagging, DocBook can be rendered as PDF for printing, HTML, man pages, audio, or even Braille. This versatility and reusability make DocBook 4.5 XML the preferred format for O’Reilly books.

Not only does this document explain how to start writing in DocBook, but it was created using the same markup and toolchain used for a typical O’Reilly book, so you can treat it as a model for your own manuscript. Chapter 2 contains information about markup.

We’ve got nothing against LaTeX, troff, or any other formatting markup system. But typesetting markup like LaTeX is inherently focused on formatting—font size, margins, alignment, etc. We’d rather you spend your time focused on the semantic structure of your book (how sections are divided, which information goes in a sidebar versus a note, and so on), and that’s where DocBook shines. In the same way most well-designed websites separate content from formatting using XHTML and CSS (XHTML for the content, and CSS for the formatting), DocBook lets us abstract formatting decisions away from content decisions.

Particularly as O’Reilly expands its efforts to provide content in multiple formats and at multiple stages of the content’s life cycle, cost-effectively generating multiple, distinct output formats from the same source document becomes critical, even though it means losing some degree of granular control over the output.

What does that mean for your book? It means that you’ll be able to view drafts of your book throughout the authoring process that are formatted much as they will be for print, and it means once your book is finished, it will go live almost immediately on Safari Books Online and other digital and ebook retail channels, rather than needing to first be converted into DocBook from another format, which can take a week or longer.

Will What I See in the XML Editor Mirror the PDF Builds?

DocBook markup specifies the structure and semantics of your document, but not the appearance. DocBook isn’t a WYSIWYG format, so it will display differently in your XML editor than it will after rendering to PDF and other formats downstream. This means not only will fonts and formatting display differently, but line breaks may differ as well.

The O’Reilly toolchains that transform your DocBook into its final form (both print and downstream electronic formats) rely on semantic XML tags that you apply to the elements of your text. Those tags are then processed in combination with customized CSS stylesheets and a commercial processor to render your content.

For More on DocBook

This guide is tailored to help authors get the most out of O’Reilly’s DocBook authoring toolchain. For more general information on DocBook XML, see Norm Walsh’s excellent DocBook: The Definitive Guide. You’ll find reference pages for each DocBook element, including a content model, a description of purpose, a list of parents that can contain it and children that can be nested in it, and allowed attributes. Other resources that may be helpful include:



[1] The Nutshell and Pocket Reference series are not compatible with Atlas at this time.

[2] If you’ve ever had to decipher an error log generated when an SVN commit-hook build fails, you’ll be happy about this one. One potential downside of this is there’s less protection against invalid markup. See “Validating Your XML” for more on this.