DITA入門パブリッシング

DITA image

　

DITAのパブリッシングでは、作成・編集したドキュメントをHTMLやPDFのデータ形式で出力するためにツールを使用します。本記事ではオープンソースのDITAパブリッシングエンジン「DITA Open Toolkit」（DITA-OT）のWindows 10での導入方法と簡単な出力例を紹介します。より詳細な情報はDITA-OTの公式Webサイト^[1]を確認してください。

用語

用語	説明
パブリッシング	DITAのドキュメント制作では、ドキュメントをトピックというコンポーネント単位で編集します。編集完了したドキュメントを出版物にする工程を「パブリッシング」と言います。パブリッシングは、HTML、PDFなどの媒体別に自動処理で行ないます。
Markdown	HTMLのタグなどに変換できる簡易的な記法です ^[2]
Apache Ant	Java言語のコンパイルやプログラムの実行手順をビルドファイルと呼ばれるXMLファイルに記述することで、自動的に行ってくれるツールです^[3]。DITA-OTで使用しています。
HTML Help	Microsoft Compiled HTML Help（HTML Help）はMicrosoftによって開発されたオンラインヘルプ用のデータ形式です。このデータ形式の出力にはHTML Help Workshopをインストールする必要があります。
Eclipse Help	統合開発環境Eclipseのヘルプで使用されているデータ形式です

DITA-OTについて

DITA-OT^[1]はApache License 2.0で公開されているDITAパブリッシングシステムです。 IBM社内で開発されていたものが2005年にオープンソースとして公開されました。本記事で紹介する機能はバージョン3.4を想定しているため、その他のバージョンでは動作しない場合があります。

DITA-OTの対応する出力形式

DITA-OTのWebサイトからダウンロードしたDITA-OTをセットアップすると、すぐに次の出力形式でパブリッシュができます。

また、プラグイン機構を備えており、自分で他のプラグインの処理を書き換える（オーバーライドする）プラグインを作って処理をカスタマイズしたり、様々な出力形式、目的のプラグインを追加することができます。

HTML （HTML5/XHTML）
PDF
Markdown （Markdown/GitHub Flavored Markdown/GitBook）
DITA
Eclipse Help
HTML Help

出力形式にあるDITAは、DITA-OTによってkeyrefの参照先やditamapに記載されたメタデータなどをトピック内に配置し直したDITAファイルを指します。他のシステムやプロジェクトでそのトピックを利用したい場合などを想定しています。 DITA-OTのWebサイトには「Normilized DITA」と表記されています。

HTML Help出力を利用する場合は、MicrosoftのDownloadセンターのページからHTML Help Workshopを入手し、セットアップしてください。

インストール直後の設定では、利用するXSLTプロセサにSaxon HE、 XSL-FOプロセサにApache FOP^[4]を使用するようになっています。

DITA-OTのセットアップ

Javaのセットアップ

Java Development Kit（JDK）またはJava Runtime Environment（JRE）が必要です。

Oracle JDKとOpenJDKのリンクを掲載します。要件を確認し、適したものを選択してください。

Oracle JDK（https://www.oracle.com/jp/java/technologies/downloads/）
Open JDK（https://adoptopenjdk.net/）

DITA-OTの処理を行う中心的な役割を果たすのがJava言語で記述されたdost.jarです。実行にはJDKまたはJREが必要です。使用する環境に合ったものを選択し、セットアップしてください。 DITA-OT3.4.0の動作に必要なJavaのバージョンは、8u101以降になります。インストーラにしたがってインストールした後、環境変数JAVA_HOMEに、インストールしたフォルダを設定してください。また、環境変数PATHに、%JAVA_HOME%\binを追加してください。

DITA-OTのセットアップ

DITA-OTのWebサイト（https://www.dita-ot.org/）からダウンロードした圧縮ファイルをインストールしたい場所に展開します。展開したフォルダを以後DITA-dirと呼ぶことにします。

「一度試してみたい」ということであれば、DITA-dirにあるstartcmd.batを実行すると DITA-OTが使える状態のコマンドプロンプトが立ち上がります。これはDITA-OTの動作に必要な設定がされた状態になりますが、一時的なものになります。startcmd.batは互換性のために残されているものなので、実際の使用では環境変数を設定してditaコマンドをコマンドプロンプトからすぐに実行可能な状態にしましょう。

