カテゴリー別アーカイブ: XML-DITA

XMLをMarkdownに変換することについて

前回はMarkdownをDITAに変換する方法について紹介しました。
今回のテーマはXMLからMarkdownへの変換についてですが、見方を変えると、これは「なぜ情報量を落とす不可逆な変換をするのか」ということについてを考えることになります。
もちろん様々なニーズにより行われるのでしょうが、1つの文書型を扱う上でのこと、複数の文書型を扱う上でのこと、そして文書型のことを考えないときのことをみてみましょう。中間形式としての軽量マークアップについて扱っていますが、ライティング形式として扱いやすいといったメリットは今回は省きます。

XMLの欠点として挙げられることの多い点に「複雑」「冗長」といったワードを聞くことがあります。ここでいう「複雑」は構造の話であり、「冗長」は単純に統一された要素と属性のマークアップ記法によって起こる話といえるでしょう。軽量マークアップの多くはまさにこの点を克服するものですが、これは構造の表現力や記法の統一性とのトレードオフでもあります。

ある1つの文書型について考えてみます。文書型情報を持つ「XMLアプリケーション」と呼ばれるもの、XHTMLやDocBookやDITAといった文書では、「それらの文書型を背景に持ちつつ軽量な記法を使う」、今までの記事で取り上げてきたMDITAでいえば「トップレベルの見出しはtopicのtitle、最初の段落はshortdescにする」といったことが可能です。つまり、軽量の記法と変換される構造の対応を一対一に近いものにできます。文書型にもよるでしょうが、「XMLの構造を潰す」ものとしては最小限、不可逆ではあるものの復旧が行える可能性が高いものです。

複数の文書型を扱う上での軽量マークアップを経由する変換について考えてみます。ある文書型Aの文書から文書型Bの文書を変換、生成したいというときにはXMLにおいてはXSLTを使う方が大抵の需要に沿うでしょう。XSLTを逐一用意する必要こそあるものの、明確な構造の対応が取れるのであれば落とす情報、残す情報の選択も自在です。

この場合に落ちる情報には文書型Aの構造aに対応するBの構造がない、といったものもあります。ここで落ちる情報がXSLTを用意する手間を上回り、かつそれでも変換の必要があり、Aの文書もBの文書も相互にやり取りする頻度が高いといった場合には軽量マークアップを保存の形式に選択するのも考慮に入れてもよいかもしれません。変換先に該当の構造がなければその構造は潰れるしかありません。ある軽量な構造Mを、Aのときはこの構造になることにして、Bのときはこの構造を、とするのであれば、処理系の実装言語や環境の問題を除けばMからA、MからBの変換と、ABのXML+XSLT変換はそう変わらないことになります。この場合のMは、PandocやDocutilsの扱う抽象的なデータ型となるでしょうか。


アンテナハウスでは以前に『Markdown+CSS組版で冊子本(PDF)を作ってみる』[1]という書籍を作成しました。また、「Markdown + CSS/TeXで冊子本を作ってみた」[2]というセミナーを開催しました。このセミナーでは、Pandocを使用し、Markdownの拡張機能から抽象データ型にしたものをLaTeX用に変換し書籍を作成するラムダノート様による第一部と、Markdownと、HTMLタグで不足する構造を補ったものをXHTMLに変換し、CSSでスタイルを付与しAntenna House Formatter[3]で書籍を作成するアンテナハウスの第二部となり、対照的なアプローチでの発表となりました。少し話が逸れますが、Markdownそしてその他の軽量マークアップを最終的にHTMLやPDFといった閲覧用の形式にするにあたり、変換におけるどの層にカスタマイズのウエイトを置くのか。様々なバリエーションがあり、必要なスキルセットも方法によって異なります。これは、(できていたかは別として)構造と分離していた表現をどの段階で付与するかということでもあります。抽象データ型の変換で難しいことが起こるときは、(この記事筆者の体感的には)概ねこの部分の感覚の不一致です。


さて、最初のテーマ設定に戻ります。「なぜ情報量を落とす不可逆な変換をするのか」の答えとしては、「落として問題のない情報であるから」ということになるでしょうか。
当たり前の結論ではあります。
しかし「保存形式はXMLより必ずMarkdownがいいのだ」といった話ではなく、「補完可能」あるいは「変換不能」の情報があるとき、元のリッチな表現力の形式に固執すべきかということを考えてみてもよいかもしれません。

