Introduction

Doxia allows you to write books like user manuals and guides in any format supported by Doxia. You can include the manuals directly in your generated site with links to the off-line friendly formats like XDoc, PDF, RTF and LaTeX.

The Xdoc output which has been rendered into this site can be viewed here.

The generated PDF is here and the generated RTF here.

How It Works

The only thing you need in addition to the content files is a simple book descriptor which specifies the ordering of the sections and the names for the chapters.

Creating a Book Descriptor

An XML file describes the layout of the book.

A sample is given below:

<book xmlns="http://maven.apache.org/BOOK/1.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/BOOK/1.0.0 http://maven.apache.org/xsd/book-1.0.0.xsd">
  <id>doxia-example-book</id>
  <title>XFire User Manual</title>
  <chapters>
    <chapter>
      <id>bind</id>
      <title>Bindings</title>
      <sections>
        <section>
          <id>bindings</id>
        </section>
        <section>
          <id>aegis-binding</id>
        </section>
        <section>
          <id>castor</id>
        </section>
      </sections>
    </chapter>
    <chapter>
      <id>transports</id>
      <title>Transports</title>
      <sections>
        <section>
          <id>transport-and-channel-api</id>
        </section>
        <section>
          <id>http-transport</id>
        </section>
        <section>
          <id>jms-transport</id>
        </section>
        <section>
          <id>local-transport</id>
        </section>
      </sections>
    </chapter>
  </chapters>
</book>

Configuring Doxia Book Maven Plugin

This example illustrates how to configure the Doxia Book Maven Plugin. It will render the book in three different formats. By default the output will be under target/generated-site/<format>/<book id> .

The currently supported format ids are: xdoc, pdf, latex, rtf, xhtml, doc-book

A sample pom.xml is given below:

<plugin>
  <groupId>org.apache.maven.doxia</groupId>
  <artifactId>doxia-book-maven-plugin</artifactId>
  <version>1.3-SNAPSHOT</version>
  <configuration>
    <books>
      <book>
        <directory>content/books/example-book</directory>
        <descriptor>content/books/example-book.xml</descriptor>
        <formats>
          <format>
            <id>latex</id>
          </format>
          <format>
            <id>xdoc</id>
          </format>
          <format>
            <id>pdf</id>
          </format>
          <format>
            <id>rtf</id>
          </format>
        </formats>
      </book>
    </books>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>render-books</goal>
      </goals>
      <phase>pre-site</phase>
    </execution>
  </executions>
</plugin>