タグ別アーカイブ: XML

XProcの紹介

makeが良い、悪い」という話が一部で盛り上がっているのを見ました。
結局ツールなので、「用途に向いていなくても慣れなどを取る」か「学習が必要でも別のものを使う価値が見合う」かといった、状況に合わせた選択が必要になるでしょう。個人的にはファイルの絶対パスをハードコードするのは可能な限り避けてほしいですが。

ビルドツールにも様々な得手不得手があるものですが、XMLに特化したものもあります。そんな導入で、XProcの話題です。

XProc: An XML Pipeline LanguageはXML文書やその他の処理を記述するための言語です*1
W3CのページのAbstractには“Pipelines generally accept zero or more XML documents as input and produce zero or more XML documents as output.”とあります。ステップ処理として記述ができる、ファイル操作についてもある程度はできるなど他にもありますが、XSLTとは目的も書き味も結構違います。

2010年に1.0がW3C仕様として勧告された後、勧告としてはそれが最新の状態がまだ続いています。しかし、2020年8月19日にXProc 3.0の最終ドラフトが上がっており*2、期待が持てるようになってきました。Editor’s Draftは8月31日に更に更新されていますが。ちなみに2.0は諸般の事情で見送られています。

また、XMLPressから2020年4月に『XProc 3.0 Programmer Reference』(Erik Siegel)*3が刊行されています。W3CのXProc仕様のEditorであるNorman Tovey-Walsh氏による推薦文もついていますし、Erik Siegel氏も XProc 3.0 editorial teamのメンバーです。
XProc 3.0についてはドラフト版仕様とこの本を読むのが確実でしょう。

XProc 3.0でのもっとも大きな改良点はXSLT同様にXPath 3.1に対応したことだと思いますが、今回はXProcの雰囲気だけ紹介します。


<!-- 1. Pipeline document: -->
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
  xmlns:xs="http://www.w3.org/2001/XMLSchema" version="3.0">

  <!-- 2. Pipeline port declarations: -->
  <p:input port="source" primary="true" />
  <p:output port="result" primary="true" />
  <!-- 3. Convert document to HTML: -->
  <p:xslt>
    <p:with-input port="stylesheet" href="xsl/basic-conversion.xsl" />
  </p:xslt>
</p:declare-step>

上のコードは『XProc 3.0 Programmers Reference』*3「Getting started with XProc」にある例です。
<p:declare-step>がルート要素です。inputやoutputを省略できる<p:pipeline>も使用できますが、
2行程度では大して労力は変わらないですね。

XMLSchemaのネームスペースが宣言されているのは、XSLT同様asで型を明示できるからです。

書かれた処理を簡単に書けば、「入力をxsl/basic-conversion.xslのXSLTで処理し、出力へ渡す」ということになります。しかし、よくわからないプロパティportの存在がありますね。それぞれの指定で想像が付くかと思いますが、inputによる入力を処理対象(source)というportにつなぎ、with-inputによる入力は(XSLT)スタイルシートというportにつなぎ、このスタイルシートによってsourceを処理します。そしてresultというportにつながった出力へ結果を渡す、という流れです。こう書くと同語反復をしているように感じられるかと思いますが、それぞれのportにきたものをステップ処理していく流れが直観に近い記述で書けるということです。他のportとしては、スキーマの検証のスキーマを渡すためのschemaなどがあります。
<p:xslt><p:validate-with-xml-schema>はデフォルトのstepです。portは決まったstepと結びついていて、portに渡したものは結びついたstepが記述されていれば、そのstepで処理されます。デフォルトのstepとport、そして独自のstepと結びついた独自のportを記述していくことがXProcの基本となります。

*1 https://www.w3.org/TR/xproc/
*2 https://spec.xproc.org/lastcall-2020-08/head/xproc/
*3 https://xmlpress.net/publications/xproc-3-0/



XSLT 3.0(XPath 3.1)JSONをXMLに変換せずに利用する

先週はXMLの形にしたJSONを、XMLにしないまま扱う方法について紹介します。CSLはでてきません。

XPath 3.1*1で名前にJSONが入る関数は4つです。

  • fn:parse-json($json-text as xs:string?, $options as map(*))
  • fn:json-doc($href as xs:string?, $options as map(*))
  • fn:json-to-xml($json-text as xs:string?, $options as map(*))
  • fn:xml-to-json($input as node()?, $options as map(*))

