Markdownもはじめよう
- 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にする
- 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* そもそもインラインとして認識されるか それとも「*」と認識されるかどうかから して処理系依存
- 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は関わっていない
- 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年越しの動き
- 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にしたい！
- 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
- 57. $ pandoc -f markdown -t rst --filter emo_pandoc emoji.md
- 58. まとめ • Markdownはいろいろあって大変 • 事前に「どのMarkdown」を決めないと交換 できなくなる危険性 • プロジェクトリーダーはしっかりするべき • 続けるか、後進に任せるか、終わらせるか • Pandocはいろいろすごい • UCBやばい