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

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


XML と oXygen の勉強会

XML 入門と oXygen を使って JATS(学術雑誌論文記述用のXMLボキャブラリー)を入力してみるという二本立てでした。
事務局さんのご意向で「エラーを体験することでより深く XML を理解する」というような内容にさせていただいたのですが、これが結構新鮮で私も楽しませてもらいました。

もう3か月くらい前の話になってしまいますが、学術情報XML推進協議会さんの主催したセミナーでスピーカーを務めさせていただきました。
https://xspa.jp/post/183836958072/jats-xml初心者セミナー2-実践編2019513

XML-1

XML-2

とは言え、oXygen は誰でもエラーのないデータが入力できることを売りとしているツールですので、無理やりエラーを発生させるのはしんどかったです(笑)

弊社ではお客様のご要望に応じた内容でセミナーを開催しておりますので、ご興味のある方はいつでもご連絡ください。


久しぶりの XSLSchool(XSLTとXSL-FOの勉強会)

XML を自動組版するには XSLT の開発と XSL-FO の知識が不可欠です。HTML と CSS で組版しようという動きもあるにはありますが、まだまだ少数派でしょう。

弊社では XSLT と FO の両方を1日で学んでしまおうという、ちょっと贅沢なセミナーを開催しています。今まで 25 回以上開催し、ご参加者の延べ人数は 100 名様を超えてます。「XSLT や FO は名前を聞いたことはあるけれど…」という方々からご好評をいただいているセミナーで、6~7時間かけて XSL-FO の基礎を学びながら XSLT をひたすら入力していただく、ちょっとしたスパルタな内容です。

セミナーで使うテキストの一部

XSLSchool-2

XSLSchool-1

先日、久しぶりに XSLSchool 開催のご依頼をいただき、静岡にあるお客様のオフィスに出向き開催させていただきました。
来月も他のお客様から開催の打診をいただいています。

詳しくは「XSLSchoolのご案内」をご参照ください


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