$optionsについては説明しません。JSONをテキストとして引数にとるのがfn:parse-json()fn:json-to-xml()
fn:json-doc()は外部JSONファイルを読み込むときなどに指定します。fn:unparsed-text()で取得したテキストをfn:parse-json()へ適用するのと
大体同じことを行います。今回取り上げるのはfn:parse-json()fn:json-doc()についてです。

mapとarray

関係する名前空間は次に挙げるものです。

  • fn=”http://www.w3.org/2005/xpath-functions”
  • map=”http://www.w3.org/2005/xpath-functions/map”
  • array=”http://www.w3.org/2005/xpath-functions”

XPath 3.1のmap構造とarray構造は一般的なプログラミング言語におけるそれとほぼ同じもので、JSONオブジェクトをそのままの形で格納できます。
先週登場したJSONを見てみましょう。

{
    "items": [
        {
            "id": "7646893/2E3MJB9A",
            "type": "book",
            "title": "スタイルシート開発の基礎",
            "publisher": "アンテナハウス株式会社",
            "publisher-place": "Tokyo",
            "event-place": "Tokyo",
            "ISBN": "978-4-900552-23-4",
            "language": "ja",
            "author": [
                {
                    "family": "アンテナハウス株式会社",
                    "given": ""
                }
            ],
            "issued": {
                "date-parts": [
                    [
                        2016,
                        5
                    ]
                ]
            }
        }
    ]
}

このJSONを外部ファイルとして取り込むには次のように記述します。

<xsl:param name="input" >'exported-data.json'</xsl:param>
...
<xsl:variable as="map(*)" name="jsonMap" select="fn:json-doc($input)"/>
<!-- または -->
<xsl:variable as="xs:string" name="json-text" select="fn:unparsed-text($input)"/>
<xsl:variable as="map(*)" name="jsonMap" select="parse-json($json-text)"/>

XMLに変換した先週と、mapやarrayを活用する今回はこの後がまったく異なります。

次の記述で、先頭のtitleを一息で取得します。

<xsl:value-of select="map:get(array:head(map:get($jsonMap, 'items')), 'title')" />

まず、最も外側のmapから、itemsのキーを持つ要素を取得します(map:get($jsonMap, 'items'))。
キーitemsの値はarray型です。このままmap:get()を行おうとしてもできませんから、arrayの先頭を取り出すarray:head()を使用しています。ところで上の記述はパイプ演算子を使えば次のように書けます。

<xsl:value-of select="map:get($jsonMap, 'items') => array:head() => map:get('title')" />

mapのarrayでは、map:find()を利用することで指定したキーの値を配列で得ることもできます。挙動の詳細はXPath 3.1*1かXSLT 3.0*2のページを確認してください。

typeの値が何種類かに決まっていて、その種類を元にif文の判定をしたいのであれば、次のように書けます。

     <xsl:variable as="map(*)" name="item" select="map:get($jsonMap, 'items') => array:head()" />
      <xsl:if test="map:get($item,  'type') =  'book' or 'proceedings'">
      <xsl:value-of select="map:get($item, 'type')" /> <!-- book -->
      </xsl:if>

もちろんXMLの構造に変換しても同じことはできますが、より一般的なプログラミング言語に近い形で扱えています。

mapやarrayとして扱うために、JSONテキストとして記述してパースしたり、select="map{"key":value}"のような書き方をする以外に、<xsl:map><map-entry>を使うことができます。

mapの操作はエントリの追加やキー指定での削除などの他、map:merge()によるmapの統合、map:for-each()によるmap要素単位での関数適用などが可能です。arrayの方はarray:fold-left()array:fold-right()の畳み込み関数や、array:for-each()でarrayの要素ごとに関数適用などなど、XML形式を扱うよりもすっきりした構文で記述が可能な関数が用意されています。

注意しなければならないこととして、mapであるかarrayであるかを間違えるとうまく値を取り出せません。$itemnodeでもないので、直接xml-to-json()は使えません。

仕様やSaxonのドキュメントとにらめっこをしながら紹介してきたXSLT 3.0とXPath 3.1のJSONの扱いですが、誤りなどありましたらご指摘ください。

*1 https://www.w3.org/TR/xpath-31/
*2 https://www.w3.org/TR/xslt-30/