環境変数PATHにDITA-dir\binを追加します。コマンドプロンプトを開き、dita --versionを入力して表示を確認してみましょう。

> dita --version
DITA-OT version 3.4.0

このようにバージョンが表示されれば完了です。以後、コマンドプロンプトからditaコマンドでDITA-OTを使用します。

DITA-OTの実行

DITA-OTを使ってDITAをHTMLやPDFとしてパブリッシングを行う例を紹介します。

DITA-OTの基本コマンド

ditaコマンドで使うおもな引数を次の表に示します。

対象	引数名	短縮した引数名	例
ditamapファイルか単一のditaファイル	input	-i	index.ditamap
出力形式の指定	format	-f	html5
条件分岐 ditavalファイル。複数あればWindowsなら `;` macOSなら `:` で区切る	filter
入力ファイルの基点になるパス	args.input.dir		samples
出力ファイル（フォルダ）名	output	-o	out/html
その他の設定を設定ファイルで指定	propertyfile		myproperty.properties

--input と --format が基本的な引数です。

--input に指定するのはファイルのパスは絶対パスまたは相対パスです。相対パスは、コマンドプロンプト上の現在のパスから指定します。--args.input.dir が設定されていればそこからの相対パスを指定します。

--format に出力形式を指定します。指定可能な出力形式の一覧は dita --transtypes で表示できます。

--output に何も指定しない場合、現在のフォルダ以下にoutフォルダが作成され、出力先フォルダとなります。

設定ファイルについては後述します。

実行例に使うDITAの構成

ここでは説明のために次のDITAドキュメントを用います。より大規模なDITAドキュメントのサンプルとしては、 DITA-OTを展開したフォルダの中にあるdocsrcに、DITA-OTのマニュアルを構成するDITAドキュメントが格納されています。

フォルダ構成は次のようにします。

D:\
- samples\
  - index.ditamap
  - topics\
    - about-dita.dita
    - install-dita-ot.dita
  - out\
    - html\
    - pdf\
  - myproperty.properties

about-dita.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="about_dita" xml:lang="ja-jp">
　　<title>DITAとは</title>
　　<shortdesc>DITAは、技術文書のためのアーキテクチャです。</shortdesc>
　　<conbody>
　　　　<p>Darwin Information Typing Architecture（DITA）は、
　　　　技術文書のためのアーキテクチャで、XML技術に基づいています。
　　　　IBMによって開発され、現在はOASISによって管理されています。
　　　　</p>
　　</conbody>
</concept>

install-dita-ot.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA 1.3 Task//EN" "task.dtd">
<task id="install_dita_ot" xml:lang="ja-jp">
　　<title>DITA-OTのセットアップ</title>
　　<shortdesc>ダウンロードしたDITA-OTの圧縮ファイルを展開し、パスを通します。</shortdesc>
　　<taskbody>
　　　　<prereq>JDKまたはJREをセットアップしておきます。</prereq>
　　　　<context>DITA-OTのセットアップ</context>
　　　　<steps>
　　　　　　<step><cmd>DITA-OTのサイトから圧縮ファイルをダウンロードします。</cmd></step>
　　　　　　<step><cmd>ダウンロードしたファイルを任意の場所に展開します。</cmd></step>
　　　　　　<step><cmd>展開した中にあるbinのパスを環境変数PATHに追加します。</cmd></step>
　　　　</steps>
　　</taskbody>
</task>

index.ditamap

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map id="index" xml:lang="ja-JP">
　　<title>DITAのはじめかた</title>
　　<topicref href="topics/about-dita.dita" type="concept" format="dita">
　　</topicref>
　　<topicref href="topics/install-dita-ot.dita" type="task" format="dita">
　　</topicref>
</map>

準備として、コマンドプロンプトを開き、samplesフォルダに移動します。

> cd D:\samples

HTML5の出力

--format に html5 を指定すると、HTML5形式が出力されることを確認しましょう。

