SphinxCon JP 2014での発表資料です。

1. Markdownも
はじめよう
2014/10/26 SphinxCon JP 2014
株式会社達人出版会／一般社団法人日本Rubyの会
高橋征義 @takahashim

2. 自己紹介
• 高橋征義
• Re:VIEWコミッタ
• 株式会社達人出版会代表取締役
• ITエンジニア向け電子書籍の制作・販売
• 一般社団法人日本Rubyの会代表理事
• Sphinx歴はたしなみ程度
• 原稿書くのに使えないかなあ…と調べてみたくらい

4. 本日のお題

5. Markdown

6. 2日前に発売された
WEB+DB PRESS Vol.83に
「もっと知りたい!
Markdown」
という原稿を書きました

7. 本日のお題
•Markdownの概要
•Markdownの方言問題
•Markdown→reST変換

8. 本日のお題
•Markdownの概要
•Markdownの方言問題
•MarkdownをreSTにする

9. Markdownを
使ったことのない方？

10. Markdownとは
• John Gruber氏が2004年に開発
• 「Daring Fireball」というブログで有名
• Aaron Swartz氏が協力
• 「読みやすく書きやすい」＋(X)HTMLに変換で
きる
• 開発は10年近く絶賛停止中

11. 記法と処理系の名前
記法処理系
reSTの
場合reST Docutils
MDの
場合Markdown Markdown
(Markdown.pl)

12. MarkdownはreSTを参考にしている
•1991年: setext (Ian Feldman)
• 1993年: HTML 1.0
• 1995年: HTML 2.0
• 1998年: XML 1.0 / HTML 4.01
• 2001年: XHTML 1.1
•2002年: reStructuredText
•2004年: Markdown
※StructuredTextはいつか分からず…

13. 機能面での比較
• (オリジナルの)Markdownに比べると、
reStructuredTextの方が圧倒的にリッチ
• 後発なのになぜ？

14. 目的の違い
記法主要な（特徴的な）目的
reST プログラムのドキュメント
（docstrings等）
Markdown Webコンテンツ
（ブログ記事等）
Re:VIEW 紙の書籍
（コンピュータ書等）
広く使われる記法には「強いポリシー」がある
（ことが多い。cf. “Opinionated Software”）

15. 【宣伝】Re:VIEWのご紹介
• 一言で言うと「Sphinxみたいなやつ」
• 青木峰郎氏が『Rubyソースコード完全解説』などの書
籍執筆時、自分用に開発し、後にOSS化されたもの（現
在は武藤健志氏がメインのメンテナ）
• 知名度では圧倒的にSphinxの方が高いが、HTML、
EPUB、LaTeXの他にも、InDesign(IDGXML)への変換
が可能なため、日本での商業出版の利用例は多い
• 達人出版会では基本的にRe:VIEWで制作している
• https://github.com/kmuto/review

16. Markdownの長所
• 読みやすい & 書きやすい
• 「プレーンテキストのメール」
• 複雑で読みづらい記法を使わせない
• HTMLが素で書ける
• いざとなればだいたい何でも書ける
• ツールが充実
• 数は力

17. Markdownの欠点
• マークアップの制限がきつい
• directiveのような（あると便利でも）文書と
して読みづらい記法が許されない
• HTMLに頼ると収拾がつかなくなりがち
• もうHTMLで書いた方が早いのでは的な
• 作者に保守発展させる気がなさそう
• 独自拡張の横行→方言問題に

18. 本日のお題
•Markdownの概要
•Markdownの方言問題
•MarkdownをreSTにする

19. Markdownの処理系
• 山ほどある
• 一言語に複数あるのが当たり前
• Rubyの場合、kramdown、RedCarpet、
RDiscount、Maruku、Blueclothなど
• 当然のように全部挙動が違う

20. Markdownの方言
• 処理系の違い（開発言語の違い）
•記法の解釈の違い （独自解釈）
•記法の構文の違い（独自拡張）