参考資料



Citation Style Languageの話(2) – 引用データJSONのXML化

前回引用データとスタイルの分離の必要性については述べていたので、CSL自体の歴史を見てみました。

Citation Style Languageの歴史について、
CSLのページ*1によれば、Bruce D’Arcus氏を中心に開発され、初期はZoteroのSimon Kornblith氏
がコントリビュートしていました。近年は Frank G. Bennett, Jr. と Rintze M. Zelleによって開発が主導されています。リンクが張られている2010年9月の外部記事はすでに読めなくなっていて、Blogは1.0のニュースリリース*2からです。

Wikipediaの記事*3にはその前身はBiblioXという取り組みであると記載されているのですが、2020年8月31日現在BiblioXのページは消失しており、辿ることが少し難しいようです。BiblioXの発表は2004年ですので、合わせれば15年以上の歩みとなります。

脱線しますが、URLが失効しあるものの歴史を辿るのが難しいというのは堪えます。Web Archiveなどのプロジェクトにしても、無限、無制限というわけにはいきません。それでも、参照した情報元が分かるよう引用情報を記述することの大事さを噛みしめています。

引用データのJSONをXSLTでXML化する

さて、CSLの引用データを確認してみましょう。Zoteroの出力一覧に「Citation Style Language …」という文字列が見えます。ポチッとな……無事ダウンロードされました。

「export-data.json」が。


{
    "items": [
        {
            "id": "7646893/2E3MJB9A",
            "type": "book",
            "title": "スタイルシート開発の基礎",
            "publisher": "アンテナハウス株式会社",
            "publisher-place": "Tokyo",
            "event-place": "Tokyo",
            "ISBN": "978-4-900552-23-4",
            "language": "ja",
            "author": [
                {
                    "family": "アンテナハウス株式会社",
                    "given": ""
                }
            ],
            "issued": {
                "date-parts": [
                    [
                        2016,
                        5
                    ]
                ]
            }
        }
    ]
}

引用データそのものは文書レイアウトのような複雑な構造を持ちませんし、XML形式である必要はないですからね。とはいえXSLTでこのデータを扱うにはどこかの段階でXMLに変換する必要があります。幸いなことに2020年のXSLTはJSONだって簡単に扱えます。今回はJSONがXSLT3.0で扱えることを示します。

XSLT 3.0 (というよりXPath 3.1)ではmap、arrayという頼もしい機能が用意されていますが、今回は構造に登場するだけです。次のテンプレートでは、外部ファイルであるexport-data.jsonを読み込んでXMLとして表示します。unparsed-text()でテキストファイルとしてJSONを読み込み、読み込んだJSONをjson-to-xml()でXMLにします。


<xsl:param name="input" >export-data.json</xsl:param>     
<xsl:template name="xsl:initial-template">
      <xsl:copy-of select="json-to-xml(unparsed-text($input))"/>
</xsl:template>

結果のXMLを次に示します。

<?xml version="1.0" encoding="UTF-8"?><!--export-data.xml-->
<map xmlns="http://www.w3.org/2005/xpath-functions">
  <array key="items">
    <map>
      <string key="id">7646893/2E3MJB9A</string>
   <string key="type">book</string>
      <string key="title">スタイルシート開発の基礎</string>
      <string key="publisher">アンテナハウス株式会社</string>
      <string key="publisher-place">Tokyo</string>
      <string key="event-place">Tokyo</string>
      <string key="ISBN">978-4-900552-23-4</string>
      <string key="language">ja</string>
      <array key="author">
        <map>
          <string key="family">アンテナハウス株式会社</string>
          <string key="given"/>
        </map>
      </array>
      <map key="issued">
        <array key="date-parts">
          <array>
            <number>2016</number>
            <number>5</number>
          </array>
        </array>
      </map>
    </map>
  </array>
</map>

XML形式で出力せずに扱う方が便利なこともありますが、とりあえず今回のところは得られた引用データのXMLから一部を抜き取ってFOにしてみます。

<xsl:template match="j:string[@key='title']">
    <fo:inline font-family="sans-serif">『<xsl:value-of select="." />』</fo:inline>
</xsl:template>
<xsl:template match="j:map[@key='issued']">
    <xsl:apply-templates select="j:array[@key='date-parts']"/>
