Chienomi

Markdownにまつわるお話

情報技術

ことの起こり

なんだか急にMarkdown関連のことが盛り上がってきた。

Commonmark絡みなのかもしれないけれど、ちょっと私にも言いたいこともある。

Takeshi KOMIYA‏さんによるツイートその1

Markdown は記法に限りがあるというシンプルさが強みであり、弱みだよね。表がないのが非常に不満だけど、それ以外は大体これで十分だよね。それ以降、いろんな人がいくつも派生記法を作っているけれど、どれも方言の域を出ていない。脚注や参照はなくても生きていけるんだ。

その2

もちろん、それで満足が行かない人たちがいるのは知っているし、ある用途 (執筆やら巨大なリファレンスの管理とか) では不十分なのは分かるけど、それは特別なユースケースであって、Markdown のそれから外れているだけなんだよね。そういう人たちは別のものを使う方が幸せになれる

へぇ、テーブルってMarkdownの標準じゃなかったんだぁ…というのはおいといて、私が言いたいのはこんな感じ。

少なくとも私はPandocのMarkdownに9割は満足している。 Kramdownでも良い

そして、Markdownの優れているところは単にシンプルたからではない。DocbookやPODやroffやtrfやXMLのようなドキュメントメタフォーマットと比べても多くの人に取って受け入れやすく、だからこそメタフォーマットとして非常によく機能することだ。

私には自分で作ったPureDocがある。けれど、Markdownのほうがよく使う。そのほうか変換の余地が大きく汎用性が高い。つまりはドキュメントメタフォーマットとして優れているのだ。 そして、Markdownは処理系依存でもそれほど困らないが、PureDocは他に処理系はない。

Markdownの拡張が気に食わない、そんな人はMarkdownでないものを使え、というなら、拡張されたMarkdownはMarkdownではない別のフォーマットだと思えばいいではないか。Markdownを名乗らなければいいのか？それとも、似た記法を使うなんてけしからんということか？

MarkdownはHTMLを含めることすら許しているんだ。足りなければ自分で拡張したっていいんだよ。好きなものを使えばいいさ。強制することなんかない。

そんなくだらないことで言い争わないで、空を見てご覧よ。今日は満月。天使が降りてきそうな素敵な星空だよ。こんなに月が明るいのに２等星までよくみえる。

ドキュメントメタフォーマット

とりあえず紹介

ブログに書くのだからもう少し補足しよう。

ドキュメントメタフォーマットというのは、なにか別の文書形式に変換することを前提としたドキュメント形式のことである。

例えばPODはそれ自体が読みやすいテキストではあるが、「意味付け」ということはできても、それがplain textの状態で「フォーマットすることで意味付けを感じられる」というようなものではない。 PODはトランスレータと呼ばれるソフトウェアに通すことを前提としており、これにより様々な形式に変換する。 対応形式はplain, man, html, latexが標準で付属し、そのほかにも様々な形式に変換可能だ。 Perl cookbookはPODで書かれているという。

RDocも似たようなもので、こっちはもっと「Wiki」っぽい。 こちらはriと呼ばれるtexinfo形式を標準としているが、HTMLにも変換できる。

Wiki記法、はてな記法はマークアップ形式だが、あくまでもHTMLに変換することを前提としている。 HTMLよりも楽に書けるとことがその価値であり、「HTMLの簡易記法」であるといえる。

plain2, reStructuredText, Re:view, AsciiDocはMarkdownに近いものだ。 plain2はLaTeXへの変換に限られているが、ReStructuredTextはSphinxを介して

  • HTML
  • LaTeX
  • ePub
  • Texinfo
  • man
  • plain

に変換することができ、Re:viewは

  • EPUB
  • PDF (LaTeX)
  • InDesign (IDGXML)
  • Markdown
  • plain text (TOPBuilder Text Markup Language)

asciidocは、(公式プロセッサではなく)asciidoctorが

  • HTML (HTML5)
  • XHTML (XHTML5)
  • DocBook (DocBook5, DocBook 4.5)
  • manpage
  • PDF
  • ePub 3
  • LaTeX
  • Mallard

に変換する。

これらのフォーマットは「そのフォーマットをplain textとして書いて、他の形式に変換する」ことを前提としているのだ。