21. 記法の解釈の違い
• 箇条書きの入れ子問題
• 強調の入れ子問題
• 大文字DIV問題
• リスト中のコメントをどうするか問題
• リストと後続行のインデント問題
• 改行、空行の扱い
• その他もろもろ

22. 箇条書きの入れ子
*foo
*bar
*buz
基本は4インデントだが、それ以外の
インデントの場合が未規定のため、
どうなるかは処理系によってまちまち。

23. 強調の入れ子
*a **b *a **b** a* b** a*
そもそもインラインとして認識されるか
それとも「*」と認識されるかどうかから
して処理系依存

24. http://johnmacfarlane.net/babelmark2/?text=*a+**b+*a+**b**+a*+b**+a*

25. 大文字DIVの挙動
<DIV>
hi
</DIV>
Markdown.plやPHP Markdown Extra
ではなぜか<p><div>hi</div></p>
となる。Pandoc、RedCarpet、Python-
Markdownでは<div>hi</div>

26. 結局何が問題なのか
• 処理系が乱立
• 正しい仕様がない
• （↑この辺まではよくある話、まあ仕方ない）
• 正しい仕様を決めようとしない
• そもそものオリジナルの挙動が微妙なのに開発
が止まっており、変更されない
• 誰かに引き継いだりもしない

27. 記法の構文の違い
• テーブル記法
• コードブロック記法
• 脚注記法
• 絵文字
• チェックリスト
• この辺はgithub方言かも
詳しい記法の話は省略します
(Markdownのイベントというわけでもないので…)

28. jgm
• John MacFarlane
• Pandoc、peg-markdown、
Babelmark2の作者
• http://johnmacfarlane.net/
本職はUCBの哲学科の教授（専門は言語哲学や
数理論理学）、というか学科長？らしい
• 哲学の先生がHaskellもCもJSも書くUCBやばい
• CommonMarkの中心人物の一人

29. Pandoc
• 汎用文書変換器
• 当然のようにreSTにも対応
• Markdownには特にこだわりが
• 多様なオプション類
• 詳しくは後ほど
• http://johnmacfarlane.net/pandoc/

30. peg-markdown
• Cで書かれたMarkdownパーサ
• 構文はPEGで記述されている
• jgmなりの「形式的仕様」
• https://github.com/jgm/peg-markdown

31. Babelmark 2
• 様々なMarkdown実装の違いを一覧する
• Markdown実装はWebサービスAPIになってい
て、Ajaxで各サーバから変換結果を取得して表
示する
• http://johnmacfarlane.net/babelmark2/

32. Pandocでのオプション
• Pandocで指定できるMarkdownは4種類ある
• markdown (Pandoc独自)
• markdown_strict (オリジナルに限定)
• markdown_phpextra (PHP Markdown
Extra互換)
• markdown_github (GitHub互換)
• さらに細かい指定も可能

33. Pandocオプション例1
• hard_line_breaks: 改行を<br/>にする
• ignore_line_breaks: 改行を完全に無視する
（空白にもせず連結する、東アジア向け？）
• autolink_bare_uris: URLをリンクにする
• mmd_header_identifiers: MultiMarkdown
互換のヘッダID記法を有効にする

34. Pandocオプション例2
• yaml_metadata_block: YAMLで文書冒頭に
メタデータが書ける
• all_symbols_escapable: あらゆる文字がで
エスケープできる（標準は限られた記号のみ）
• intraword_underscores: 単語内の「_」を強
調記法と解釈しないようにする
• markdown_in_html_blocks: HTMLブロック
内のMarkdown記法を有効にする
• footnotes: 脚注を有効にする

35. Pandocオプション例3
• blank_before_header: #で始まる見出し行の直前が
空行でなければ見出しにしない
• header_attributes: 見出しに属性を付けられる
• auto_identifiers: 見出しに自動でidを振る
• fenced_code_blocks: GitHubとかのコードブロック
記法を有効にする
• line_blocks: reSTの「|」の引用記法を有効にする
• fancy_lists: 英字やローマ数字を連番リストにできる
• startnum: 連番リストの最初の数値を変えられる
• definition_lists: 定義リストを有効にする

