# Publishing Outputs

## Publishing a single document

The default publishing document units are: article and book. The output file name is optionnaly specified by the `-o` option.

You can also publish an article or book subset, i.e. you can run dblatex on an XML input whose root element is a chapter, a section, or anything else. In this case, dblatex wraps the root element in an article or in a book and print out a warning. The output subset does not contain any front matter data found in an article or in a book (cover page, revision history, etc.), but it can contain some back matter materials like an index.

    $ dblatex subset.xml
    Build the book set list...
    Build the listings...
    XSLT stylesheets DocBook - LaTeX 2e (0.2.11)
    ===================================================
    Warning: the root element is not an article nor a book
    Warning: element section(sec-subset) wrapped with article
    Build subset.pdf
    ...

## Publishing a Set of Books

When the document root element is a set, and when set.book.num is set to '`all`', dblatex ouputs a file per book contained in the set (and in the nested sets). In this case the `-o` option is ignored, and only the `-O` option is taken into account to specify the output directory that will contain the generated files.

Instead of building all the books, the user can publish a single book from the set, by setting the set.book.num parameter to the absolute position of the book in the set(s). By default set.book.num is set to 1 to publish only the first book.

The output file names are the book identifiers when use.id.as.filename is non zero, and when an identifier exists. If one of the two conditions are not met, the filename pattern is "`book<position in set>`".

Example: given the following set:

    <?xml version="1.0" encoding="UTF-8"?>

    <!-- setfile.xml. An example of set. All the books have an @id except one -->

    <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
    <set lang="en" id="a_set" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Set Title</title>
      <set>
        <xi:include href="book1.xml"/>   <!-- book #1 -->
        <xi:include href="book2.xml"/>   <!-- book #2 -->
        <xi:include href="book3.xml"/>   <!-- book #3 -->
      </set>
      <set>
        <set>
          <xi:include href="bookA.xml"/> <!-- book #4 -->
          <xi:include href="bookB.xml"/> <!-- book #5 -->
        </set>
        <set>
          <xi:include href="bookC.xml"/> <!-- book #6 -->
        </set>
      </set>
      <set>
        <xi:include href="book4.xml"/>   <!-- book #7 -->
        <!-- The following book, at 8th position in the sets, has no @id -->
        <xi:include href="book5.xml"/>   <!-- book #8 -->
        <xi:include href="book6.xml"/>   <!-- book #9 -->
      </set>
    </set>

Publishing this set produces 9 books in the `pdfdir` directory:

    $ dblatex -O./pdfdir -Pset.book.num=all -Puse.id.as.filename=1 setfile.xml
    Build the book set list...
    Build the listings...
    XSLT stylesheets DocBook - LaTeX 2e (0.2.11)
    ===================================================
    Output all the books from the set
    Writing sec1-mybook.rtex for book(sec1-mybook)
    Writing sec2-mybook.rtex for book(sec2-mybook)
    Writing sec3-mybook.rtex for book(sec3-mybook)
    Writing secA-mybook.rtex for book(secA-mybook)
    Writing book8.rtex for book
    Writing secC-mybook.rtex for book(secC-mybook)
    Writing sec4-mybook.rtex for book(sec4-mybook)
    Writing sec5-mybook.rtex for book(sec5-mybook)
    Writing sec6-mybook.rtex for book(sec6-mybook)
    ...
    Files successfully built in '/path/to/set/pdfdir':
    sec1-mybook.pdf
    sec2-mybook.pdf
    sec3-mybook.pdf
    sec4-mybook.pdf
    book8.pdf
    sec6-mybook.pdf
    secA-mybook.pdf
    secB-mybook.pdf
    secC-mybook.pdf