content/apt/book/index.apt

 -----
 Writing Books in Doxia
 -----
 Trygve Laugstol
 Vincent Siveton
 ------
 2012-04-13
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

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 {{{../doxia-example-book/index.html}here}}.

 The generated PDF is {{{../doxia-example-book/doxia-example-book.pdf}here}} and the generated RTF
 {{{../doxia-example-book/doxia-example-book.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 {{{../doxia-tools/doxia-book-renderer/book.html}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:

%{snippet|id=example|file=content/books/example-book.xml}

* 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:

%{snippet|id=configuration|file=pom.xml}