36. Pandocのテーブル記法
• これまた4種類ある
• シンプルテーブル simple_tables
• マルチラインテーブル multiline_tables
• グリッドテーブル grid_tables
• パイプテーブル pipe_tables
• table_captions: テーブルのキャプションを有効

37. Pandocオプション例
• 要するに記法の有無・解釈の違いに対応するた
めにオプションだらけになる
• Markdown文書を正しく解釈してもらうにはオ
プションも交換する必要がある
• つらい世界…

38. CommonMark
• 2014年8月に勃発
• Markdown Discuss MLからの流れかも
• Markdownの標準化運動
• 当初Standard Markdownという名前だった
• Jeff Atwoodとjgmが中心（？）
• 名前が出てるのは2人以外にも数名いる
• John Gruberは関わっていない

39. http://commonmark.org/

40. Coding Horror
• Jeff Atwoodのブログ
• 2009/12/29: Responsible Open Source
Code Parenting
• “Which leads me to the biggest problem
with Markdown: John Gruber.”
• 2012/10/25: The Future of Markdown
• 標準化の提案
• 5年越しの動き

41. http://blog.codinghorror.com/responsible-open-source-code-parenting/

42. http://blog.codinghorror.com/the-future-of-markdown/

43. CommonMarkの仕様
• 仕様の厳密化
• HTMLへのマッピングとして規定
• オリジナルとは微妙な違いはある
• オリジナルから拡張は基本しない
• 今後の課題
• でもいくつかこっそり追加してある
• PandocのMarkdownぽい
• 拡張はなし
• markdown_strictでもない

44. CommonMarkの今後
• 仕様案は10/24にv0.4が公開
• 議論等は掲示板とgithubで進んでいる
• 細かい提案は出てるがどうまとめるのか不明
• 少なくともGitHubやStackExchangeの挙動
は変更されていない模様
• ロードマップ非公開、リリース予定時期も不明
• とにかく今後に期待、というところ

45. 本日のお題
•Markdownの概要
•Markdownの方言問題
•MarkdownをreSTにする

46. PandocでMD→reST
• Pandocを使えばMarkdownもreSTにもできる
• 「Markdownで書いてたんだけど…」
「Markdownしか知らないんだけど…」
みたいなことを言われても、Sphinxに取り込め
る（はず）

47. Pandocをはじめよう
$ pandoc -f markdown_github
-t rst
foo.md

48. Pandocをさらに拡張
• Markdown＋謎の独自記法で書かれた文書を
reSTにしたい！

49. http://qiita.com/r7kamura/items/faf2189a32e1eaa1a5d4

51. HTML::Pipelineとか
• MarkdownからいったんHTMLを変換
• その変換結果のHTMLに対して独自記法の変換
を行う
• HTMLじゃないと使えない……
• TeXとかTeXとか
• そこでPandocですよ！

52. Pandocフィルタ
• Pandocは変換結果のASTをJSONに吐き出せる
• Markdown → AST → JSON
• さらにJSONを入力にして変換することもでき
る
• JSON → AST → (reST等)
• JSONを加工するフィルタを書けば拡張できる

53. Pandocフィルタ
• 例: 絵文字フィルタ (GitHub風)
• とりあえずUnicode絵文字に変換してみる
• RubyにはEmotというライブラリがあるので
それを使うことに（Python力が低くてすみま
せん…）

54. $ pandoc -f markdown
-t json emoji.md > emoji.json

56. https://github.com/takahashim/emo_pandoc

57. $ pandoc -f markdown
-t rst
--filter emo_pandoc emoji.md

58. まとめ
• Markdownはいろいろあって大変
• 事前に「どのMarkdown」を決めないと交換
できなくなる危険性
• プロジェクトリーダーはしっかりするべき
• 続けるか、後進に任せるか、終わらせるか
• Pandocはいろいろすごい
• UCBやばい

59. ついでに（勝手に）宣伝
http://texconf14.tumblr.com/