Mavenを使った簡単DocBook入門

DocBook

先ほど、DocBookは最終的な成果物であるHTML、PDFに変換できるようになるまで大変と書きました。しかし、Mavenを使うとそれも簡単になってきています。
JBoss.orgが提供している、maven-jdocbook-pluginを利用した、超簡単方法について紹介したいと思います。

JDKと、Maven2がインストールされていることを前提とし、以下の流れで説明していきます。

  1. プロジェクトの作成
  2. pom.xmlの作成
  3. ドキュメントの作成
  4. ビルド(HTMLの生成)

プロジェクトは以下の構成で作成します。src/main/docbook以下にDocBookのXMLやイメージファイルを置いていく構成となっています。

sample-docbook
 +-pom.xml
 +-src
   +-main
     +-docbook
       +-ja-JP
         +-images
         +-master.xml

pom.xmlは以下の内容にします。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.example</groupId>
	<artifactId>sample-docbook</artifactId>
	<version>1.0-SNAPSHOT</version>
	<packaging>jdocbook</packaging>
	<name>Sample Docbook Book</name>
	<description>Sample Docbook Book</description>
	<repositories>
		<repository>
			<id>repository.jboss.org</id>
			<name>JBoss Repository</name>
			<url>http://repository.jboss.org/maven2</url>
		</repository>
	</repositories>
	<pluginRepositories>
		<pluginRepository>
			<id>repository.jboss.org</id>
			<name>JBoss Repository</name>
			<url>http://repository.jboss.org/maven2</url>
		</pluginRepository>
	</pluginRepositories>
	<build>
		<plugins>
			<plugin>
				<groupId>org.jboss.maven.plugins</groupId>
				<artifactId>maven-jdocbook-plugin</artifactId>
				<extensions>true</extensions>
				<dependencies>
					<dependency>
						<groupId>org.jboss.seam</groupId>
						<artifactId>seam-docbook-xslt</artifactId>
						<version>1.1.0.GA</version>
					</dependency>
					<dependency>
						<groupId>org.jboss.seam</groupId>
						<artifactId>seam-jdocbook-style</artifactId>
						<version>1.1.0.GA</version>
						<type>jdocbook-style</type>
					</dependency>
					<dependency>
						<groupId>org.jboss</groupId>
						<artifactId>jbossorg-jdocbook-style</artifactId>
						<version>1.1.0</version>
						<type>jdocbook-style</type>
					</dependency>
				</dependencies>
				<configuration>
					<sourceDocumentName>master.xml</sourceDocumentName>
					<masterTranslation>ja-JP</masterTranslation>
					<formats>
						<format>
							<formatName>html_single</formatName>
							<stylesheetResource>
								classpath:/xslt/org/jboss/seam/xhtml-single.xsl
							</stylesheetResource>
							<finalName>index.html</finalName>
						</format>
					</formats>
					<options>
						<xincludeSupported>true</xincludeSupported>
						<xmlTransformerType>saxon</xmlTransformerType>
						<docbookVersion>1.72.0</docbookVersion>
						<localeSeparator>-</localeSeparator>
						<useRelativeImageUris>
							false
						</useRelativeImageUris>
					</options>
				</configuration>
			</plugin>
		</plugins>
		<pluginManagement>
			<plugins>
				<plugin>
					<groupId>org.apache.maven.plugins</groupId>
					<artifactId>maven-dependency-plugin</artifactId>
					<version>2.0</version>
				</plugin>
				<plugin>
					<groupId>org.jboss.maven.plugins</groupId>
					<artifactId>maven-jdocbook-plugin</artifactId>
					<version>2.1.2</version>
				</plugin>
			</plugins>
		</pluginManagement>
		<extensions>
			<extension>
				<groupId>org.apache.maven.wagon</groupId>
				<artifactId>wagon-webdav</artifactId>
				<version>1.0-beta-2</version>
			</extension>
		</extensions>
	</build>
</project>

DocBookのXMLである、master.xmlには例として以下の内容を記述します。これには、http://d.hatena.ne.jp/kakurasan/20080528/p1で書かれていた例を利用させて頂きました。

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<book xmlns="http://docbook.org/ns/docbook" version="5.0"
	xml:lang="ja">
	<info>
		<title>タイトル</title>
		<author>
			<personname>
				<firstname>太郎</firstname>
				<surname>山田</surname>
			</personname>
			<affiliation>
				<address>
					<email>taro@example.com</email>
				</address>
			</affiliation>
		</author>

		<copyright>
			<year>2008</year>
			<holder>Copyright (C) Taro Yamada</holder>
		</copyright>

		<abstract>
			<para>この本の概要</para>
		</abstract>
	</info>

	<preface xml:id="preface">
		<title>前書き</title>
		<para>前書きの段落</para>
		<para>前書きの2段落目</para>
	</preface>

	<chapter xml:id="chap1">
		<title>はじめの章</title>
		<para>段落</para>
		<sect1 xml:id="firstsect">
			<title>1段階目のセクション</title>
			<para>1段階目のセクションの段落</para>
			<sect2 xml:id="secondsect.firstsect">
				<title>2段階目のセクション</title>
				<para>2段階目のセクションの中の段落</para>
			</sect2>
			<sect2 xml:id="secondsect2.firstsect">
				<title>2段階目のセクションの2つ目</title>
				<para>2段階目のセクションの2つめの中の段落</para>
			</sect2>
		</sect1>
	</chapter>

	<chapter xml:id="chap2">
		<title>2番目の章</title>
		<para>2番目の章の段落</para>
	</chapter>
</book>

ビルドです。コマンドプロンプトからルートディレクトリ(pom.xmlのあるディレクトリ)で以下のコマンドを実行します。

mvn compile

初回実行の場合はわらわらと必要なライブラリをインターネットからダウンロードが行われます。
ビルドが成功すれば、target/docbook/plublish/ja-JP/html_single/index.htmlが生成されます。

※会社内などプロキシサーバ経由でインターネットに繋がっている環境で実行する場合は、Maven2のプロキシ設定が必要になります。

とりあえず、世の中で公開されているスタイルでHTMLを生成するだけであれば、pom.xml書いてコマンド一発たたくだけで実現可能なレベルまでになってきています。(今回は、JBossSeamのリファレンスマニュアルで利用されているスタイルを使用しました)

今回のような単純な変換であれば、ネイティブライブラリは一切使っていないので、Javaが動く環境であればOKというのもかなり良いです。