さて、前回の記事ではMarkdown DITAとMDITAの違いについて確認しました。
Markdown DITAはMDITAと比べDITA形式へ変換するためのライティング形式の向きが強いという感想を書きましたが、MDITAをDITAへ変換することもそう難しいことではありません。
DITAパブリッシングエンジンDITA-OT[1]には、標準的な出力形式として「Normalized DITA」があります。
Normalized DITAについてはDITA-OTの出力形式についてのページ[2]や弊社の「DITA入門 パブリッシング」のページ[3]でも軽く紹介をしています。外部プロジェクトなどで使用できるように、内部パスの依存関係などを処理した状態のDITAを出力するものです。DITA-OTを使ってMarkdownファイルをDITAのXML形式にするには、この出力を用いるのが便利そうです[4]。XMLオーサリングソフト[5]などではより簡便な方法が用意されているかもしれません。
今回処理するMDITAファイルは次のsample.mdとします。DITA-OTのバージョンは3.4.1を使用しました。
---
id: sampleofmd
keyword:
- markdown
indexterm:
- md
---
# Markdownサンプル {.task}
これはMarkdownのサンプルです。
この文書は`dita --format dita`でDITA形式に変換されます。
## MDITAでセクション
これはMDITAでのセクション例。IDは自動で振られています。後からの比較のために、MDITAでは記法として有効でないものを含んでいます。
通常のDITAファイルであればDITA-OTは単体ファイルでも変換が可能ですが、
このsample.mdを直接処理しようとすると、エラーを吐きます。
dita -i \topics\sample.md --format=dita -o . Error: Failed to run pipeline: [DOTJ012F][FATAL] Failed to parse the input file 'file:/d:topics/sample.md'.: file:/d:topics/sample.md Line 1:Content is not allowed in prolog.
とりあえず今回はマップ経由で変換を行うことにします。
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map id="index">
<title>map title</title>
<topicref href="topics/sample.md" format="mdita" />
</map>結果を見ると、指定した場所にマップファイルとフォルダ構造を保った
トピックファイルがあります。フォルダへ移動すると、sample.mdファイルがありますね。
……？ md？ と思いながらファイルをエディタで開いてみると、拡張子はともかく
DITAのTopic情報タイプになっています。
<?xml version="1.0" encoding="UTF-8"?><?path2rootmap-uri ../?>
<!DOCTYPE topic
PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="sampleofmd"><title>Markdownサンプル {.task}</title><shortdesc>これはMarkdownのサンプルです。</shortdesc><prolog><metadata><keywords><keyword>markdown</keyword></keywords></metadata><data name="indexterm" value="md"/></prolog><body><p>この文書は<codeph>dita --format dita</codeph>でDITA形式に変換されます。</p><section id="mditaでセクション-secid"><title>MDITAでセクション {#secid}</title><p>これはMDITAでのセクション例。IDは自動で振られています。</p></section></body></topic>
topic のidはYAML Frontmatterで指定した通りになっています。
「{」「}」囲みで要素の追加マークアップを行う記法は処理されず、
そのままタイトルに残っていますね。
本文の最初の段落はshortdescに格納されています。
YAML Frontmatterと変換後のPrologを見ると、
keywords、keywordは想定通り処理されています。
一方でindextermは汎用のdata要素
にnameとvalueとして格納されてしまいました。
YAML FrontmatterのKeyValueはLwDITAの対応範囲内で処理されていることが分かります。
セクションを切った箇所では、Markdown記法の見出しが、
sectionのidの値として自動で振られています。ここも記法が対応していないので、
「{」「}」で囲われたマークアップは処理されていません。id内では記載できる文字の関係か、
微妙に表記が変わっています。
本文段落、
「`」「`」で囲われた箇所が<codeph>に変換されているのが確認できます。
もし<pre>になることを意図していた場合はExtended Profileでタグを直接書きます。
それでは、md.ditamapのtopicrefのformatを書き換え、
これをMarkdown DITAと認識させてDITAに変換してみましょう。
<topicref href="topics/sample.md" format="markdown" />先程と同様にマップをDITA-OTの入力に指定します。
<?xml version="1.0" encoding="UTF-8"?><?path2rootmap-uri ../?>
<!DOCTYPE task
PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="markdownサンプル"><title>Markdownサンプル </title>
<prolog><metadata><keywords><keyword>markdown</keyword></keywords></metadata>
<data name="id" value="sampleofmd"/>
<data name="indexterm" value="md"/></prolog>
<taskbody><context>
<p>これはMarkdownのサンプルです。</p>
<p>この文書は<codeph>dita --format dita</codeph>でDITA形式に変換されます。</p>
</context>
</taskbody>
<task id="secid"><title>MDITAでセクション </title>
<taskbody>
<context><p>これはMDITAでのセクション例。IDは自動で振られています。</p></context>
</taskbody></task></task>トピックタイトル行で設定したtaskが反映されています。一方で、YAML Frontmatterに記述したidは先程のindextermのように扱われ、topicのidにはなってくれていません。さらに、構造が色々壊れたものが出力されていますね。変換のコード実装を読まないとなんとも言えませんが、Strict Taskを想定しているのであればsectionは出現しませんから、Markdown DITAを書く場合には、より取り得る要素に注意しながら記述する必要があるということでしょうか。
MDITAをDITAに変換しました。Markdown DITAとの違いに注意する必要はありますが、
ドキュメントの段階的なDITAへのステップとして、
あまりピーキーではない制約のMarkdown文書をDITAの形式へ変換できることは
確かに悪くないと感じました。
DITAやDITA以外のXMLをMarkdownに変換する方向の試みも存在します。
次週はこのアプローチについて述べる予定です。
- [1] DITA-OT
- [2] Normalized DITA – DITA-OT
- [3] DITA-OTの対応する出力形式
- [4] Markdown content – DITA-OT
- [5] XML/DITA関連製品 – アンテナハウス
- 関連記事
- XMLエディタで始めるリッチなMarkdown入門？
- MDITA（LwDITA uses Markdown）の書き方
- DITAとしてのMDITA
- Markdown DITAとMDITA
- XMLをMarkdownに変換することについて