参考

  1. ラムダノートの技術 Advent Calendar 2019

関連資料

  1. [1]『Markdown+CSS組版で冊子本(PDF)を作ってみる』 アンテナハウス CAS-UB出版
  2. [2]Markdown + CSS/TeXで冊子本を作ってみた※終了しています
  3. [3]Antenna House Formatter V7

DITA/XML Service Antenna House

Antenna House Formatter

関連記事

  1. Markdown+CSS組版で冊子本(PDF)を作ってみる
  2. XMLエディタで始めるリッチなMarkdown入門?
  3. MDITA(LwDITA uses Markdown)の書き方
  4. DITAとしてのMDITA
  5. Markdown DITAとMDITA
  6. MDITAをDITAに変換する

MDITAをDITAに変換する

さて、前回の記事では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を見ると、
keywordskeywordは想定通り処理されています。
一方でindextermは汎用のdata要素
namevalueとして格納されてしまいました。
YAML FrontmatterのKeyValueはLwDITAの対応範囲内で処理されていることが分かります。

セクションを切った箇所では、Markdown記法の見出しが、
sectionidの値として自動で振られています。ここも記法が対応していないので、
{」「}」で囲われたマークアップは処理されていません。id内では記載できる文字の関係か、
微妙に表記が変わっています。

本文段落、
`」「`」で囲われた箇所が<codeph>に変換されているのが確認できます。
もし<pre>になることを意図していた場合はExtended Profileでタグを直接書きます。

それでは、md.ditamapのtopicrefformatを書き換え、
これを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. [1] DITA-OT
  2. [2] Normalized DITA – DITA-OT
  3. [3] DITA-OTの対応する出力形式
  4. [4] Markdown content – DITA-OT
  5. [5] XML/DITA関連製品 – アンテナハウス

DITA/XML - Antenna House

関連記事
XMLエディタで始めるリッチなMarkdown入門?
MDITA(LwDITA uses Markdown)の書き方
DITAとしてのMDITA
Markdown DITAとMDITA
XMLをMarkdownに変換することについて

Markdown DITAとMDITA

前回、MDITAのDITAとしての機能について紹介しました。
MDITAからDITAへの変換の前に、DITAのパブリッシングエンジンDITA-OT[1]の対応している「Markdown DITA」について、MDITAとの違いをおさえることにします。

DITAの軽量化版を作るという思想はLightweight DITA(LwDITA)[2]以前からありました[3]。というより、それらを受けた流れでLwDITAが登場します。ともかく、LwDITAは「標準化」という大きな違いはあるものの「唯一の軽量化されたDITA」ではない、ということです。

DITA-OTが対応する「Markdown DITA」は、LwDITAとは別にページが用意されています[4]。
LwDITAが策定中であるということもありますが、こちらは「フォーマットの仕様」というよりも、
「処理系に独自実装されたMarkdown(派生の)簡易記法」という理解をするのがよいでしょう。

Markdown DITAとMDITAはともにYAML Frontmatterにはよるメタデータの記述に対応していたり、Markdownとしての基本的な記法は共通しますが、(少なくとも今のところ)Markdown DITA側でしか対応していない記法があったり、それによる記述順序や変換時の要素の違いが存在します。

Pandoc header_attributes

PandocのMarkdownで拡張される見出しの記法に対応します。

# header {#id .outputclass}

見出しと同行で、半角空けて「{」「}」で囲まれた箇所に「#」とくっつけてid、「.」とくっつけてoutputclass(説明は省略します)を見出し情報に付与できます。見出しレベルが1、つまりトピックタイトルとなる見出し要素の場合、ここに「.task」「.concept」「.reference」と記述すると、それぞれ「task」「concept」「reference」としてMarkdownファイルが扱われることになります。他のものはoutputclass属性として扱われるだけです。

セクションレベルの見出しでは、「section」「example」が同様に特殊な扱われ方をします。

Hard Line Break

「文末に半角スペース2つ以上」としてMarkdownに一応用意されているもののDITAの書式に存在しない強制改行(HTMLにおける<br />)は<?linebreak?>として変換されます。

