EclipseとDEP4Eで簡単DocBook環境

DocBookを試してみようと思っても、いろいろ導入するものがたくさんあって大変ですよね。
Windowsな場合、なおさら大変です。

# Eclipse Keplerを導入

Eclipseはポータブルな構造をしているので、用途ごとにEclipseを構築するとあとで楽だと思います。
Eclipse Standardを拾ってきましょう。

私は32-bit版のWindows8.1を使っているので、Windows 32 Bitを選択しました。

展開先は今回デスクトップにしました。

## workspaceの名前を変える

他のプロジェクトとカブるとたくさん出てきて邪魔臭いことがあるので、workspaceの場所を変えました。

Eclipseを起動すると、最初にワークスペースの場所を聞いてきますが、これを適当な場所に変更します。
私は`C:\Users\takehiro\workspace`となっていましたので、これを`C:\Users\takehiro\docbook-workspace`に変更しました。
皆様に於かれましてはご自由に設定ください。

ワークスペースが新規作成されてWelcomeが開かれますので、これを閉じます。

# DEP4Eを導入する

DEP4E、正式名称をDocbook Editing and Processing for Eclipseというそうです。

DEP4EはDocBookの編集環境と変換処理環境を一気に構築してくれます(名前のまま)。これ一発で整うので非常に楽ちんですね。XalanやSaxon, スキーマとかを拾ってきてPATHを通して、とやらなくてもいいんです。

