bookshop 0.0.3 → 0.0.4

data/lib/bookshop/generators/bookshop/app/templates/book/ch02.xml

@@ -0,0 +1,707 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="setting_up_your_xml_files">
+  <title>Setting Up Your XML Files</title>
+
+  <para>This chapter covers the basics of getting you set up to write in
+  DocBook using O’Reilly’s toolchain. It covers how to use O’Reilly’s
+  Subversion (SVN) repository to maintain your book files, how to organize
+  your XML files, and how to validate your XML files.</para>
+
+  <sect1 id="docbook_and_subversion">
+    <title>DocBook and Subversion</title>
+
+    <para>One of the benefits of working in DocBook is that you can take
+    advantage of O’Reilly’s Subversion repositories to maintain your files.
+    Subversion is an open source version control system that keeps track of
+    the changes you make to your book. Throughout the writing process, you can
+    “commit” revised versions of the book files to the repository with a log
+    message, which will be associated with a revision number. Among other
+    features, Subversion allows you to revert back to any revision of your
+    book, as well as run a diff to compare two different versions of a
+    file.</para>
+
+    <para>Subversion also supports multiple working copies of the same
+    project, which means you can have multiple authors collaborating and
+    making changes to the same set of files simultaneously, and Subversion
+    provides the functionality to merge, diff, or revert the revisions you
+    make when you commit the files to the repository.</para>
+
+    <sidebar id="gui_svn_clients">
+      <title>I Don’t Like SVN—Can I Use Something Else?</title>
+
+      <para>While we realize that some of the software development world now
+      favors distributed version control systems like Git and Mercurial, in
+      order to make the most of our <phrase
+      role="keep-together">DocBook</phrase> tools, you need to use SVN. You
+      can, however, choose your preferred SVN <phrase
+      role="keep-together">client—</phrase>whether command-line or GUI. Here
+      are some available GUI clients:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><ulink url="http://tortoisesvn.tigris.org/">TortoiseSVN
+          (Windows)</ulink></para>
+        </listitem>
+
+        <listitem>
+          <para><ulink
+          url="http://www.lachoseinteractive.net/en/community/subversion/svnx/features/">svnX
+          (Mac)</ulink></para>
+        </listitem>
+
+        <listitem>
+          <para><ulink url="http://scplugin.tigris.org/">SCPlugin
+          (Mac)</ulink></para>
+        </listitem>
+
+        <listitem>
+          <para><ulink url="http://versionsapp.com/">Versions
+          (Mac)</ulink></para>
+        </listitem>
+
+        <listitem>
+          <para><ulink url="http://rapidsvn.tigris.org/">RapidSVN
+          (multiplatform)</ulink></para>
+        </listitem>
+
+        <listitem>
+          <para><ulink url="http://subcommander.tigris.org/">Subcommander
+          (multiplatform)</ulink></para>
+        </listitem>
+      </itemizedlist>
+
+      <para>A more comprehensive list can be found <ulink
+      url="http://en.wikipedia.org/wiki/Comparison_of_Subversion_clients">here</ulink>.</para>
+
+      <para>O’Reilly’s documentation generally refers to the command-line SVN
+      client, but the concepts—and much of the vocabulary—are the same in
+      GUIs. For example, running <literal>svn update</literal> on the command
+      line is analogous to right-clicking in an <phrase
+      role="keep-together">SCPlugin</phrase> project directory and selecting
+      <filename>More</filename><phrase
+      role="unicode">→</phrase><filename>Subversion Update</filename>.</para>
+    </sidebar>
+
+    <sect2 id="using_an_oreilly_svn_repo">
+      <title>Using an O’Reilly Subversion Repository</title>
+
+      <para>Once you have spoken with your editor and decided that you will
+      write in DocBook, email the O’Reilly Tools team at
+      <email>toolsreq@oreilly.com</email>; we will create a Subversion
+      repository for you on an O’Reilly server that contains <filename
+      moreinfo="none">book.xml</filename> and other files to use as a template
+      for getting started. We will also set you up with a username and
+      password. There are several benefits to using an O’Reilly SVN
+      repository:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>It is easier to exchange files with your editor and coauthors
+          for review.</para>
+        </listitem>
+
+        <listitem>
+          <para>It is easier for the O’Reilly Tools team to help you with any
+          DocBook questions you may have along the way.</para>
+        </listitem>
+
+        <listitem>
+          <para>You can create PDF builds of your book every time you commit
+          changes.</para>
+        </listitem>
+
+        <listitem>
+          <para>The files are stored in a safe and secure location that is
+          backed up regularly.</para>
+        </listitem>
+
+        <listitem>
+          <para>You have the ability to view and merge changes from earlier
+          versions of your book.</para>
+        </listitem>
+      </itemizedlist>
+
+      <note>
+        <para>The author/manuscript repository URL for a standard O’Reilly
+        book follows this structure:
+        <emphasis>https://prod.oreilly.com/external/authors/books/<replaceable>ISBN13</replaceable>/current/</emphasis>.</para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Subversion Primer</title>
+
+      <para>For in-depth information on the Subversion workflow and a command
+      reference, see O’Reilly’s <ulink
+      url="http://svnbook.red-bean.com/nightly/en/svn-book.html?"><citetitle>Version
+      Control with Subversion</citetitle></ulink> (free to read
+      online).</para>
+
+      <para>First, set up a directory on your local machine to serve as your
+      local workspace for the project. You can name it anything you want. For
+      example: <filename>~/projects/my_book</filename>. Your working copy (or
+      checkout) is your own private work area: Subversion will never
+      incorporate other people’s changes, nor make your own changes available
+      to others, until you explicitly tell it to do so.</para>
+
+      <para>The following steps outline a typical SVN workflow. Again, the
+      examples refer to the command line, but you can run equivalent commands
+      using any of the GUI clients.</para>
+
+      <sect3>
+        <title>Checkout (<ulink role="orm:hideurl"
+        url="http://svnbook.red-bean.com/en/1.0/re04.html">svn
+        co</ulink>)</title>
+
+        <para>Check out the files from the repository as follows (substituting
+        the <replaceable>ISBN13</replaceable> and your workspace
+        filepath):</para>
+
+        <programlisting>$ <userinput>svn co https://prod.oreilly.com/external/authors/books/<replaceable>ISBN13</replaceable>/current 
+<replaceable>~/projects/my_book</replaceable></userinput></programlisting>
+
+        <para>You need to run this command only once, when you first start a
+        project. It will copy the <filename>book.xml</filename> and template
+        files from the repo into your checkout. See <xref
+        linkend="organizing_files" /> for more information about the files you
+        receive when you make your initial checkout.</para>
+      </sect3>
+
+      <sect3>
+        <title>Commit (<ulink role="orm:hideurl"
+        url="http://svnbook.red-bean.com/en/1.0/re06.html">svn commit -m'log
+        message'</ulink>)</title>
+
+        <para>After you do some amount of work that you want to preserve or
+        share with <phrase role="keep-together">others—</phrase>say, you
+        finish a chapter—commit those changes along with a short, descriptive
+        log message. For example:</para>
+
+        <programlisting>$ <userinput>svn commit -m'<replaceable>finished draft of Chapter 1</replaceable>' ch01.xml</userinput></programlisting>
+
+        <para>You don’t have to include the filename
+        (<filename>ch01.xml</filename> here). If you leave it off, running
+        <literal>svn commit</literal> will commit <emphasis>all</emphasis> the
+        local modifications in your checkout—so make sure you really want to
+        publish those changes. (If you make a mistake, previous versions can
+        of course be recovered.) To find out which local files have
+        modifications compared to the repo, run <literal>svn status
+        -u</literal>. Here’s an example of the output:</para>
+
+        <programlisting>$ <userinput>svn status -u</userinput>
+M          245835   ch01.xml
+     *     232767   ch04.xml
+?                   images</programlisting>
+
+        <para>The “M” means <filename>ch01.xml</filename> has local
+        modifications; the “*” means a newer revision of
+        <filename>ch04.xml</filename> exists on the server; and the “?” means
+        <filename>images</filename> is not under version control. These are
+        just a few of the possible indicators; <ulink
+        url="http://svnbook.red-bean.com/en/1.0/re26.html">http://svnbook.red-bean.com/en/1.0/re26.html</ulink>
+        has a complete list.</para>
+
+        <note>
+          <para>You can decide how frequently you want to commit. The more
+          often you do, the easier it is to roll back to or recover specific
+          previous <phrase role="keep-together">versions</phrase>.</para>
+        </note>
+      </sect3>
+
+      <sect3>
+        <title>Update (<ulink role="orm:hideurl"
+        url="http://svnbook.red-bean.com/en/1.0/re28.html">svn
+        up</ulink>)</title>
+
+        <para>Running <literal>svn up</literal> (aka <literal>svn
+        update</literal>) brings changes from the repository into your working
+        copy. You may first want to run <literal>svn status -u</literal> to
+        see what kinds of changes will be incorporated (rather than blindly
+        merging in changes), and then run <literal>svn up</literal> before
+        starting to work on the files. This will ensure that your copies of
+        the files reflect the most recent version in the repo.</para>
+
+        <para>It’s also good practice to run <literal>svn up</literal> again
+        before you commit. This should prevent any conflicts that could occur
+        if other files have been added to the repo since you last
+        updated.</para>
+
+        <para><xref linkend="svn_workflow_setup" /> and <xref
+        linkend="svn_workflow_ongoing" /> provide a visual overview of the
+        workflow just described (where “me” is you, the author).</para>
+
+        <figure float="none" id="svn_workflow_setup">
+          <title>Setting up your workspace for a new project: checkout</title>
+
+          <mediaobject>
+            <imageobject role="web">
+              <imagedata fileref="figs/svn_workflow_setup.png" format="PNG"
+                         width="4.8in" />
+            </imageobject>
+          </mediaobject>
+        </figure>
+
+        <figure id="svn_workflow_ongoing">
+          <title>Ongoing SVN workflow: update and commit</title>
+
+          <mediaobject>
+            <imageobject role="web">
+              <imagedata fileref="figs/svn_workflow_ongoing.png" format="PNG"
+                         width="4.8in" />
+            </imageobject>
+          </mediaobject>
+        </figure>
+      </sect3>
+
+      <sect3>
+        <title>Add/delete/move/copy (<ulink role="orm:hideurl"
+        url="http://svnbook.red-bean.com/en/1.0/re01.html">svn
+        add</ulink>/<ulink role="orm:hideurl"
+        url="http://svnbook.red-bean.com/en/1.0/re08.html">svn
+        rm</ulink>/<ulink role="orm:hideurl"
+        url="http://svnbook.red-bean.com/en/1.0/re18.html">svn
+        mv</ulink>/<ulink role="orm:hideurl"
+        url="http://svnbook.red-bean.com/en/1.1/re07.html">svn
+        cp</ulink>)</title>
+
+        <para>These commands are useful for organizing files and directories
+        in the repo. If you run them locally, they take effect only after you
+        commit. For example:</para>
+
+        <programlisting>$ <userinput>svn add ch01.xml ch02.xml</userinput>
+A         ch01.xml
+A         ch02.xml</programlisting>
+
+        <para>The “A” output on the left indicates that the files have been
+        scheduled for addition. If you’ve deleted files, you’ll see a “D”
+        there; if you’ve modified files, you’ll see an “M”. (These letters are
+        the same ones shown when you run <literal>svn status
+        -u</literal>.)</para>
+
+        <note>
+          <para>If you decide, for example, that you don’t want to add
+          <filename>ch01.xml</filename> after all, don’t commit—run
+          <userinput>svn revert ch01.xml</userinput> to discard the scheduled
+          <phrase role="keep-together">addition</phrase>.</para>
+        </note>
+
+        <?dbfo-need height=”1in”
+?>
+
+        <para>Here’s an example of what happens when you commit after adding
+        files:</para>
+
+        <programlisting>$ <userinput>svn commit -m'Adding Chapters 1 and 2 to the repo'</userinput>
+Adding         ch01.xml
+Adding         ch02.xml
+Committed revision 245451.</programlisting>
+
+        <para>where “245451” is the revision number. You can find out the
+        current revision number at any time using <literal>svn
+        info</literal>.</para>
+
+        <para>Many SVN commands can be run server-side if you include
+        repository URLs. Doing so results in an immediate commit (rather than
+        scheduling an action for a later commit) and requires a commit
+        message. Here’s an example of using a server-side <literal>svn
+        mv</literal> to rename a chapter file:</para>
+
+        <programlisting>$ <userinput>svn mv -m'Renaming chapter2.xml to chapter3.xml' </userinput>
+<userinput>https://prod.oreilly.com/external/authors/books/ISBN13/current/chapter2.xml </userinput>
+<userinput>https://prod.oreilly.com/external/authors/books/ISBN13/current/chapter3.xml</userinput>
+Committed revision 245458.</programlisting>
+
+        <para>Then <literal>svn up</literal> to see the change in your working
+        copy. This command is equivalent to an <literal>svn cp</literal>
+        followed by an <literal>svn rm</literal>.</para>
+
+        <note>
+          <para>If you try to <literal>svn rm</literal>, <literal>svn
+          mv</literal>, or <literal>svn cp</literal> a file that exists in
+          your checkout but was never added to the repo, you’ll get an error
+          message like “svn: 'file' is not under version control”.</para>
+        </note>
+      </sect3>
+
+      <sect3>
+        <title>Other useful commands</title>
+
+        <variablelist>
+          <varlistentry>
+            <term><literal><ulink
+            url="http://svnbook.red-bean.com/en/1.1/re13.html">svn
+            info</ulink></literal></term>
+
+            <listitem>
+              <para>Print information about your working copy, including the
+              repo URL.</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal><ulink
+            url="http://svnbook.red-bean.com/en/1.0/re15.html">svn
+            log</ulink></literal></term>
+
+            <listitem>
+              <para>See all commit log messages. Use with <literal>--limit
+              </literal><replaceable>#</replaceable> to limit the number of
+              results.</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal><ulink
+            url="http://svnbook.red-bean.com/en/1.0/re09.html">svn
+            diff</ulink></literal></term>
+
+            <listitem>
+              <para>View changes in a file.</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal><ulink
+            url="http://svnbook.red-bean.com/en/1.0/re25.html">svn
+            revert</ulink></literal></term>
+
+            <listitem>
+              <para>Undo local edits.</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+
+        <para>The complete list of SVN commands is available <ulink
+        url="http://svnbook.red-bean.com/en/1.2/svn.ref.html">here</ulink>.</para>
+      </sect3>
+
+      <sect3>
+        <title>Conflicts</title>
+
+        <para>Because Subversion does not use a “locking” model of version
+        control by default, it is possible for many people (such as coauthors
+        and other collaborators) to have checkouts of the same repo and to
+        work on them in parallel—which means is possible to have conflicts.
+        For this reason, communicating with your collaborators is extremely
+        important, as is remembering to commit and update your files.
+        Conflicts can be resolved, but dealing with them can take time away
+        from the writing of your book. It’s better to avoid them.</para>
+
+        <para>See <ulink
+        url="http://svnbook.red-bean.com/en/1.2/svn.tour.cycle.html#svn.tour.cycle.resolve"><citetitle>Version
+        Control with Subversion</citetitle></ulink> for more on resolving
+        conflicts.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="triggering_pdf_builds">
+    <title>Triggering PDF Builds of Your Book</title>
+
+    <para>The PDF builds are created with the same XSL-FO stylesheets that we
+    use to typeset the final product that we send to the printer and sell as
+    an online PDF. The build process for DocBook books creates PDFs from a
+    valid <filename>book.xml</filename> file when commit messages include the
+    right string (<literal>orm:commitpdf</literal>).</para>
+
+    <para>You can generate a fresh PDF of your book every time you commit
+    changes to the SVN repository. To do so, run the following command
+    (substituting your own message <phrase
+    role="keep-together">before</phrase> the semicolon):</para>
+
+    <programlisting format="linespecific">$ <userinput>svn commit -m'<replaceable>Made some really important changes to Chapter 3</replaceable>; orm:commitpdf'</userinput></programlisting>
+
+    <para>To get the PDF, just run <literal moreinfo="none">svn up</literal>
+    on your working copy about 5–10 minutes after committing your files. The
+    PDF will be downloaded as <filename
+    moreinfo="none">pdf/book.xml.pdf</filename> in your working copy. If there
+    are any problems in generating the PDF, you’ll instead get a <filename
+    moreinfo="none">.buildlog</filename> file in the <filename
+    moreinfo="none">pdf/</filename> directory that lists the errors.</para>
+
+    <para>For PDF builds to work, the <filename>book.xml</filename> must be
+    valid. If it is not valid, the PDF will fail to build. See <xref
+    linkend="validating_your_xml" />.</para>
+
+    <note>
+      <para>Some users have reported that the <literal>svn up</literal> will
+      fail if the old <filename>book.xml.pdf</filename> is still open. Close
+      the file and then <literal>svn up</literal>. Please contact
+      <email>toolsreq@oreilly.com</email> with problems.</para>
+    </note>
+
+    <para>If you’re using a GUI client (see <xref
+    linkend="gui_svn_clients" />), the process is the same as on the command
+    line. You just need to add <literal>orm:commitpdf</literal> somewhere in
+    your log message.</para>
+
+    <para>The text <literal moreinfo="none">orm:commitpdf</literal> triggers
+    the PDF build, and it can be used with any commit from your working copy,
+    not just the <filename moreinfo="none">book.xml</filename> file or a
+    chapter file. So if you would like to generate a fresh PDF without making
+    any changes to your book files, you can add a separate scratch file to the
+    <filename moreinfo="none">current</filename> directory (or a subdirectory)
+    and just make modifications and commit the changes to it with the <literal
+    moreinfo="none">orm:commitpdf</literal> string.</para>
+
+    <sect2>
+      <title>Triggering PDF Builds of a Single Chapter</title>
+
+      <para>If instead of generating a PDF of the whole book when you commit
+      changes, you’d prefer to generate a PDF of a single chapter, you can use
+      the following command:</para>
+
+      <programlisting format="linespecific">$ <userinput>svn commit -m'<replaceable>Committing changes to Chapter 4</replaceable>; orm:chapterpdf <replaceable>@id_for_chapter</replaceable>'</userinput></programlisting>
+
+      <para>Here, the magic commit hook is <literal
+      moreinfo="none">orm:chapterpdf</literal> instead of <literal
+      moreinfo="none">orm:commitpdf</literal>. You’ll also need to include
+      <replaceable>@id_for_chapter</replaceable>, which is the value of the
+      <literal moreinfo="none">id</literal> attribute of the <literal
+      moreinfo="none">chapter</literal> in the XML file you want to create a
+      PDF of.</para>
+
+      <note>
+        <para>A quick way to retrieve the <literal
+        moreinfo="none">id</literal> via the command line is:</para>
+
+        <programlisting>$ <userinput>grep "&lt;chapter" ch04.xml</userinput>
+&lt;chapter id="practice_1_automated_testing"&gt;
+  &lt;chapterinfo&gt;</programlisting>
+      </note>
+
+      <para>The string “<literal moreinfo="none">orm:chapterpdf</literal>
+      <replaceable>@id_for_chapter</replaceable>” must appear at the
+      <emphasis>end</emphasis> of your commit message for the commit hook to
+      work.</para>
+    </sect2>
+
+    <sect2>
+      <title>Receiving Email Notifications When Committing</title>
+
+      <para>You can set up your O’Reilly SVN repository to send a notification
+      anytime you or someone else (another author, your editor, the O’Reilly
+      Tools team, etc.) commits. Email notifications are activated with an SVN
+      property. You can request that the <phrase
+      role="keep-together">notification</phrase> property be added by writing
+      to <email>toolsreq@oreilly.com</email>, or you can just add it
+      yourself:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Navigate to the directory in your working copy that you want
+          to add email <phrase role="keep-together">notifications</phrase>
+          to:</para>
+
+          <programlisting>$ <userinput>cd <replaceable>~/projects/my_book</replaceable></userinput></programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Add the <literal>orm:commitemails</literal> property,
+          specifying the email addresses to which you’d like notifications to
+          be sent (substitute in your email addresses for
+          <replaceable>email_1@domain.com</replaceable>, etc.):</para>
+
+          <programlisting>$ <userinput>svn pset orm:commitemails </userinput>
+  <userinput>'<replaceable>email_1@domain.com</replaceable>,<replaceable>email_2@domain.com</replaceable>,<replaceable>email_3@domain.com</replaceable>' .</userinput></programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Do an <literal>svn up</literal> to make sure you’re in sync
+          with the repo, and then commit the change to enable
+          notifications:</para>
+
+          <programlisting>$ <userinput>svn up</userinput>
+$ <userinput>svn commit -m'<replaceable>Adding email notifications for current/ directory.</replaceable>'</userinput></programlisting>
+        </listitem>
+      </orderedlist>
+
+      <para>That’s it. Notifications will now be sent to the addresses set in
+      the <literal>orm:commitemails</literal> property every time a change is
+      committed to the specified directory.</para>
+
+      <note>
+        <para>The <literal>orm:commitemails</literal> property is not
+        recursive—i.e., it will apply only to the directory to which it’s
+        applied, and not any subdirectories. So if you want email
+        notifications on subdirectories (e.g., the <filename>pdf/</filename>
+        directory in <filename>current/</filename>), you’ll need to add the
+        <literal>orm:commitemails</literal> property to those directories as
+        well, using the steps above.</para>
+      </note>
+
+      <para>To turn off notifications, you can remove the
+      <literal>orm:commitemails</literal> property as follows, and then
+      commit:</para>
+
+      <programlisting>$ <userinput>svn pdel orm:commitemails</userinput></programlisting>
+    </sect2>
+
+    <sect2 id="web_pdfs">
+      <title>Web PDFs (Parallel PDF Builds)</title>
+
+      <para>By default, when you trigger a PDF build on your SVN repo with the
+      <literal moreinfo="none">orm:commitpdf</literal> string, our toolchain
+      applies the XSL-FO stylesheets that we use for the print PDF. We use a
+      separate set of stylesheets for the PDFs that we sell online (as part of
+      the ebook bundles on <ulink
+      url="http://www.oreilly.com/">oreilly.com</ulink> and elsewhere), but
+      you can trigger a build of that “web-friendly” PDF, too. Some of the
+      features of these web-friendly PDFs include:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Page size is the trim size; no crop marks</para>
+        </listitem>
+
+        <listitem>
+          <para>Different hyperlink handling (see <xref
+          linkend="inserting_hyperlinks" />)</para>
+        </listitem>
+
+        <listitem>
+          <para>Colorized and clickable cross-references (see <xref
+          linkend="creating_xrefs" />)</para>
+        </listitem>
+      </itemizedlist>
+
+      <warning>
+        <para>By enabling web-friendly PDF builds, you will be triggering the
+        creation of two PDFs each time you use the <literal
+        moreinfo="none">orm:commitpdf</literal> string. Double the PDFs means
+        double the time it will take for you to see your new PDFs. But even if
+        you have a lot of content, you usually won’t have to wait longer than
+        15 minutes to receive both PDFs.</para>
+      </warning>
+
+      <para>Adding the web PDF build is just a matter of adding an SVN
+      property (similar to enabling email notifications). You can request that
+      the property be added by writing to <email>toolsreq@oreilly.com</email>,
+      or you can add it on your book directory yourself, as follows:</para>
+
+      <programlisting>$ <userinput>svn pset orm:parallel true .</userinput></programlisting>
+
+      <para>Then commit. Once the SVN property is in place, you will receive a
+      second PDF in your <filename>pdf/</filename> directory (named
+      <filename>book.xml.web.pdf</filename>) when you trigger a build using
+      the <literal role="keep-together">orm:commitpdf</literal> string.</para>
+
+      <para>To turn off parallel PDF builds, you can remove the
+      <literal>orm:parallel</literal> property as follows, and then
+      commit:</para>
+
+      <programlisting>$ <userinput>svn pdel orm:parallel</userinput></programlisting>
+    </sect2>
+
+    <sect2 id="displaying_comments_in_pdfs">
+      <title>Displaying Comments in Your PDF Builds</title>
+
+      <para>By default, text contained within XML comments
+      (<literal>&lt;!--</literal> <literal>--&gt;</literal>) or
+      <literal>remark</literal> elements (see <xref
+      linkend="adding_comments" />) will not be rendered in PDF builds.
+      However, if you’d like to have this text displayed in your PDFs—for
+      example, if you have comments for reviewers that you’d like to display
+      in your PDFs during tech review—you can do so by setting the
+      <literal>orm:draft</literal> SVN property on your book directory, as
+      follows:</para>
+
+      <programlisting>$ <userinput>svn pset orm:draft remarks .</userinput></programlisting>
+
+      <para>Then commit. Once the SVN property is in place, comments and
+      remarks will be displayed in red for easy visibility.</para>
+
+      <para>To turn off this feature in PDF builds, you can remove the
+      <literal>orm:draft</literal> property as follows, and then
+      commit:</para>
+
+      <programlisting>$ <userinput>svn pdel orm:draft</userinput></programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Generating Timestamps in Your PDF Builds</title>
+
+      <para>To display a per-page, user-friendly timestamp on your PDFs, you
+      can set the <literal>orm:timestamp</literal> SVN property on your book
+      directory, as follows:</para>
+
+      <programlisting>$ <userinput>svn pset orm:timestamp true .</userinput></programlisting>
+
+      <para>Then commit. Once the SVN property is in place, a timestamp will
+      appear in the top-left corner of the PDFs you create. It looks something
+      like this:</para>
+
+      <screen>--------------
+| 2010—03-05 |
+|  11:05:43  |
+--------------</screen>
+
+      <para>To turn off the timestamp in PDF builds, just remove the
+      <literal>orm:timestamp</literal> property, and then commit:</para>
+
+      <programlisting>$ <userinput>svn pdel orm:timestamp</userinput></programlisting>
+    </sect2>
+  </sect1>
+
+  <sect1 id="validating_your_xml">
+    <title>Validating Your XML Files</title>
+
+    <para>We require that XML files submitted to Production are valid DocBook
+    4.5. Many XML editors (like XXE or oXygen) will validate your XML for you
+    on the fly. You can also use our PDF build toolchain (see <xref
+    linkend="triggering_pdf_builds" />) to do a validity check, as the PDF
+    won’t build if the files aren’t valid.</para>
+
+    <para>Another option for validating on the command line is <literal
+    moreinfo="none">xmllint</literal>. This tool is preinstalled on Mac OS X
+    and is available for a wide range of operating systems as part of the
+    <filename moreinfo="none">libxml2</filename> package from <ulink
+    url="http://xmlsoft.org/downloads.html">xmlsoft</ulink>.</para>
+
+    <para>To validate your <filename>book.xml</filename> file using <literal
+    moreinfo="none">xmllint</literal>, run the following command:</para>
+
+    <programlisting format="linespecific">$ <userinput moreinfo="none">xmllint --postvalid --xinclude --noout book.xml</userinput></programlisting>
+
+    <para>Any validity errors will be printed to standard output. If the book
+    files are valid, no output will be produced.</para>
+
+    <sect2>
+      <title>Validating Locally Using an XML Catalog</title>
+
+      <para>By default, <literal>xmllint</literal> validates over the Internet
+      against the DTD located at the URL listed in the XML file’s DOCTYPE
+      declaration. But if validating over the Internet is undesirable, you can
+      set up a local copy of the DocBook 4.5 DTD and a local XML catalog for
+      validation purposes.</para>
+
+      <para>The easiest way to install a copy of the <ulink
+      url="http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">DocBook 4.5
+      DTD</ulink> is via your favorite package manager. It is available via
+      <ulink
+      url="http://trac.macports.org/browser/trunk/dports/textproc/docbook-xml-4.4/Portfile">MacPorts</ulink>
+      and <ulink
+      url="http://cygwin.com/packages/docbook-xml44/docbook-xml44-4.4-2">Cygwin</ulink>,
+      among other packaging systems.</para>
+
+      <para>Many packaging systems will create the necessary <filename
+      moreinfo="none">catalog</filename> file for you, but if you need to
+      write one yourself, you can find more details on doing so at <ulink
+      url="http://www.sagehill.net/docbookxsl/WriteCatalog.html"></ulink> and
+      a sample catalog file at <ulink
+      url="http://www.sagehill.net/docbookxsl/ExampleCatalog.html"></ulink>.</para>
+
+      <para>The default location where <literal
+      moreinfo="none">xmllint</literal> will look for the catalog file is
+      <filename moreinfo="none">/etc/xml/catalog</filename>. Alternatively,
+      you can set the environment variable <literal
+      moreinfo="none">XML_CATALOG_FILES</literal> to define another default
+      location for catalog files. Once you’ve got the DTD and catalog set up
+      locally, you can validate as before:</para>
+
+      <programlisting format="linespecific">$ <userinput moreinfo="none">xmllint --postvalid --xinclude --noout book.xml</userinput></programlisting>
+    </sect2>
+  </sect1>
+</chapter>