ちなみに、これから執拗にDocBookの話をするが、DocBookもまた他の形式に変換するためのドキュメントメタフォーマットなのだが、「XMLまたはSGMLで書かれている」という特徴がある。 はっきり言えば、前述の形式と比べて圧倒的に読みにくく、書きにくい。 前述のフォーマットがHTMLよりも簡易な記述法を使っているのに対して、むしろODFやHTML, EPUBのようなドキュメント形式として作られたものだと考えたほうが良い。

だが、DocBookに執拗に言及するのは、DocBookが技術文書の形式として普及したからであり、かつトランスレータが多様であるからだ。標準処理系で

  • HTML
  • PostScript
  • PDF
  • RTF
  • DVI
  • plain

に対応している。

ちなみに、PureDocというのは私が作ったもので、RubyをベースとしたDSLである。 これは、Markdownのようなフォーマットが目指しているものとはちょっと方向性が違う。HTMLよりも簡易な記述とHTMLよりも強力な表現を求めており、実際変換したものはHTMLを拡張したものになる(XMLネームスペースを使って独自のタグを追加する)。

RubyのDSLであるため、「ロジックを含めた記述ができる」というのがポイントになっている。

読みやすいか??

まず言っておくが、どのフォーマットが優れているかということに関しては、もはや宗教であり、好みによる。

個人的にはReStructuredTextはかなり好きだ。 plain textの状態でも読みやすいし、表現力も高い。 Python(私は好きでない)のくせにやるじゃないか、と思う。

Re:View形式と、asciidoc形式はあまり好きではない。 PureDocがそんな感じじゃないかというかもしれないが、 plain textとしての自然さがないのだ。

例えば強調は、MarkdownやReStructuredTextでは

*強調されたテキスト*

となるが、Re:Viewは

@<em>{強調されたテキスト}

であり、asciidocには強調という概念がない。 (asciidocは「見た目」での定義であり、どちらかというとTeXなどに近い)

PureDocでは

e "強調されたテキスト"

となる。DocBook/XMLは完全に技術マニュアル用であり、そもそも「エレメントを定義しろ」とあるので、こちらも強調はない。 HTMLでは

<em>強調されたテキスト</em>

となる。RDocも見た目定義だが、一応「イタリックにするとiではなくemを使う」仕様なので

_強調されたテキスト_

となる。PODにも強調はなく、一応はイタリックを強調としているので

I<強調されたテキスト>

となる。

好みはともかくとして、ドキュメントメタフォーマットとしては「読みやすさ」は「表現力」に並ぶ重要な価値だ。 なぜならば、ドキュメントメタフォーマットはそもそもMicrosoft Word形式などのプロプライエタリフォーマットに対するアンチテーゼとしての意味合いがあるからだ。

