DITA-OT 4.3で追加された`init`サブコマンドに独自テンプレートを追加する

2025-03-16 一部事実関係修正

DITA Open Toolkit（DITA-OT） 4.3が2025年2月15日にリリースされました。
DITA-OT Day 2025が2月16日に開催されるという日程だったので^[1]、そこで新規機能として紹介されているはずです。とはいえは22日現在はイベントのアーカイブなりスライドなりは公開されていません。

今回はvalidateサブコマンドとinitサブコマンド（プレビュー版）が追加されています。

validateは対象ファイルのスキーマバリデーションと参照類のチェックを行うために用意されたもので、preprocess処理のdry-runのような働きをします。出力処理において不正な状態のファイルがスキップされて処理され、それなりに長い時間をかけて徒労というシーンはありがちであるので助かる人がいるはずです。

initはテンプレートを提供する機能です。ドキュメンテーションツールのSphinxを使ったことがある人はsphinx-quickstartを思い浮かべてください。DITAは単独ファイルで文書を作ることは殆どなく、またルートマップの位置の制限など本質的でない嵌りポイントもあるため、デフォルトで提供されるグッドプラクティスはとくにビギナーに資するものでしょう。

まあ企業ユーザは大抵独自CCMS内でDITAファイルを作るので関係無いんですが。

usage

dita init <template名> で、指定したテンプレートが現在のパスに展開されます。

dita init <template名> 

ディレクトリを作成してその中にテンプレート内容を配置したい場合は--output <ディレクトリ名>を追加します。

公開されたDITA-OT Dayの資料を見ると、--outputなしでもパスの直接指定で動くような説明をしていました。

dita init --listで現在利用可能なテンプレート一覧が表示されます。初期ではDITA-OTにバンドルされているsamples、startupの2つです。構成はOxygenXMLが提唱しているテンプレートに近いですが、theme機能用のファイルが追加されていたりします。

$ dita init --list
samples     DITA garage samples and Ant build scripts
startup     Startup template

https://www.dita-ot.org/dev/parameters/dita-command-arguments#dita-command-properties__subcommands

さて、initですが、ユーザ独自のテンプレートも追加できます。

plugin.xml

独自テンプレートを作成する場合も、出力プラグインや特殊化スキーマ追加プラグイン同様、DITA-OTプラグインとして実装します。

DITA-OTにバンドルされたorg.dita.initプラグインを見てみましょう。

org.dita.initプラグインのplugin.xml

<plugin id="org.dita.init" version="1.0.0">
  <feature extension="init.template" file="samples/" desc="DITA garage samples and Ant build scripts"/>
  <feature extension="init.template" file="startup/" desc="Startup template"/>
</plugin>

<feature>に@extension="init.template"が今回追加されています。@fileにコピーするファイル内容のパス（相対）が、@descにそのテンプレートの説明が記述されています。

これに倣って、plugin.xmlを書いてみます。

独自プラグインのplugin.xml

<plugin id="org.dddoooccc.templates">
    <feature extension="init.template" file="mytemplate/" desc="my template"/>
</plugin>

mytemplateの部分がテンプレート名として認識されます（その内変更されそうな気もする）。

フォルダ

init機能自体は指定されたフォルダ内容をコピーするだけなので、テンプレートとしてコピーさせるファイル内容についてはかなり自由です。
典型的な内容としてはDITAファイルの他、html出力用の固定ヘッダやフッタ・追加CSSなどでしょうか。

ポイントというより懸念として、DITA-OTはWindowsやLinux間でのパス周りでの修正が度々あるので、パス名に関係する部分は安全側に倒しておくことをお薦めします。つまり

• ASCII範囲
• 空白を含まない（WindowsでOKだがソフト側がガバいことがある）

有効化

上のplugin.xmlとテンプレートのディレクトリを格納したorg.dddooccc.templatesディレクトリを<dita-ot>/plugins下に配置してdita installを叩きます。

$ dita install
Added org.dddoooccc.templates
$ dita init --list
samples     DITA garage samples and Ant build scripts
mytemplate  my template
startup     Startup template

独自テンプレートが選択できるようになりました。

脚注

1. https://www.oxygenxml.com/events/2025/dita-ot_day.html