Built by Maven

Introduction

Doxia allows you to write books like user manuals and guides in any format supported by Doxia. Combined with the Doxia Book Maven you are able to 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 itself is a simple book descriptor which is used to specify the ordering of the sections and the names for the chapters.

See The Book Descriptor Reference for a reference to the descriptor.

Creating a Book Descriptor

An XML file is used to describe 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>
  <executions>
    <execution>
      <phase>pre-site</phase>
      <goals>
        <goal>render-books</goal>
      </goals>
    </execution>
  </executions>
  <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>
</plugin>