惭补谤办诲辞飞苍もはじめよう
- 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の方言問題 ?惭补谤办诲辞飞苍→谤别厂罢変换
- 8. 本日のお题 ?Markdownの概要 ?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の方言問題 ?惭补谤办诲辞飞苍を谤别厂罢にする
- 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の方言問題 ?惭补谤办诲辞飞苍を谤别厂罢にする
- 46. PandocでMD→reST ? Pandocを使えばMarkdownもreSTにもできる ? 「Markdownで書いてたんだけど…」 「Markdownしか知らないんだけど…」 みたいなことを言われても、Sphinxに取り込め る（はず）
- 47. Pandocをはじめよう $ pandoc -f markdown_github -t rst foo.md
- 48. Pandocをさらに拡張 ? Markdown＋謎の独自記法で書かれた文書を 谤别厂罢にしたい！
- 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やばい