DocBook入門： DocBookで各種文書を作成する。

目次

はじめに

前準備

Apache FOPのインストール

ダウンロード

パッケージの展開

動作確認

DocBook XSL Stylesheetsのインストール

ダウンロード

インストール

DocBook文書の作成

DocBook文書からHTML文書の作成

スタイルシートの作成

Apache Xalan起動用スクリプトの作成

HTML文書の作成

DocBook文書からPDF文書の作成

設定ファイルの作成

スタイルシートの作成

PDF文書の生成

DocBook文書からEPUB文書の作成

スタイルシートの作成

EPUBファイルの作成

EPUBファイルの修正

EPUB文書の作成

参考文献

はじめに

DocBookは技術文書のための意味マークアップ言語である。当初はコンピュータのハードウェア、及び、ソフトウェアの技術文書を意図していたが、その他いろいろな文書を作成できる。

DocBookなら表示フォーマットに依存しない論理的な構造をもつ文書を作成できる。このような文書はオリジナルを修正せずにHTML、XHTML、EPUB、PDF、man pages、HTML Helpなどいろいろなフォーマットで出力できる。

現在のDocBookのバージョンは5.0で、RELAX NGスキーマで定義されたXMLで記述する。(他にはW3C XML スキーマ、Document Type Definition (DTD)スキーマを使用できるが、これらは標準ではない。)

DocBookはXML文書なので、一般的なテキストエディタで編集できる。DocBookは一般的なスキーマ言語でスキーマを提供しているので、スキーマによる補完が可能なXMLエディタならDocBookの補完もできる。いくつかグラフィカルなXMLエディタでは、ワードプロセッサのようにDocBookを編集できる。

DocBookは明確に定義されたスキーマに準拠するXML文書であるため、検証、及び、処理にXMLをサポートする一般的なツール、及び、プログラミング言語を使用できる。

DocBookファイルをいろいろなフォーマットの出力ファイルに変換するには、Extensible Stylesheet Language (XSL)という技術を使用する。これは次の三つの部分で構成される。

• XSL Transformation (XSLT)

  XML文書を他のXML文書(XHTML、XSL-FOなど)、または、XML以外のフォーマット(HTML、Plain Textなど)に変換するためのXML言語。

• XSL Formatting Objects (XSL-FO)

  ML文書を視覚的なフォーマット(PDF、その他の印刷可能なフォーマット)に変換するためのXML言語。

• XML Path Language (XPath)

  XML言語ではないがXSLTでXML文書の特定の部分を指定するための言語構文。

この文書では、XSLTとXPathプロセッサの実装であるApache Xalan、XSL-FOプロセッサの実装であるApache FOP、及び、DocBook用のXSLスタイルシートであるDocBook XSL Stylesheetsについて、インストール、及び、基本的な使用方法を説明する。ただし、DocBook文書を編集するためのXMLエディタについては説明しない。

前準備

Apache Xalan、及び、Apache FOPはJAVAアプリケーションのため、実行するにはJAVAの実行環境(JRE)、または、開発キット(JDK)が必要となる。よって、必要に応じてJAVAのJRE、または、JDKをインストールしておく。尚、7/28にJRE/JDK 7がリリースされているが、現時点では安定していないため、JRE/JDK 6の最新版を使用すること。

Windows環境では、7-zipなどのzip形式に対応したファイルアーカイバを用意する。

PDF文書を表示するために適当なビューワーを用意する。Linux環境ではEvince、Windows環境ではAdobe Readerなど。

EPUB文書を表示するために適当なビューワーを用意する。Linux環境ではFBReader、Windows環境ではAdobe Digital Editionsなど。

Apache FOPのインストール

Apache Xalanは、XSLTとXPathの実装の一つでApache Xalan Projectにより開発されている。また、Apache FOPは、XSL-FO プロセッサの実装の一つでApache XML Graphics Projectにより開発されている。

Apache FOPのパッケージにはApache Xalanが含まれているため、ここではApache-FOPのインストール方法を説明する。

ダウンロード

ダウンロードサイトから最新版のバイナリパッケージをダウンロードする。Binary DownloadのFOP Distribution mirrorリンクからミラーサイト一覧に移動できるので、適当なミラーサイトから以下のパッケージをダウンロードする。