画像

画像の記法自体はMDITAでも対応していますが、Markdown DITAでは画像のタイトルを挿入できます。タイトルなしであればインラインの画像、タイトルがあれば<fig>の子として画像を変換するようです。


![alt](url "title")

keyref

リンク記法でURLを記載する「()」を省略した場合、keyrefとして扱われるとあります。URL参照するリンク、画像がこの対象です。変換されると<xref keyref=”key” />のようになります。

[key]
![key-2]

shortdesc

MDITAではショートデスクリプションは「本文の最初の段落要素」のようになっていましたが、Markdown DITAにはありません。

特殊化

「Pandoc header_attributes」の箇所で触れたように、Markdown DITAでは汎用トピックではなくtaskなど特殊化した情報タイプへ変換される場合があります。その場合、本文最初の段落がcontext要素として扱われたり、続く番号付き箇条書きがstep要素として扱われるなどします。

ここまで見てきましたが、Markdown DITAは「DITAを書ける人間が、XMLオーサリングツールがない環境でライティング形式として使用する」という用途が向いているようです。かなり近い性質の構造へ向かう文書のMarkdown記法に、こうした違いがあるというのはなかなか趣深いことではないでしょうか。

  1. [1] DITA-OT
  2. [2] Lightweight DITA: An Introduction Version 1.0
  3. [3] インテリジェントコンテンツにおけるAXの役割と考察 (2016/11/18, 関根哲也)情報処理学会研究報告 Vol.2016-DC-103 No.2
  4. [4]Markdown DITA syntax reference – DITA-OT

DITA/XML Service Antenna House

関連記事
XMLエディタで始めるリッチなMarkdown入門?
MDITA(LwDITA uses Markdown)の書き方
DITAとしてのMDITA

DITAとしてのMDITA

前回の記事で、MDITAで使えるMarkdown(派生)の記法について紹介しました。
しかし、MDITAの特徴は「Markdownの文法でトピック指向ライティングしたものをDITAに取り込める」ことに限りません。
DITAの機能(の一部)をMDITAから使うことができるのです。
とはいっても、Extended ProfileでHDITA(HTML5)の記法を使用してのもので、
「MDITAの機能」と言っていいのかは微妙なところですが。
前回の記事内容ではMarkdownとしてMDITAを各種ツールで扱うことができましたが、
今回紹介する機能を使用して期待した出力結果を得るには、
DITAのパブリッシングエンジン[1][2]を使用する必要があります。

conrefやkeyrefでは、リンクのURLやファイルのバージョンなど
変更される可能性がある(そして文書自体に変化は無い)要素の
文書中には参照を残しておき、その内容を別ファイルに
置くことができます。動作のイメージ図は「DITA超入門」[2]をご覽ください。

<!-- about.md -->
AH Formatterの最新版は<span data-conref="latest.dita#ver" />です。
<!-- latest.dita -->
<ph id="ver">7.0</ph>では...

パブリッシュした結果では次のように表示されます。

AH Formatterの最新版は7.0です。

また、出力に表示する要素をフィルタできる機能も限定的に使用可能です。
data-props属性に値を指定することで、トピック側の準備は完了です。


...XSL-FOでは上のように記述します。
<p data-props="notxslfo">もしCSS組版なら......</p>

フィルタの動作を記述する.ditavalファイルの中身はXMLで記述する必要があります。


<!-- ifcss.ditaval -->
<prop att="data-props" action="exclude" val="notxslfo" />

パブリッシュした結果では

...XSL-FOでは上のように記述します。

と、excludeした値が消えています。

これらの機能は、HDITAではdata-conrefdata-keyref属性にidを指定することで利用できます。

HDITAにはフレーズ要素<ph>が無いので、
単語などのkeyrefconrefでの置き換えには
<span>を用います。

LwDITAについてのより詳細な情報は、OASISによるイントロダクションのページ[4]や、前回の記事などをご覧ください。
次回は、MDITAからXDITA、DITAへの変換と編集についてを予定しています。