そして、同時に「書きやすい」ことは、HTMLが簡易なマークアップ言語とはいえ、「普通の人が書くにはハードルが高い」という側面があったためで、より誰にでもかけて、HTMLのように面倒な(タグ表現が妙に長い上に、「なぜ終端にまでタグを書かなければいけないのか」という冗長さを避けたかったということから来ているように思う。

そもそも「書きやすいフォーマット」というのはWiki記法から流行り始めたように思うし、 徐々にブログなどでもHTMLではなくより簡易な記法でマークアップを可能にした。

ドキュメント形式なのにロジックがあるPureDoc

ちなみに、PureDocはRuby DSLであるため、

3.times do |i|
  p { "Hello!" }
end

なんてことができ、この結果

<p>Hello!</p>
<p>Hello!</p>
<p>Hello!</p>

という出力が得られる。 全く一般向けではない仕様だ。

さらに言えばZshで書かれたPureDoc Zのほうは

repeat 3
do
  p Hello
done

とすれば同じような結果が得られる。 これを「読みやすい」と思う人はどうかしていると思う。 PureDocは「書きやすい」ようにはしているが、「読みやすい」ようにはしていない。

PureDocはほぼすべてのテキスト系HTMLタグを使用することができ、かつオプションも指定できる。 さらにnoteなども備えていて、「HTML以上」であることが前提だ。 実のところ「ロジックで書ける」のも「HTML以上」の一部であり、「仕様」だったりする。

PureDocはinstance_evalを使ってRubyコードとして評価しているし、PureDoc Zに至ってはドキュメント中でライブラリをincludeすることでDSL的に使うための語彙がshell functionとして追加されるだけのものだ。

「メタフォーマット」としての価値

WikiなどはHTMLを簡単に書くためのものなのだから、特に変換先としての意味はないのだが、 メタフォーマットとしての価値は、「一度書けば表示向けにも印刷向けにもできる」ということにある。 基本的にはHTMLとPDFにできれば良いだろうという考え方が成り立つのだが、例えば「自分はコマンドドリブンなマークアップで書けば良いけれど、みんなはWordだからDocxで吐きたい」というケースはあるものであり、多様なフォーマットでの出力というのは割と重要な価値である。

実は、私はMarkdown/Pandocと出会うまでずっとPODで書いていた。 PODの多彩な変換形式に助けられてきたからだ。

だが、PODは純粋に汎用というわけではなかったし、 「DOCよりも多くのフォーマットに変換でき、より汎用性と表現力がある形式」を求めていた。

Pandocは極めて強力な変換ツールであり、入力形式はMarkdownに限ったわけではないのだが、 一応、Markdownを軸にしている…のだと思う。

そのため、PandocをMarkdownツールだと考えれば、Markdownは圧倒的なアドバンテージがある。 (もちろん、PandocがReStructuredTextをMarkdownと同等に変換できるのであれば、特にMarkdownにアドバンテージがあるわけではなくなる)

実はPandocは多彩なフォーマットが仇となり、適切に変換されないケースがそこそこある。 さすがに完璧に…というのは相当難しいのだろう。

Markdownにはもうひとつ、様々な処理系があるということがある。 KramdownはRubyで書かれており、Rubyプログラムにおいて使いやすい処理系だ。 KramdownもLaTeXへの出力に対応しており、割と使いやすい。

方言の話

Kramdownがinput formatとして

  • Kramdown
  • Markdown
  • GitHub Flavored Markdown

の3つを挙げていることに既に闇を感じるが、 実は処理系それぞれがMarkdownを拡張していて、一口にMarkdownといっても書き方に互換性がない、という問題が存在する。 冒頭で言及されていたのはそういうことだろう。

だが、それほど問題があるとは思わない。

まず、「多彩な処理系があるマークアップ言語」自体珍しく、Re:Viewなんてほとんどないし、ReStructuredTextだってそう多くはない。 なので、「特定の処理系向けに書かれたMarkdown」がそんなに問題なのか、という疑問がまずある。

さらに、MarkdownはGFMとPHP Markdown Extraが普及していて、これらの記法はだいたい通用する。 だから、純粋なMarkdownでは表現力はかなり限られるが、これらの記法を取り込めばかなりの表現力を持つし、これらの記法を取り込んでなお複数の処理系で取り扱うことができるのだ。

拡張記法のせいで無駄に「意味」をとられるのが気に入らないのであれば、 KramdownのようにMarkdown Standardに従った処理をできる処理系を使えば良い。

Markdownが良いという話

Markdownの記法が完璧だとは思わないが、少なくともPandoc Markdownは表現力にほとんど不満はないし、Pandocの変換フォーマットにも不足はない。

Markdownという記法について「及第点」で、変換という実用面に不満がないのだから、 それで文句を言うべきことなどない。

だから、別に「Markdownじゃ足りない」というのであれば拡張すれば良いし、それが許されてもいる。 拡張されたMarkdownを使ってはいけないということはないだろうし、素のMarkdownと拡張Markdownは別物だと考えれば使い分けだって成立する。

あるいは、「簡素さ優先のMarkdown」と「高機能なGFM」のように考えればよいではないか、ということだ。

無理に「Markdownとはこうだ」ということを押し付け合う必要もないし、Markdownはいままでの苦痛を緩和してくれる、「良いもの」なのだ。

そうでないというのならば、試しに大量のドキュメントをDocBookで書いてみればいい。 DocBookは確かに技術文書を書くのに適しているが、相当に苦痛だろう。 書く量が膨大で、しかもテキストはほとんどエレメントに埋もれてしまう。

別にHTMLで書いても構わない。 Markdownよりも優れていると思うのであれば。

Markdownが好きで、しかし機能が足りないから拡張しようという気持ちはなにも間違っていないし、それはまた別のものだと考えればごく自然なものなのだ。 方言があってはいけないというものではないし、が方言があったところでMarkdownは十分に共通性があると思う。

このブログもMarkdownで書いて、Kramdownで変換している。

ツールや記法でいがみあうことなどなにもない。 誰かに何かを強制する必要などないのだ。 あなたが幸せになるように使えばいい。