bookshop 0.0.4 → 0.0.9

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

@@ -1,707 +0,0 @@
-<?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>