参考

  1. [1] DITA入門 パブリッシング
  2. [2] DITA-OT
  3. [3] DITA超入門 – アンテナハウス
  4. [4] Lightweight DITA: An Introduction Version 1.0

  5. DITA/XML - Antenna House

    関連記事

    1. XMLエディタで始めるリッチなMarkdown入門?
    2. MDITA(LwDITA uses Markdown)の書き方
    3. Markdown DITAとMDITA
    4. XMLをMarkdownに変換することについて

MDITA(LwDITA uses Markdown)の書き方

「『Markdown文書』は一意ではない」ということを以前の記事で少し触れました。
Lightweight DITA(LwDITA)[1]のMarkdown形式「MDITA」について、もう少しみていきます。
まだ固まった仕様ではありませんので、記事で触れた挙動が変更される可能性があります。
内容に誤りがあった場合はおしらせください。

DITAについての説明は弊社サイトの情報ページ[2]やOASISのDITA Committe[3]、DITAコンソーシアムジャパン[4]といったサイトをご覧ください。

さて、LwDITAの目的ですが、ざっくりとは「複雑でとっつきにくい仕様だから、簡単な所だけ抜き出して簡単に書けるようにして、今までと違う層にも使ってもらおう」というものです。

LwDITA導入のためのOASISのページ[5]がDraftながら存在します。
説明が「DITAのこの機能をこう表現できる、この機能はない」といった方向によっていて、目的のひとつである「XMLで巨大なDITAを使っていない層へのアプローチ手法」としては難しいところです。このページのドキュメントのソースはGitHubリポジトリにあり、最終更新が2018年なので少し不安になりますが、SubCommitteのページには2020年5月のやり取りのログが公開されていたりするので動いているはずです。
Work In Progressな状態ではありますが、DITAをサポートするエディタのMarkdown対応が始まり、DITA Open Toolkit[6]でLwDITAのPreviewサポートが入った状況を考えれば、すぐに破棄される状況ではなさそうです。何より、そのような場合でも通常のXMLや他形式への変換がそう難しくないようにLwDITAは設計されています。

LwDITA以前にあった軽量記法への取り組みなどの歴史もあり、「現在使える仕組み」についての資料はWeb上から探すには
少し労力が要ります。正道としてはLwDITA導入のページ[5]からReferenceを辿っていくことになりますが、前知識のない状態でリーチするには難しい情報がそこそこあります。LwDITAについての書籍は1冊刊行されていて[7]、LwDITA SubCommitteeの現在のco-chairであるCarlos Evia氏によるものですから、ある程度信頼して良いでしょう。オンデマンド印刷版は4千円で手に入ります。

GitHubでホスティングされているリポジトリでLwDITA、というよりMDITAによるドキュメントのソースも幾つか見つかりますが、
基本的にセクション、リスト、リンク、コードブロックといった、GitBookなどでも登場するような要素のみ登場していました。
LwDITAの機能を使い倒すよりは、XML経由のMarkdownビルドに使用しているという印象です。
勿論それも付き合い方の1つではあるのですが、もう少しアピールできそうなポイントもありそうです。

今回はMDITAで使う記法について紹介します。次回はMDITAで使える(HTMLタグを書くことになりますが)DITAの機能を紹介する予定です。

DITAの、というよりLwDITAのファイルは基本的に、ひとつの事柄について扱うトピックを単位としてファイルを分割します。
トピックファイルを構成する要素は次の4つです。

  • トピックタイトル
  • Prolog(メタデータ)
  • トピックのShort Description
  • トピックの本文(Body)

MDITAの記法はCore Profileと呼ばれる基本の部分と、Extended Profileと呼ばれる部分で構成されます。
Extended ProfileはMarkdown方言(派生)の記法で有名、有用なものを採用して、Core ProfileではHTMLタグを書かなかければいけなかったところを補うようになっています。とはいえ、どれがCoreでどれがExtendedなのか、LwDITA導入のページ[5]でも表記にばらつきがあるようです。

まずCore Profileの部分を紹介します。

MDITAのトピックタイトルは次のように、<h1>レベルに変換されるような見出し記法で記述します。
行頭に「#」を置いて見出し内容とは半角スペースを挟む、ATX形式と呼ばれる見出しの記法です。
見出し内容の後に半角スペースを置き、「#」を重ねて見出し行、区切りを強調もできます。


# トピックタイトル