<mirror-top>/xmlgraphics/fop/binaries/
    fop-1.0-bin.zip

パッケージの展開

ダウンロードしたパッケージを適当なディレクトリに展開する。以降このディレクトリを<fop-home>とする。

Linuxの場合

unzipを使用してパッケージを以下のディレクトリに展開する。

$ sudo unzip fop-1.0-bin.zip -d /opt/

Windowsの場合

7-zipなどのファイルアーカイバを使用してパッケージを以下のディレクトリに展開する。

> "C:\Program Files\7-Zip\7z.exe" x -oC:\opt\ fop-1.0-bin.zip

動作確認

Apache FOPでサンプルファイル(readme.fo)を画面に表示する。これにより、ビューワーが起動されReadmeが表示されれば、Apache FOPは正しくインストールされている。

Linuxの場合

コマンドプロンプトから<fop-home>ディレクトリに移動して、以下のコマンドを実行する。

$ cd /opt/fop-1.0
$ ./fop -fo examples/fo/basic/readme.fo -awt

Windowsの場合

コマンドプロンプトから<fop-home>ディレクトリに移動して、以下のコマンドを実行する。

> cd C:\opt\fop-1.0
> fop -fo examples/fo/basic/readme.fo -awt

DocBook XSL Stylesheetsのインストール

DocBook文書を他のフォーマットに変換するには、フォーマットに応じたXSLスタイルシートが必要となる。ここではThe DocBook Projectから配布されているDocBook XSL Stylesheetsを使用する。

ダウンロード

ダウンロードサイトから最新版のパッケージをダウンロードする。現時点では以下のパッケージが最新版となる。尚、ファイル名の"ns"はNamespace対応版という意味である。DocBook Ver.5.0以降ではこちらを使用する。

http://sourceforge.net/projects/docbook/files/docbook-xsl-ns/1.76.1/
  docbook-xsl-ns-1.76.1.zip

インストール

ダウンロードしたパッケージを適当なディレクトリに展開する。パッケージの中には、install.shなどのインストール用のスクリプトがあるが今回は使用しない。

Linuxの場合

unzipを使用してパッケージを以下のディレクトリに展開する。

$ sudo unzip docbook-xsl-ns-1.76.1.zip -d /opt/

Windowsの場合

7-zipなどのファイルアーカイバを使用してパッケージを以下のディレクトリに展開する。

> "C:\Program Files\7-Zip\7z.exe" x -oC:\opt\ docbook-xsl-ns-1.76.1.zip

DocBook文書の作成

テキストエディタを使用して、sample.xmlファイルを以下の内容で作成する。このとき、保存時の文字コードは必ずUTF-8とすること。例えば、Windowsのメモ帳であればファイルメニュー→名前を付けて保存で文字コードを選択できる。尚、改行コードはLF、CR+LFどちらでも問題ない。

<?xml version="1.0" encoding="utf-8"?>
<article version="5.0" xmlns="http://docbook.org/ns/docbook">
  <info>
    <title>DocBook文書から各種文書を作成する。</title>
  </info>
  <section>
    <title>Sample 1</title>
    <para>Hello World!</para>
  </section>
  <section>
    <title>サンプル2</title>
    <para>こんにちは世界！</para>
  </section>
</article>

DocBook文書からHTML文書の作成

Apache XalanとXSLスタイルシートを使用して、DocBook文書からHTML文書を作成する方法を説明する。

スタイルシートの作成

HTML文書用のXSLスタイルシートを作成する。実際には最初に予めインストールしたDocBook XSLのHTML用のスタイルシートを読み込み、その後変更するパラメータのみを記述する。

Linuxの場合

テキストエディタを使用して、docbook_html_linux.xslファイルを以下の内容で作成する。

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version='1.0' xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="file:///opt/docbook-xsl-ns-1.76.1/html/docbook.xsl"/>
  <xsl:output method="html" encoding="utf-8" indent="yes"/>
  <xsl:param name="l10n.gentext.default.language">ja</xsl:param>
</xsl:stylesheet>

Windowsの場合

テキストエディタを使用して、docbook_html_windows.xslファイルを以下の内容で作成する。

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version='1.0' xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="file:///C:/opt/docbook-xsl-ns-1.76.1/html/docbook.xsl"/>
  <xsl:output method="html" encoding="utf-8" indent="yes"/>
  <xsl:param name="l10n.gentext.default.language">ja</xsl:param>