</xsl:template>
<xsl:template match="j:array[@key='date-parts']">
<fo:inline><xsl:value-of select="./j:array/j:number[1]" />年</fo:inline>
</xsl:template>
<xsl:template match="j:string[@key !='title']">
</xsl:template>

これをexport-data.xmlに適用します。かなり省略していますが、
export-data.xmlのtitledate-partsから年の値を取り出し、加工して出力できました。

<fo:inline font-family="sans-serif">『スタイルシート開発の基礎』</fo:inline><fo:inline>2016年</fo:inline>

CSLからXSLT、XSL-FOへの完全な変換まで到達予定でしたが、XPath3.1やXSLT3.0の機能を調べだしたら今回の記事に間に合わなくなったため、少し時間を空けて再挑戦したいところです。

*1 https://citationstyles.org/about/
*2 https://citationstyles.org/2010/03/22/citation-style-language-1-0/
*3 https://ja.wikipedia.org/wiki/Citation_Style_Language

関連記事

  1. Citation Style Languageの話(1)

Citation Style Languageの話(1)

個人用途での電子書籍管理は引用管理ソフトウェアであるZotero[1]を利用しています。物理的な文書も登録管理できますが、蔵書量の関係からまだ手をつけていません。休日にちまちまと登録しているのですが、休日の度に本が増えるので終わりはしばらく来なさそうです。
書きもので技術的内容・事実に依拠した内容を扱うにあたっては参考文献が重要になりますが、参考文献の書式は学会や論文誌によって異なっているものです。つまり、書誌情報と書式を分離して管理、利用する仕組みが求められることになります。このうちオープンで普及しているものとしてはBibTeXといったものがあります。どんなものを使おうとおこる問題ではありますが、BibTeXを使うにはBiBTeXの記法やBiBTeXを処理するツールへの習熟が必要です。

さて、Zoteroではさまざまな形式で管理している参考文献リストを、プラグインによってMicrosoft Wordなどにも出力できます。そしてより柔軟にこのリストを扱うフォーマットとしてCitation Style Language(CSL)[2]というXMLに基づくオープンフォーマットが利用できます。
CSLを処理するスタンドアロンのソフトウェア*もありますが、XMLですのでXSLTによる処理も可能です。次のCSLはCSL primer[3]のページから一部抜粋しています。

<?xml version="1.0" encoding="utf-8"?>
<style xmlns="http://purl.org/net/xbiblio/csl" version="1.0" default-locale="en-US">
<!-- Generated with https://github.com/citation-style-language/utilities/tree/master/generate_dependent_styles/data/asm -->
<info>
<title>Applied and Environmental Microbiology</title>
<id>http://www.zotero.org/styles/applied-and-environmental-microbiology</id>
<link href="http://www.zotero.org/styles/applied-and-environmental-microbiology" rel="self"/>
<link href="http://www.zotero.org/styles/american-society-for-microbiology" rel="independent-parent"/>
<link href="http://aem.asm.org/" rel="documentation"/>
<category citation-format="numeric"/>
<category field="biology"/>
<issn>0099-2240</issn>
<eissn>1098-5336</eissn>
<updated>2014-04-30T03:45:36+00:00</updated>
<rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License</rights>
</info>
</style>

この基本情報と、テキスト中での引用書式、参考文献リストでの引用書式、
ロケールによる表示変更、その他書式のためのマクロといった要素を組み合わせたものがCSLの構造です。
つまり、XSLTを記述する方針は、テキスト中での引用書式cs:citation
参考文献リストでの書式cs:bibliographyの記述を元に出力書式を用意し、そこに情報を流しこんで出力を行うことになります。
cs:macroの内の記述方法などはXSLTと似通ってはいますが、if文でelse節が使えたり、variableやtextの使い方が異なるなど注意を要します。

来週はCSLの経緯の概略と、CSLからXSL-FOへの変換に挑戦予定です。


* CSLを利用できるソフトウェアのリストはCSLのトップページ[2]にあります。

[1] https://www.zotero.org/
[2] https://citationstyles.org/
[3] https://docs.citationstyles.org/en/1.0.1/primer.html

関連記事

Citation Style Languageの話(2) – 引用データJSONのXML化


海外ウェビナー動画「CSSとXSL-FO:印刷出版に私はどちらを使うべきでしょうか?」(日本語字幕付き)