インストールは下のアイコンをEclipseのワークスペースにドラッグ＆ドロップするだけです。
[![Drag and drop into a running Eclipse Indigo workspace to install Docbook Editing and Processing for Eclipse (DEP4E)](http://marketplace.eclipse.org/sites/all/modules/custom/marketplace/images/installbutton.png)](http://marketplace.eclipse.org/marketplace-client-intro?mpc_install=1441896)

もしくは公式サイト http://dep4e.sourceforge.net/ を御覧ください。

途中、署名がないという警告がでますが、インストールするためには承諾するしかありません。

# DocBook5.0プロジェクトを作成

早速DocBook5.0のプロジェクトを作成してみましょう。
`File`→`New`→`Other...`の順でクリックすると開くダイアログの中に`DocBook`が増えています。
![新規作成メニュー](https://qiita-image-store.s3.amazonaws.com/0/20589/dfaf8734-c950-65b2-77be-6ad8415b6490.png)
`DocBook5.0 Project`を選んで`Next`をクリックします。

あとはプロジェクトに適当な名前をつけて`Finish`です。

# ワークスペース全景
ワークスペースは下の図のようになっています。見慣れた構成ですね。
![ワークスペース全景](https://qiita-image-store.s3.amazonaws.com/0/20589/b105b9e7-e29b-74ad-0263-9da7229ba836.png)

左下にAntのViewが居ます。Antのツリーを展開すると、EPUB3やHTML5、PDFといった項目が並んでいます。
DocBookを変換するフォーマットのことで、これをダブルクリックするとビルドできます(PDFに変換しようとしたらヒープが足りないと言われてしまいました...)。

# 初期設定
初期設定を行っていきます。

設定はDEP4Eとプロジェクトの2つに行います。DEP4Eの設定は一回やるだけで良いですがプロジェクトでの設定はプロジェクトを作るごとに行わなければなりません。

## DEP4Eの設定 - 検証時のXML Inclusions
DocBookで大きな文書を作るとなると、セクションやチャプターごとにファイルを分けて作成することになるでしょう。
その際にXInclusion(XInclude)によって連結を指示しますが、初期状態ではXInclusionをバリデータが認識せず検証エラーになってしまいます。
これを検証成功させるためにInclusionを検証するようにします。

`Window`→`Preferences`とクリックし、下図の画面で`Process XML Inclusions`にチェックを付けます。
![dep4e-validation.png](https://qiita-image-store.s3.amazonaws.com/0/20589/22e9d997-e995-8208-b2d3-4351147b9c0e.png)

## プロジェクトの言語設定
変更しなくても特に問題ないかと思いますが念のため...

ワークスペースの`Navigator`のツリーにAntの`build.xml`がありますのでこれをダブルクリックして開きます。

デフォルトでは次のようになっていますが、

```build.xml
<?xml version="1.0" encoding="UTF-8"?>
<project name="DocBook" default="All">
	
	<property name="docbook.xml.filename" value="docbook" />
	<property name="docbook.xml.language" value="en" />
		
	<import file="${net.sourceforge.dep4e.resources}/ant/docbook_5-0.xml" />
	
</project>
```

5行目の`docbook.xml.language`の`value="en"`を`value="ja"`に変更します。

```build.xml
<?xml version="1.0" encoding="UTF-8"?>
<project name="DocBook" default="All">
	
	<property name="docbook.xml.filename" value="docbook" />
	<property name="docbook.xml.language" value="ja" />
		
	<import file="${net.sourceforge.dep4e.resources}/ant/docbook_5-0.xml" />
	
</project>
```

`docbook.xml.filename`のプロパティはビルド対象のファイルなので、これを`value="docbook"`から`value="master"`などとすれば、`master.xml`がビルド対象になります。

変更したら当たり前ですが保存することをお忘れなく...

## サンプルファイルの削除
サンプルファイルを削除します。
`Navigator`で`source`以下にある`en`フォルダをまるごと削除します。

## 文書のマスターファイルを作成
`Navigator`の`source`を右クリックして`Folder`を作成します。`Folder name`には`ja`と入力しましょう。
![dep4e-create-folder.png](https://qiita-image-store.s3.amazonaws.com/0/20589/1221ef2f-3a4d-ffa0-a842-e31ee445d846.png)

つづいて`ja`フォルダを右クリックして`DocBook 5.0 File`を新規作成します。
私の場合はルートエレメントは`section`にしました。この辺りは目的に合わせて変更します。
`File Name`には`docbook.xml`と入力します。これは`build.xml`の`docbook.xml.filename`プロパティの値に合わせます。
![dep4e-newfile.png](https://qiita-image-store.s3.amazonaws.com/0/20589/22d32cfb-3ec9-3149-4095-a813888d6bd8.png)

開いたファイルでそのまま作業をします。

## ルート要素の言語宣言を変更
作成されたXMLファイルのルート要素に、言語宣言がされていますがこれを変更します。

```xml
<?xml version="1.0" encoding="UTF-8"?>
<article xml:lang="en" xmlns="http://docbook.org/ns/docbook"
	version="5.0" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink">
```

`xml:lang="en"`を`xml:lang="ja"`に変更します。

```xml
<?xml version="1.0" encoding="UTF-8"?>
<article xml:lang="ja" xmlns="http://docbook.org/ns/docbook"
	version="5.0" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink">
```

なおこの作業は`DocBook 5.0 File`を作成するたびに必要になりますのでご注意ください。
もっとも、XMLファイルとして作成してイチから書いてしまえば問題無いですが。

## docbook.xmlの内容を削除

余計なサンプル文を削除してしまいます。

```docbook.xml
<?xml version="1.0" encoding="UTF-8"?>
<article xml:lang="ja" xmlns="http://docbook.org/ns/docbook"
	version="5.0" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink">
	<info>
		<title>Title of article</title>
	</info>
	<section>
		<title>Section title</title>
		<para>A paragraph.</para>
	</section>
</article>
```

# さぁ、DocBookで書き始めましょう！
以上でDocBookで書き始める準備が整いました。
DocBookにはたくさんのタグがあるので難解に感じますが、実際にはHTMLでページを書くくらいのタグを覚えればある程度のものはかけてしまいます。
必要になったら新しいタグを覚えてゆけばよい位の気持ちでいれば良いと思います。

マークアップ変換ソフトのPandocがDocBook対応しているので、MarkdownからDocBookに変換するのも手だと思います。