</xsl:stylesheet>

各パラメータの意味は以下の通り。

• 3行目

  DocBook XSLのHTML用のスタイルシートを読み込む。

• 4行目

  出力形式をHTML、エンコーディングをUTF-8、及び、出力結果をインデントする。

• 5行目

  自動生成される文字列を日本語仕様とする。これにより、"Table of Contents"や"Chapter"などが"目次"や"章"などの日本語で出力される。

Apache Xalan起動用スクリプトの作成

DocBook文書からHTML文書を生成するにはApache Xalanを使用する。ただし、コマンド実行する度に長いCLASSPATHなどを毎回タイプするのは面倒なので、まずは起動用のスクリプトを作成する。

Linuxの場合

<fop-home>ディレクトリの下にxalanスクリプトを以下の内容で作成する。

$ cd /opt/fop-1.0
$ sudo vi xalan

#!/bin/sh
#
# Excecute Xalan-Java.
#
FOP_HOME=`dirname $0`

LOCALCLASSPATH=

DIRLIBS=${FOP_HOME}/lib/*.jar
for i in ${DIRLIBS}
do
    if [ "$i" != "${DIRLIBS}" ] ; then
      if [ -z "$LOCALCLASSPATH" ] ; then
        LOCALCLASSPATH=$i
      else
        LOCALCLASSPATH=$LOCALCLASSPATH:"$i"
      fi
    fi
done

java -cp $LOCALCLASSPATH org.apache.xalan.xslt.Process $@

$ sudo chmod a+x xalan

Windowsの場合

<fop-home>ディレクトリの下にxalan.cmdスクリプトを以下の内容で作成する。

@echo off
rem
rem Excecute Xalan-Java.
rem
SETLOCAL ENABLEDELAYEDEXPANSION

set LOCAL_FOP_HOME=%~dp0
set LIBDIR=%LOCAL_FOP_HOME%\lib

for %%i in (%LIBDIR%\*.jar) do set LOCALCLASSPATH=!LOCALCLASSPATH!;%%i

java -cp %LOCALCLASSPATH% org.apache.xalan.xslt.Process %*

ENDLOCAL

HTML文書の作成

xalanスクリプトからApache Xalanを実行し、XML文書(sample.xml)にスタイルシートを適用してHTML文書(sample.html)を作成する。

Linuxの場合

コマンドラインから以下のコマンドを実行する。

$ /opt/fop-1.0/xalan -xsl docbook_html_linux.xsl -in sample.xml -out sample.html

Windowsの場合

コマンドラインから以下のコマンドを実行する。

> C:\opt\fop-1.0\xalan.cmd -xsl docbook_html_windows.xsl -in sample.xml -out sample.html

以下に作成されたHTML文書をWEBブラウザで表示した結果を示す。

図1 HTML文書の表示例

DocBook文書からPDF文書の作成

Apache FOPとXSLスタイルシートを使用して、DocBook文書からPDF文書を作成する方法を説明する。

設定ファイルの作成

Apache FOPはデフォルトではPDF出力時に日本語フォントを検索しないため、そのままではPDF文書の日本語が全て#記号に化けてしまう。Apache FOPに日本語フォントを検索させるため、fop_fonts.xconfファイルを以下の内容で作成し実行時に指定する。

<?xml version="1.0" encoding="utf-8"?>
<fop version="1.0">
  <renderers>
    <renderer mime="application/pdf">
      <fonts>
        <auto-detect/>
      </fonts>
    </renderer>
  </renderers>
</fop>

パラメータの意味は以下の通り。

• 6行目

  PDF出力時にOSにインストールされているフォントを自動検出する。

スタイルシートの作成

XSL-FO文書用のXSLスタイルシートを作成する。実際には最初に予めインストールしたDocBook XSLのXSL-FO用のスタイルシートを読み込み、その後変更するパラメータのみを記述する。

Linuxの場合

テキストエディタを使用して、docbook_fo_linux.xslファイルを以下の内容で作成する。

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version='1.0' xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="file:///opt/docbook-xsl-ns-1.76.1/fo/docbook.xsl"/>
  <xsl:param name="l10n.gentext.default.language">ja</xsl:param>
  <xsl:param name="ulink.show" select="0"/>
  <xsl:param name="paper.type">A4</xsl:param>
  <xsl:param name="hyphenate">false</xsl:param>
  <xsl:param name="title.font.family">TakaoExGothic</xsl:param>
  <xsl:param name="body.font.family">TakaoExMincho</xsl:param>
  <xsl:param name="monospace.font.family">TakaoMincho</xsl:param>
</xsl:stylesheet>

Windowsの場合

テキストエディタを使用して、docbook_fo_windows.xslファイルを以下の内容で作成する。

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version='1.0' xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="file:///C:/opt/docbook-xsl-ns-1.76.1/fo/docbook.xsl"/>
  <xsl:param name="l10n.gentext.default.language">ja</xsl:param>
  <xsl:param name="ulink.show" select="0"/>
  <xsl:param name="paper.type">A4</xsl:param>
  <xsl:param name="hyphenate">false</xsl:param>
  <xsl:param name="title.font.family">MS PGothic</xsl:param>
  <xsl:param name="body.font.family">MS PMincho</xsl:param>
  <xsl:param name="monospace.font.family">MS Mincho</xsl:param>
</xsl:stylesheet>

各パラメータの意味は以下の通り。

• 3行目

  DocBook XSLのXSL-FO用のスタイルシートを読み込む。

• 4行目

  自動生成される文字列を日本語仕様とする。これにより"Table of Contents"や"Chapter"などが"目次"や"章"などの日本語で出力される。

• 5行目

  デフォルトではリンクを設定した文字列の直後にリンク先のURIが展開されるが、これを抑制する。

• 6行目

  出力サイズをA4とする。

• 7行目

  ハイフネーションを無効にする。日本語を使用する場合、実行時にハイフネーションのエラーが出るのでそれを抑制する。

• 8行目

  タイトルのフォントを指定する。Linuxの場合、TakaoExゴシック、Windowsの場合、MS Pゴシックとする。

• 9行目

  本文のフォントを指定する。Linuxの場合、TakaoEx明朝、Windowsの場合、MS P明朝とする。

• 10行目

  プログラムリストなどの等倍フォントを指定する。Linuxの場合、Takao明朝、Windowsの場合、MS明朝とする。

PDF文書の生成

Apache FOPを実行し、XML文書(sample.xml)にスタイルシートを適用してPDF文書(sample.pdf)を作成する。

内部的には、まずApache XalanとXSLスタイルシートを使用して、DocBook文書からXSL-FO文書が作成される。さらにApache FOPにより、XSL-FO文書からPDF文書が作成される。今回の例ではこの動作は一連で実行されるが、個別に実行することもできる。

Linuxの場合

コマンドラインから以下のコマンドを実行する。

$ /opt/fop-1.0/fop -c fop_fonts.xconf -xsl docbook_fo_linux.xsl -xml sample.xml -pdf sample.pdf

Windowsの場合

コマンドラインから以下のコマンドを実行する。

> C:\opt\fop-1.0\fop -c fop_fonts.xconf -xsl docbook_fo_windows.xsl -xml sample.xml -pdf sample.pdf

以下に作成されたPDF文書をAdobe Readerで表示した結果を示す。

図2 PDF文書の表示例

DocBook文書からEPUB文書の作成

Apache XalanとXSLスタイルシートを使用して、DocBook文書からEPUB文書を作成する方法を説明する。

スタイルシートの作成

EPUB文書用のXSLスタイルシートを作成する。実際には最初に予めインストールしたDocBook XSLのEPUB用のスタイルシートを読み込み、その後変更するパラメータのみを記述する。

Linuxの場合

テキストエディタを使用して、docbook_epub_linux.xslファイルを以下の内容で作成する。

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version='1.0' xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="file:///opt/docbook-xsl-ns-1.76.1/epub/docbook.xsl"/>
  <xsl:output method="xml" encoding="utf-8" indent="yes"/>
  <xsl:param name="l10n.gentext.default.language">ja</xsl:param>
</xsl:stylesheet>

Windowsの場合

テキストエディタを使用して、docbook_epub_windows.xslファイルを以下の内容で作成する。

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version='1.0' xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="file:///C:/opt/docbook-xsl-ns-1.76.1/epub/docbook.xsl"/>
  <xsl:output method="xml" encoding="utf-8" indent="yes"/>
  <xsl:param name="l10n.gentext.default.language">ja</xsl:param>
</xsl:stylesheet>

各パラメータの意味は以下の通り。

• 3行目

  DocBook XSLのEPUB用のテンプレートを読み込む。

• 4行目

  出力形式をXML、エンコーディングをUTF-8、及び、出力結果をインデントする。

• 5行目

  自動生成される文字列を日本語仕様とする。これにより"Table of Contents"や"Chapter"などが"目次"や"章"などの日本語で出力される。

EPUBファイルの作成

xalanスクリプトからApache Xalanを実行し、XML文書(sample.xml)にスタイルシートを適用してEPUB文書の中身となるファイルを作成する。尚、xalanスクリプトについては、上記「Apache Xalan起動用スクリプトの作成」を参照すること。

Linuxの場合

コマンドラインから以下のコマンドを実行する。

$ /opt/fop-1.0/xalan -xsl docbook_epub.xsl -in sample.xml

Windowsの場合

コマンドラインから以下のコマンドを実行する。

> C:\opt\fop-1.0\xalan.cmd -xsl docbook_epub.xsl -in sample.xml

これにより、XML文書(sample.xml)から以下のフォルダ、及び、ファイルが作成される。

META-INF/
  container.xml
OEBPS/
  ar01s02.html
  content.opf
  index.html
  toc.ncx

EPUBファイルの修正

作成されたファイルはこのままEPUB文書にアーカイブするとAdobe Digital Editionsでは日本語が文字化けするため、OEBPSフォルダの下の全てのHTMLファイルのhtml要素にxml:lang="ja"属性を追加する。

修正前

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    :

修正後

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xml:lang="ja" xmlns="http://www.w3.org/1999/xhtml">
    :

Linuxの場合

コマンドラインから以下のコマンドを実行する。

$ find OEBPS -name '*.html' | xargs sed -i -e's/^<html/<html xml:lang="ja"/'

Windowsの場合

PowerShellのコマンドラインから以下のコマンドを実行する。(実際には一行で入力すること。)

> powershell
PS> gci -r -i *.html OEBPS|
  %{(gc -en UTF8 $_)|%{$_ -replace'^<html','<html xml:lang="ja"'}|sc -en UTF8 $_}

EPUB文書の作成

EPUB文書はEPUB Open Container Format (OCF)という形式で作成する。mimetypeファイルを以下の内容で作成し、META-INF、OEBPSフォルダ、及び、配下のファイルをOCF ZIPコンテナと呼ばれる形式にアーカイブする。このとき拡張子はepubとする。尚、mimetypeファイルをアーカイブするさいに、以下の条件を満たす必要がある。

• mimetypeファイルはコンテナの最初のファイルであること。

• mimetypeファイルの内容はapplication/epub+zipとし、余計な空白文字や制御文字を含めないこと。

• mimetypeファイルは無圧縮、かつ、暗号化なしで、Local File HeaderにExtra Fieldが存在しないこと。

Linuxの場合

zipを使用してEPUB文書を作成する。

$ echo "application/epub+zip" > mimetype
$ zip -X0 sample.epub mimetype
$ zip -rX9 sample.epub META-INF OEBPS

Windowsの場合

7-zipなどのファイルアーカイバを使用してEPUB文書を作成する。ただし、7-zipではmimetypeファイルが先頭にならないため、epub文書の仕様を満たしていない。

> echo application/epub+zip > mimetype
> "C:\Program Files\7-Zip\7z.exe" a -tzip sample.epub mimetype -mx0
> "C:\Program Files\7-Zip\7z.exe" a -tzip sample.epub META-INF OEBPS -mx9

以下に作成されたPDF文書をAdobe Digital Editionsで表示した結果を示す。

図3 EPUB文書の表示例(ページ1)

図4 EPUB文書の表示例(ページ2)

参考文献

DocBook Wikipedia.

DocBook.org.

DocBook 5: The Definitive Guide.

DocBook XSL: The Complete Guide.

The DocBook Project.

The Apache Xalan Project.

Apache FOP.

EPUB Wikipedia.

International Digital Publishing Forum (IDPF) EPUB.

以上

2011/08/26 記事のタイトルを修正した。

2011/09/02 記事のカテゴリーを変更した。

2011/09/05 EPUB文書の作成の記述を修正した。