Xplor International(https://xplor.org/)主催のウェビナーにて、弊社副代表のMichael Millerが発表を行いました。

タイトルは「CSSとXSL-FO:印刷出版に私はどちらを使うべきでしょうか?」(原題:CSS or XSL-FO: Which should I use for producing print publications)です。
「CSSとXSL-FO、どちらを使うべきでしょうか?」という質問をよくいただきます。こののウェビナーではCSSとXSL-FO、それぞれの特徴や歴史的な背景を昨今の出版を取り巻く環境も含めてご紹介しています。技術的な内容は少なめで、どなたでも理解しやすい内容となっています。

ウェビナーの様子はYouTubeでご覧いただくことができますので、ぜひご視聴ください。

なおYouTubeの字幕機能を使えば、日本語字幕付きでご視聴いただくこともできます。
字幕の設定方法は、

  1.  動画右下の設定アイコン(歯車マーク)をクリック
  2. 「字幕」をクリック
  3. 「日本語」にチェックを入れる

以上の設定で日本語字幕付きでご視聴いただけます。



XSL-FO/CSSスタイルシートにより、XMLとHTMLをサーバー上で高速にPDFに変換!



アンテナハウス ウェビナー スケジュール一覧 2020


CommonMark文書をcmarkでXML形式にする

CommonMark[1]処理系のリファレンス実装であるcmark[2]は、その抽象構文木(AST)をXMLとして出力できます。さらに、このASTの文書型定義(DTD)も存在します。公開されていて、身近でミニマルなDTD、また文書のASTとして学習にも有用です。cmarkのインストール、DTDについての詳細は割愛します。

次のようなCommonMark文書があるとします。

# 見出しレベル1

CommonMarkにはDTDがある。

## 見出しレベル2

docutilsにもDTDがある。

これをcmarkでXML出力すると、次のようになります(xml:space="preserve"プロパティを省略して表示しています)。

<document>
<heading level="1"><text>見出しレベル1</text></heading>
<paragraph><text>CommonMarkにはDTDがある。</text></paragraph>
<heading level="2"><text>見出しレベル2</text></heading>
<paragraph><text>docutilsにもDTDがある。</text></paragraph>
</document>

CommonMarkのDTDの一部を抜き出すと、次のようになっています(表示を省略した箇所は「…」のように記述しています)。

<!ENTITY % block
         'block_quote|list|code_block|paragraph|heading|thematic_break|html_block|custom_block'>
<!ENTITY % inline
         'text|softbreak|linebreak|code|emph|strong|link|image|html_inline|custom_inline'>
...
<!ELEMENT paragraph (%inline;)*>

<!ELEMENT heading (%inline;)*>
<!ATTLIST heading
          level (1|2|3|4|5|6) #REQUIRED>
...
<!ELEMENT text (#PCDATA)>

CommonMarkの処理系を実装するときに厄介な、ある記法の途中での他の記法の割り込み処理などは変換後のASTには登場しませんから平和な見た目です。さて、このCommonMarkのDTDですが、コメントや見た目の調整のための改行を含めても90行程度。さらにこのXMLは変換前はCommonMark文書ですから、おおよそどんな見た目の記述がこの構造になるかの対応付けも整理をつけやすいのではないでしょうか。「<html_block>」や「<custom_block>」(あるいはこれらのインラインマークアップ)について真面目に考えるならもう少し難しくなりますが、CommonMark文書のASTとしての文書型定義は相当にシンプルです。


こんな記事[3]を見つけました。Markdownからの変換としては多くはLaTeX、近頃はCSS組版などがありますが、ASTをXMLで出力できるならこういったアプローチも可能ですね。目的によってはMarkdownを変換したXHTMLから更に変形するよりも単純な記述で求めるPDF出力を得られるでしょう。
ところで、アンテナハウス製品には最近のフォントも組版できるXSL-FOプロセッサー、Antenna House Formatterがあります。次回、CommonMarkのASTをFOに変換したものをAH Formatterで出力してみる予定です。


参考資料

  1. [1]https://commonmark.org/
  2. [2]https://github.com/commonmark/cmark
  3. [3] Markdown + XSL → PDF


Antenna House Formatter

DITA/XML Service Antenna House


関連記事


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

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に変換する

Pages: 1 2 3 4 5 6 7 Next