もうひとつ、Setext形式と呼ばれる記法もあります。<h1>:相当の見出し内容の行の下に「=」を並べる記法です。


トピックタイトル
===============

MDITAで段落の区切りは空行を挟みます(つまり、2連続で改行を入れます)。
基本的に要素同士の区切りは空白行です。

Short Descriptionはある意味簡単である意味難しいものといえるでしょう。トピックタイトルの行から1行空け、
最初の段落がそうなります。記法としてはそれだけですが、トピック全体を簡潔に記述した内容とする必要があります。
DITAのShort Descriptionの書き方として、
「Short Descriptionを重視し、そこで完結するなら本文は空でもよい」と薦められることを考えれば、簡易記法としては合理的です。
SubCommitteeのログを見ると、そのうちに記法のバリエーションが増えるかもしれません。

残りの部分は本文となります。

見出し項目はトピックタイトルの紹介で登場した、ATX形式とSetext形式の記法があります。


## ATXの見出し項目 ##

Setextの見出し項目
-----------------

仕様的な強制はありませんが、同じ文書内で同じ見出しレベルの記法を、
ATX形式とSetext形式で混在させるのは避けるべきでしょう。個人的には、後述するYAML Frontmatterの区切りに「---」を使うので、見出し項目にSetext形式を使うことは避けています。

一般的なMarkdownでのATX形式の見出し記法は、「#」を追加し<h3>から<h6>に相当する見出しが可能ですが、MDITAで使用可能なのは<h2>相当までです。この制限はトピック指向で文書を記述する際の目安になります。
つまり、これより低い見出しレベルが必要ならばトピックを分割すべきかもしれないということです。

箇条書きは行頭に「*」または「-」または「+」、半角スペースを空けて箇条書き内容を記述します。行区切りで次の箇条書き項目を記述します。
文書中で箇条書き記号の混在はしないようにしてください。入れ子の場合、行頭から親のラベルと半角スペース分の空白を空けて同じように記述します。番号付き箇条書きはCoreなのかExtendedなのか微妙な書き方をされていますが、「1」から「9」の数字始まりの半角アラビア数字と「.」または「)」、半角スペースを空けて箇条書き内容で同様に記述します。


* 箇条書き1
* 箇条書き2
* 2-1

1. 番号付き
2. 番号付き

表は単純な表を記述できます。見出し列、寄せ方向の指定ができますが、複雑な表は書けません。
縦の区切りを「|」、見出しと内容の区切りを「-」で記述します。「-」の個数はひとつでも構いません。行末の「|」は省略する場合もあります。内容の途中で表示を改行したい場合<br>が使えます。
寄せは区切りを「:---:」のように「:」で囲むと中央寄せ、「---:」なら右寄せというように表記します。


|見出し項目1|見出し項目2|
|----------|-----------|
|   内容1  |  内容2     |

整形済みテキストは、「“`」のに挟まれた箇所になります。コードブロックを意図している場合はExtended ProfileのHTMLタグでブロックを記述した方が確実かもしれません。


package main
...

インラインの記法として、次があります。LwDITA導入のページ[5]からはCore ProfileなのかExtended Profileなのか判然としないところですが、Markdownの基本的な記法であるはずです。

  • *」または「_」で囲んだ<em>。ただしXDITAだと<i>
  • **」または「__」で囲んだ<strong>。ただしXDITAだと<b>
  • [表示する文字](URL)」でリンクテキスト。
  • ![代替表示文字列](URL)」で画像

インラインの整形済みテキスト記法の「`」囲いについては記述が見つけられませんが、
DITA-OTの処理を見ると有効のようです。

さて、Extended Profileについてです。

メタデータはYAML Frontmatterと呼ばれる記法で記述できます。ファイルの先頭、つまりトピックタイトルよりも先に、「---」と書かれた行に挟まれた部分に、設定記述用言語のYAML[8]を用いてトピックのメタデータを記述します。

メタデータに記述できる内容についてMDITAのイントロダクションページにはあまり記述がなく、例も次しかありません。

  • id
  • author

MDITA(のExtended Profile)と同じ表現力のXDITAにはDTDがあるので見てみると、
厳密には設定されていないようです。また、『Creating Intelligent Content with Lightweight DITA』[7]には次のようにあります。

