Recommended
More Related Content
What's hot
What's hot (20)
Viewers also liked
Similar to Markdownもはじめよう
Similar to Markdownもはじめよう (20)
More from masayoshi takahashi
More from masayoshi takahashi (20)
Recently uploaded
Recently uploaded (7)
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やばい