Chapter 3. Building and Debugging

You can use Atlas to build your book in three formats—PDF, EPUB, KF8, and HTML—whenever you like.

Building Books

To kick off a build, click on the Build tab. Then, select New Build, and you will be presented with a list of the files that you’ve created so far. Drag or click the files that you’d like to include in the build and select the ebook formats that you’d like generate, as shown in Figure 3-1.

A few things to keep in mind when building books in Atlas:

• Atlas expects a file extension of .asciidoc, so please use that instead of .asc.
• When you trigger a build, Atlas automatically creates a book.asciidoc file that references the files that you choose to include in the build, so there is no need to add one.
• Do not include book-docinfo.xml file in the build. This metadata-only file is described in “Adding Metadata”.

The builds will change to a status of pending. Wait a few minutes, and then refresh the page. Assuming the builds were successful, you can download your files right from Atlas. If you run into an error, see “Debugging Errors”.

Build times vary based on the length of your book, but most builds finish within a few minutes. EPUB files build the fastest, PDF files the slowest, and KF8 files somewhere in between.

If the title and copyright pages in your book builds are looking bare, you can optionally fill them in by adding a file called book-docinfo.xml to your project via git (see Chapter 5), and then adding the appropriate metadata using XML tags. Here is an example showing the metadata that you might like to include:

<title>BOOK TITLE</title>

<author> <!-- feel free to add multiple authors-->
<firstname></firstname>
<surname></surname>
</author>

<editor>
<firstname></firstname>
<surname></surname>
</editor>

<copyright>
<year>2012</year>
<holder></holder>
</copyright>

<othercredit role="proofreader">
<firstname></firstname>
<surname></surname>
</othercredit>

<!-- All rights reserved. -->

<publisher>
<publishername>O’Reilly Media, Inc.</publishername>
<address format="linespecific">
<street>1005 Gravenstein Highway North</street>
<city>Sebastopol</city>
<state>CA</state>
<postcode>95472</postcode>
</address>
</publisher>

<isbn></isbn>

<edition></edition>

<revhistory>
<revision>
<date>2012-02-10</date>
<revremark>First release</revremark>
</revision>
<revision>
<date>2012-02-27</date>
<revremark>Second release</revremark>
</revision>
<revision>
<date>2012-04-27</date>
<revremark>Third release</revremark>
</revision>
</revhistory>

When you create a new build, the metadata will be added to the title and copyright pages of your PDF. Note that you do not need to include the book-docinfo.xml file iself in the build. Atlas sees and picks up the metadata information automatically.

Debugging Errors

Book builds will sometimes fail. The most likely cause of a failure is that your AsciiDoc isn’t structured in a syntactically valid way. When you trigger a build, Atlas transforms your AsciiDoc into DocBook XML 4.5 and, using the DocBook as a source, builds the book files. If one of your builds fails, Atlas will report the error, which should help you to fix it.

For example, here is an Atlas error log for a PDF build that failed:

book.xml:291: element xref: validity error : IDREF attribute
linkend references an unknown ID "cloning_to_github"

In this case, the problem is that there is a cross-reference referring to an ID that does not exist. You can fix it by adding an ID to the appropriate block, as explained in Chapter 4.

We realize that build failures can be tricky to troubleshoot, so we’re working on improving the error messaging. Also, we’ve configured Atlas to be permissive enough so that it doesn’t fail on minor errors. Please let us know about your experiences with troubleshooting build failures, and how Atlas can be improved to make the experience better.