Those attributes can provide information like the language of a topic, critical dates for a topic (creation, last revision, expiration, etc.), and much more.

DITA-OTのMarkdown Contentのシンタックスページは厳密にはMDITAのページではありませんが[9]、keyword, category, sourceといった項目をメタデータに設定している例があります。DITA的な文書の記述を行うなら、こういった情報を記載することはファイルの取り回しに有用でしょう。


---
id: topic-id
author: antenna
category:
- "markup"
keyword:
- "mdita"
- "markdown"
---

HTMLタグでの記述もExtended Profileの分類です。この部分の書き方の詳細はHDITAについての記述を読むことになります。
注意点として、HTMLタグで始めて閉じるまでの箇所の内部はMarkdownの記法は使えません。
先ほどのメタデータもHTMLタグで記述が可能です。

Creating LwDITAのサポートページと見なしてよいであろう、Carlos Evia氏のlwdita-bookのリポジトリ[10]に、MDITAの追加サポート記法として
定義リストと脚注の記法が記されています。



DT
: DD

空白行の後に行頭からタイトル<dt>、次行の行頭に「:」、半角スペースから<dd>、内容の記述を行います。空白行で終了、
行頭に「:」と半角スペース始まりで次の<dd>です。PHP Markdown Extra記法から、とあります。

脚注は、アンカーに「[^アンカーID]」、脚注内容を「[^アンカーID]: 内容」で記述します。


XML[^xml]は、…

[^xml]: Extensible Markup Languageは、…

他に、noteを記述する記法として「<div data-class="note">」がありましたが、MDITAでは非推奨となったということです。

次週にLwDITAで使えるDITAの機能について紹介する予定です。

参考資料

  1. [1] https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita-lightweight-dita
  2. [2] アンテナハウス XML/DITAサービス
  3. [3] https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
  4. [4] DITAコンソーシアムジャパン
  5. [5] Lightweight DITA: An Introduction Version 1.0
  6. [6] DITA Open Toolkit
  7. [7] Creating Intelligent Content with Lightweight DITA
  8. [8] https://yaml.org/
  9. [9] https://www.dita-ot.org/dev/topics/markdown-dita-syntax-reference.html
  10. [10] https://github.com/carlosevia/lwdita-book

DITA/XML Service Antenna House

関連記事

  1. XMLエディタで始めるリッチなMarkdown入門?
  2. DITAとしてのMDITA
  3. Markdown DITAとMDITA
  4. XMLをMarkdownに変換することについて

XMLエディタで始めるリッチなMarkdown入門?

Markdown記法とその派生は様々にあり、使用される場面もブログポストの原稿であったり、
Wiki記法(この記事ではHTMLへ変換される簡易記法、と考えてください)の1つであったりするので、「Markdownドキュメント」といっただけではどんな文書なのかはよくわかりません。「Markdown記法を使用して書かれている箇所があるドキュメント」くらいにはいえるのかもしれませんが。とはいえ、基本的な記法については共通しています。なので一度基本を覚えてしまえばその部分は他の派生へも通じ、その学習コストを下げることができます。

さて本題です。
「Markdownは分からないが手元にリッチなXMLエディタがある」そんなことはないでしょうか。

XML技術を駆使するDITAというドキュメントのアーキテクチャがあります。
いきなり導入するにはなかなか重量級な仕様と哲学があるので、
OASISのDITA CommitteeのSub Committeで、DITAやXMLを未だ使っていない層に向けたLightweight DITA(LwDITA)というものが考案されています[1]。
LwDITAはDITAの複雑な仕様から基本的なものを抽出し、XML、HTML5、Markdown(派生)の3つの形式でほぼ同じ表現力の記述を可能にしたものです。
特にHTML5、Markdownの形式(HDITA、MDITA)は、XML離れが激しい層へのアプローチ手法として考案された側面があり、XMLに触れなくともある程度のDITA体験が可能になっています。MDITAは単体ではGitHub Flavored Markdown(GFM)のサブセットのように扱えるので、GFMに対応したアプリケーションである程度執筆・編集のサポートが受けられます。