D:\samples\>dita --input=index.ditamap --format=html5 --output=D:\samples\out\html

out\htmlにindex.htmlが出力され（画像 2）、同じく出力されたabout-dita.html（画像 3）、install-dita-ot.html（画像 4）へのリンクがあります。

PDFの出力

--format に pdf2 を指定すると、PDFが出力されます。この出力形式はApache FOP、XEP、AH Formatterに対応しています。出力に用いるXSL-FOプロセサは--pdf.formatterで指定できます。無指定の場合、デフォルトでは Apache FOPが使用されます。

D:\samples\>dita --input=index.ditamap --format=pdf2 --out=D:\samples\out\pdf

ひとつのPDFとして出力されたことが確認できますが（画像 5）、日本語が上手く表示できていません。原因はデフォルト設定が日本語の文字が収録されていないフォントを指定していることによります。これを変更するには、org.dita.pdf2のプラグインフォルダ下のfont-mapping.xmlの設定やApache FOP固有の設定を変更する必要があります。 DITA-OTのWebサイト1やApache FOPのWebサイト4 で設定方法を確認してください。

AH FormatterでPDFを出力

--format=pdf2 を今度はAH Formatterで出力してみましょう。

※Antenna House Formatter（AH Formatter）
（AH Formatterはアンテナハウスが開発・販売する商用XSL-FOプロセサです。 30日間評価版は無償配布。正式版は有償となります。詳しくはWebページをご参照ください。）

AH Formatterの設定ファイルを読み込むことで、Apache FOPよりも簡単に日本語フォントを使うことができます。一度AH Formatterを起動し、上部の「組版」「オプション設定を書き出す」で AHFSettings(x64).xmlを出力しておきましょう（画像 6）。このドキュメントのみに指定する設定であれば、出力した AH Formatterの設定ファイルのパスを --axf.opt に指定します。

D:\samples\> dita --input=index.ditamap
　　　　　　　--format=pdf2
　　　　　　　--out=D:\samples\out\pdf
　　　　　　　--pdf.formatter=ah
　　　　　　　--axf.cmd="C:\Program Files\Antenna House\AHFormatterV70\AHFCmd.exe"
　　　　　　　--axf.opt=samples\AHFSettings(x64).xml

プラグインによって、よりAH Formatterの性能を活かしたPDFを出力することができます。「補足」の項の「AH FormatterとPDF5-MLプラグインでPDFを出力する」をご覽ください。

補足

DITA-OTプラグインのインストール

DITA-OTの特徴のひとつであるプラグイン機構について紹介します。プラグインには次の3種類があります。

DITA-OTの公式ページに登録されているプラグイン
DITA-OTの公式ページに登録されていないが、ダウンロードURLが公開されているプラグイン
自身で作成したような、公開もされていないプラグイン

そして、プラグインの導入方法は2種類あります。

zipファイルを展開し、DITA-OTのpluginsフォルダにドラッグ＆ドロップする方法
dita --installコマンドでプラグインのパスを指定する方法

1の方法はその後にプラグインをDITA-OTが認識できるようにDITA-OTの設定ファイルにパスを追記を行う必要がありますが、2の方法ではDITA-OTが代わりに行ってくれます。

DITA-OT公式ページにある DocBook出力を得ることのできるプラグインは、次のようにして導入できます。

>dita --install org.dita.docbook

DITA-OT公式ページに登録がないものの、URLが公開されているようなプラグインは zipファイルをダウンロード可能なURLを指定します（DITA-OTのバージョンが3.1以前で公式ページに表示されているプラグインを導入する場合もこの方法になります）。

自分のローカルに置いたプラグインも、プラグインのパスを同様に指定することで同様にインストールできます。

プラグインをアンインストールする場合、 dita --uninstallコマンドにプラグインのIDを指定します。プラグインのID一覧は
dita --plugins
で確認できます。

プロパティの設定

コマンド実行時に引数で設定された値、--property=valueあるいは -Dproperty=valueによって処理が変わります。--propertyでの指定に対応していないパラメータをコマンド実行時に指定したい場合、-Dpropertyで指定してください。 XSL-FOプロセサの変更や出力ディレクトリなどをプロパティファイルに記述しておくことで、ditaコマンドを入力するときに省略ができます。

