タグ別アーカイブ: DITA-OT

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

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に変換することについて

海外出展情報 その2

Xploration 18 は、Xplor International、Electronic Document Systems AssociationR が主催する、プレゼンテーションと展示の両方を提供する会議で、 出席者が電子文書の傾向、ベストプラクティス、規定、新技術について学ぶ場です。 アンテナハウスが Xploration 18 で展示を行ったのは今年で2年目となります。

4月23日、Antenna House はコロラド州デンバーの CMS / DITA 北米会議 に出席いたしました。 この会議は、Center for Information-Development Management(CIDM)が主催し、プレゼンテーション、ワークショップ、展示などを行っています。 アンテナハウスは毎年 CMS/DITA North Americaで展示を行い、今年は多言語フォーマットに関するセッションで [ Formatting languages is easy as pie with DITA-OT and PDF5 (-ML Plugin)! ]  という題目で、展示を行いました。

DITA NA

アンテナハウス(海外サイト)
http://www.antennahouse.com/
http://www.rainbowpdf.com/

<< 海外出展情報 その1


海外出展情報 その1

米国アンテナハウスは今月(4月)2週間にわたって3つの異なるイベントに出席して参りました。 4月16日の週に、ワシントン DC で開催された JATS-Con 2018、フロリダ州オーランドで開催された Xploration 18 、そして4月23日は、コロラド州デンバーで開催の CMS/DITA North America に参加いたしました。

JATS-Con は、ジャーナル・アーティクル・タグ・スイート(JATS)を使用している、または学ぶことに関心のある人のための、2日間の会議です。 JATS は、学術雑誌を XML で記載する際に使われるスキーマの1種で、学術雑誌を記述するときの基準となる規格となっています。初回の JATS-Con は 2010 年に開催されました。会議の主催者、National Library of Medicine は Antenna House Formatter のユーザーで、JATS 実装のための XSL スタイルシートを開発しそれをパブリックドメイン(公有化)として提供しています。今年はアンテナハウスは JATS-Con の出席者として参加しました。この会議は、いつもアンテナハウスの多くのユーザーと出会う大変良い機会となっています。

あと2つのイベントについては明日ご紹介いたします。

アンテナハウス(海外サイト)
http://www.antennahouse.com/
http://www.rainbowpdf.com/

海外出展情報 その2 >>