一方Oxygen[2]やXMetaL[3]といった、DITAをサポートするXMLエディタも
LwDITAもサポートし始めています。既にDITAのパワーをXMLエディタでフル活用されている方にはLwDITAの表現力は物足りないかもしれません。とはいえ、せっかくサポートされている機能です。もし手元に既にMarkdown対応のXMLエディタがあれば、試しに使ってみてはどうでしょうか。

参考資料

  1. [1] OASIS Lightweight DITA SubCommitteeのページ https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita-lightweight-dita
  2. [2] アンテナハウスの Oxygen情報ページ https://www.antenna.co.jp/oxygen/
  3. [3] アンテナハウスの XMetaL情報ページ https://www.antenna.co.jp/xmetal/

DITA/XML Service Antenna House

関連記事

  1. MDITA(LwDITA uses Markdown)の書き方
  2. DITAとしてのMDITA
  3. Markdown DITAとMDITA
  4. MDITAをDITAに変換する

XMetaLの保守契約更新手続きが止まっています

現在XMetaLの保守契約更新手続きが止まっています。原因はライセンス発行元のジャストシステム(カナダ)が新型コロナウィルス蔓延の影響で業務を停止しているからです。

この時代、ソフトウェアの開発会社が完全に業務を停止するというのもどうかと思うのですが、テレワークの準備をすることもできないくらい急な話だったのかもしれません。
更新手続きは止まっていますが、XMetaLの使用自体は引き続き行えますのでご安心ください。業務が再開され次第手続きに入らせていただきます。

なおoXygenの方は平時と同じように更新手続きを行っています。


oXygen 21.1 がリリースされています

oXygen のカレントバージョンは21.1です。古いバージョンをお使いの方はバージョンアップをご検討ください。

主な機能強化点は次のとおりです。

■ DITA 関連

  • 生成される WebHelp(日本語)の検索処理の改善
  • DITA マップやトピックから参照されるリソースの階層/依存関係の表示
  • 関連リンクとして追加できるトピックを素早く見つけられるように
  • 画像の挿入前にプレビュー確認

■ HTML 関連

  • 現在の編集場所で有効な要素、属性、および値の提案、多くの提案の注釈、およびHTML5仕様へのリンク

■ JSON 関連

  • JSON インスタンスを生成するためのさまざまなオプションを設定できるダイアログボックスを新設

その他多数の強化が行われています。詳しくは ここ をご参照ください。


「DITA Festa 2019 Tokyo」開催です

恒例の DITA Festa がやって来ます。
2019年11月27日(水)、28日(木)の二日間、場所は市ヶ谷駅のすぐ目の前です。

今回は、オムロン殿、日本電気殿、ローランド ディー.ジー.殿から DITA の導入事例発表があります。すでに受講受付が始まっていますので、興味のある方はお早めに。参加費は無料です。

詳しくは こちら をご参照ください。


海外出展情報 その1

10月にAntenna Houseは、Xplor Webinarとロンドンで開催された S1000D User Forum / ILS specification day に参加しました。

今回はXplor Webinarのご紹介をしたいと思います。

10月16日に開催された Xplor International が主催する教育ウェビナーで、弊社のシニアアーキテクトであるトニー・グラハムはAccessibility Mattersを発表しました。多くのアンテナハウスの顧客とパートナーがこのウェビナーに参加し、Xplorのメンバーもこの話題に興味を持っていました。このウェビナーはデジタルの世界においてアクセシビリティがいかに、またなぜ重要であるかを学ぶ絶好の機会でした。

プレゼンテーションの中で、トニーはHTML、Web Content Accessibility Guidelines(WCAG)、およびPDF / UA(Universal Accessibility)標準のアクセシビリティ機能を調査しました。アクセス可能なHTMLやPDFを作成するために必要な情報は、通常ソースXMLに含まれているか、ソースXMLから推測できるため、ユーザーの行動よりもファイル形式に重点を置いて調査しています。ただしXMLそのものをユーザーが目にすることはほとんどありません。このウェビナーでは、神経障害や失読症などの学習障害のある人がアクセスしやすいように、コンテンツのスタイリングが持ついくつかの側面についても調査しました。

プレゼンテーションはこちらのYouTubeからご覧いただくことができます。

https://www.youtube.com/watch?v=X00icPURCvw&feature=youtu.be


Pages: 1 2 3 4 5 6 7 8 9 10 Next