LwDITAで（途中まで）ドキュメントを書いてみました

これまでに数回Lightweight DITA（LwDITA）に言及したことがありました。LwDITAやDITAについては記事末尾の関連記事、参考資料をご覧ください。ざっくり書くと、リッチな文書フォーマットとその簡略化版です。

最近、社内でドキュメントにLwDITAを試用して執筆しています。これは少し正確ではなく、より正確にお伝えするなら「執筆していた」となります。現在DITA（ただし一部機能しか使用しない）に移行中となります。

そこそこ文量のあるドキュメントに使ってみての利点、欠点について記そうと思います。一部、実装と仕様どちらに対しての言及であるのか不明瞭である点がありますがご容赦ください。

LwDITAでできること

DITAとしての利点と、LwDITAとしての利点があります。DITAとしての利点はおおよそ次のようになります。

DITA文書の一部としてDITA-OTで処理可能
conref、keyrefが利用できる
トピック単位でファイルを分けて管理できる
メタデータに索引用のキーワードを集約できる

LwDITAはDITA文書の一部として、通常のDITAと混在して処理が可能です。管理の観点からすると必ずしも良くはありませんが、「最初LwDITAで書いてDITAへ移行していく」今回の私のユースケースや、「既存資産のDITAやXML形式を利用しつつ新規記述のコストを減らす」といったときに有用です。

conrefやkeyrefはDITAの機能で、簡単に言えばプログラム言語における変数をドキュメント中に使用できます。専門語の揺れを防いだり、URLの変更などに対応できます。長期的に同じドキュメントを使用したいときに便利です。

「トピック単位でファイルを分割して管理できる」、DITAがトピック指向の設計であるので、条件が合致するときは各ドキュメントの構成のシンプルさを保つことができます。後述する「索引の半自動化」に係わるところです。「メタデータに索引用のキーワードを集約できる」というのも大体同じメリットですが、メタデータを書く箇所がフォーマット側で各ファイル単位に用意されているものは実はあまり多くありません。

そして1行では書きにくいメリットとして、構造のどの位置で呼ばれたかによって、適用されるセクションレベルを変更できるという恩恵があります。簡単に例を挙げると、h2レベルの内容の途中で呼ばれた別ファイルの見出しトップレベルはh3と解釈されます。書いているうちにトピックを分割したくなったときなどに有用です。

LwDITAとしてDITAに対する利点は次があります。

単純な最低限のマークアップ（em、strong、italic、リスト……）

メディアコンテンツ対応も地味に仕様としてはDITA1.3より進んでいるのですが、これは出た時期によるもので、実用的にはDITAでも対応されているはず。

さて、とくにMDITA（と一部拡張プロファイルとしてHDITA記法）を利用していたのですが、次の利点があります。

MDITAではYAMLフロントマターにkeyword、category、author、source、トピックIDを記述可能
DITAに限らず別形式へ変換可能という安心感

メタデータは単純なKeyValue、あるいは簡単な入れ子となるようなものが多いため、汎用エディタを使ってXML形式で記述するのは冗長に感じるときがあります。YAMLでとりあえずパパっと書けるのは楽でした。

最終形をPDFと考えたとき、DITAではやりづらくなる箇所もあるかもということで、別形式にしやすい意味ではMarkdownは安心感があります。その分表現力に制約がかかりますが。

「チームメンバーの記述可能なフォーマットの共通スキルがHTMLやMarkdown」といったケースもありうるかもしれません。

LwDITAでできないこと

対応しているDITAメタデータ（prolog）が少ない
対応しているプロパティ、要素が少ない（特にMDITA）
独自拡張のDITAが対応できない

さもありなんといったところで、作業が進むと、簡易形式ゆえにオミットされた機能が使いたくなってきます。上に挙げた理由で、今はDITA化を進行中です。とはいえ、変換後もLwDITAと対応できない要素はあまり使っていません。

とくにMDITAの不満点として、<note> に対応する記法がありません。以前あった記法もなぜかdepricatedになったので、注やtipsなど、荒涼としたドキュメントにおけるポップでおしゃれなアクセントが書けないのです。

XDITAを飛び越えてフルウエイトのDITAに変換すると、<indexterm>、索引語の指定が使えるようになります。keywordとしてYAMLフロントマターに記述していた語へこのマークアップを行うと、トピックの開始位置に索引が自動でつくように設定できます。入れ子にもできるので索引のサブ項目もほとんど労力をかけずに可能です。

「特殊化したDITA」について軽く触れましたが、AH-DITAという拡張ではfo:propプロパティによってXSL-FO語彙によるスタイル付けをダイレクトに行うことができます。また、図表のフロート配置も<floatfig>で、より自由に行えるようになります。

その他細かいところや全体像などについても、そのうち記事にできればと思います。