Maven Tidy Plug-in - Quick Start DocBook Guide

1.0.0.beta-1

Copyright © 2010 Team - Maven Tidy Plug-in

Table of Contents

Installation
Adding the Maven Repository
Adding the Plug-ins to the project pom
Generate a Maven Project Site

This Quick Start DocBook Guide just explains how to modify a Maven Project (and Environment) to get DocBook content generated in a Maven Project Site. There is a more detailed explanation available in the User Guide section Making DocBook content available in a Maven project site .

Installation

What other software must be installed first?

  • Java JDK v1.5 (or higher)

  • Maven v2.1 (or higher)

Adding the Maven Repository

The Maven Tidy Plug-in is not yet available through the central Maven Repository, but can be found in the project specific Maven Repository http://docbook-utils.sourceforge.net/maven2.

This Maven Repository can be added in a few different ways to a Maven build environment. Below are the most common options listed.

  • Add the <pluginRepository> lines direct to the project pom.xml

    Single user - Single project

  • Add the <pluginRepository> lines to a <profile> in the ~/.m2/setting.xml

    Single user - Multiple projects

  • Add the repository http://docbook-utils.sourceforge.net/maven2 to a Maven Repository Proxy, like Nexus, Artifactory, etc.

    Multiple users - Multiple projects 

  <pluginRepositories>
    <pluginRepository>
      <id>docbook-utils</id>
      <name>DocBook Utils</name>
      <url>http://docbook-utils.sourceforge.net/maven2</url>
      <layout>default</layout>
      <releases>
        <enabled>true</enabled>
        <updatePolicy>daily</updatePolicy>
        <checksumPolicy>warn</checksumPolicy>
      </releases>
    </pluginRepository>
  </pluginRepositories>

Adding the Plug-ins to the project pom

Add the following plug-ins to the project pom.xml. Maybe add the <pluginManagement> part a parent project. 

  <build>
    <pluginManagement>
      <plugins>
    
        <!--  Generate (X)HTML / PDF documents from DocBook content  -->
        <plugin>
          <groupId>com.agilejava.docbkx</groupId>
          <artifactId>docbkx-maven-plugin</artifactId>
          <version>2.0.10</version>
          <executions>
            <execution>
              <phase>pre-site</phase>
              <goals>
                <goal>generate-html</goal>
                <goal>generate-xhtml</goal>
                <goal>generate-pdf</goal>
              </goals>
            </execution>
          </executions>
          <configuration>
            <xincludeSupported>true</xincludeSupported>
          </configuration>
          <dependencies>
            <dependency>
              <groupId>org.docbook</groupId>
              <artifactId>docbook-xml</artifactId>
              <version>4.4</version>
              <scope>runtime</scope>
            </dependency>
          </dependencies>
        </plugin>

        <!--  Clean up the, by docbkx-maven-plugin, generated HTML  -->
        <plugin>
          <groupId>net.sourceforge.docbook-utils.maven-plugin</groupId>
          <artifactId>maven-tidy-plugin</artifactId>
          <version>1.0.0.beta-1</version>
          <executions>
            <execution>
              <phase>pre-site</phase>
              <goals>
                <goal>tidy</goal>
              </goals>
            </execution>
          </executions>
          <configuration>
            <sourceDir>${project.build.directory}/docbkx/html</sourceDir>
            <destinationDir>${project.build.directory}/generated-site/xhtml/docbook</destinationDir>
            <replaceExtensionMap>
              <html>xhtml</html>
            </replaceExtensionMap>
            <jtidyConfiguration>
              <property>
                <name>output-encoding</name>
                <value>UTF-8</value>
              </property>
              <property>
                <name>output-xhtml</name>
                <value>true</value>
              </property>
              <property>
                <name>indent</name>
                <value>true</value>
              </property>
              <property>
                <name>wrap</name>
                <value>120</value>
              </property>
              <property>
                <name>write-back</name>
                <value>true</value>
              </property>
            </jtidyConfiguration>
          </configuration>
        </plugin>

        <!--  Generate Project Site  -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-site-plugin</artifactId>
          <version>2.1</version>
          <dependencies>
            <dependency>
              <groupId>org.apache.maven.doxia</groupId>
              <artifactId>doxia-module-xhtml</artifactId>
              <version>1.1.2</version>
            </dependency>
          </dependencies>
        </plugin>
      </plugins>
    </pluginManagement>
    
    <!--  Plug-in used in this project  -->
    <plugins>

      <!--  Generate (X)HTML / PDF documents from DocBook content  -->
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
      </plugin>

      <!--  Clean up the, by docbkx-maven-plugin, generated HTML  -->
      <plugin>
        <groupId>net.sourceforge.docbook-utils.maven-plugin</groupId>
        <artifactId>maven-tidy-plugin</artifactId>
      </plugin>

      <!--  Generate Project Site  -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

Generate a Maven Project Site

  • Generate the Maven project site 

    $  mvn  clean  site