プロパティ設定ファイルの書き方

コマンド実行時に引数で設定された値（--property=valueまたは-Dproperty=value）
--propertyfileで指定するカスタムのプロパティファイル
DITA-dir\local.propertiesファイル
DITA-dir\config\org.dita.dost.platform\plugin.propertiesファイル
DITA-dir\config\configuration.propertiesファイル

同じプロパティに1～5で別の値を設定した場合、そのプロパティが読み込まれた最初の値が処理に適用され、その後に読み込まれた同じプロパティは無視されます。無指定だった場合、2～5の順にプロパティが読み込まれてデフォルト値として扱われるということです。

＜変更する設定項目＞ = ＜値＞のように記述します。 #で始まる行はコメントとして扱われます。 ${<項目>}のようにして項目の値を参照できます。設定可能な項目の一覧はDITA-OTのWebサイト^[1]、またはDITA-dir\doc\userguide.pdfにあります。

HTMLにカスタムしたCSSファイルとヘッダを指定したい場合、例えば次のようにプロパティファイルに記述します。カスタムCSSのあるフォルダがD:\samples\css\style.cssにあったとします。

# カスタムCSSの存在するフォルダを設定。args.input.dir="D:samples"が設定されているとする。
args.cssroot = ${args.input.dir}/css/
# カスタムCSSのファイル名
args.css = style.css
# .cssファイルをコピーして出力フォルダに配置するかどうか
args.copycss = yes
# 出力時CSSがコピーされる場所を出力フォルダからの相対パスで指定
args.csspath = static/css

XSL-FOプロセサにAntenna House Formatterを使いたい場合、たとえば次のようにプロパティファイルに記述します。

# XSL-FOプロセッサをAntenna House Formatterに切り替える（pdf2）
pdf.formatter = ah
# AHFCmd.exeのパス（pdf2）
axf.cmd = C:/Program Files/Antenna House/AHFormatterV70/AHFCmd.exe
# AH Formatterの設定ファイルを指定する。（pdf2）
axf.opt = C:/Program Files/Antenna House/AHFormatterV70/AHFSettings(x64).xml

どのパラメータを使用するかはプラグインにより異なります。プラグインの説明を参照するようにしてください。

AH FormatterとPDF5-MLプラグインでPDFを出力する

アンテナハウスが公開しているPDF出力用プラグインPDF5-MLとAH Formatterを使ってより高品質なPDFを出力してみましょう。

myproperty.properiesにahf.dirパラメータの設定を記述しました。

# myproperty.properties
# AH Formatterのあるフォルダを指定する（pdf5.ml）
ahf.dir = C:/Program Files/Antenna House/AHFormatterV70

pdf5.mlではpdf.formatter=ahを指定しなくてもXSL-FOプロセサにAH Formatterを使用します。axf.cmdを指定する必要はありません。環境変数AHF_DIRにAH Formatterのパスが設定されていれば、ahf.dirを記述する必要はありません。

>dita --install https://github.com/AntennaHouse/pdf5-ml/archive/V1.0.6.zip

D:\samples>dita -i index.ditamap -f pdf5.ml -o out\pdf --propertyfile=myproperty.properties

記事中に登場する操作（Windows 10）

インストールされているアプリケーションの起動

Windows 10では、既にインストールされているアプリケーションはタスクバーにある「ここに入力して検索」にアプリケーション名を入力すればアプリケーションが検索結果に表示されます。

環境変数の追加・編集

「環境変数の設定」画面を開きます。
「追加」を選択すると新しい環境変数の設定画面が開きます。すでに存在する項目を選択して「編集」を押すとその項目の値の編集画面が開きます。
設定した環境変数の値を他の箇所から参照したい場合は%で囲います。

自分以外のユーザがその環境変数を使用するような場合は「環境変数の設定」画面の下側「システムの環境変数」を設定しますが、編集するときは管理者モードで画面を開く必要があります。

参考資料

お問い合わせ

Webフォーム: Webフォームからお問い合わせ

電子メール: sis@antenna.co.jp