# 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