Markdownもはじめよう

23,656 views

Published on

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

Published in: Technology
0 Comments
70 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
23,656
On SlideShare
0
From Embeds
0
Number of Embeds
7,426
Actions
Shares
0
Downloads
58
Comments
0
Likes
70
Embeds 0
No embeds

No notes for slide

Markdownもはじめよう

  1. 1. Markdownも はじめよう 2014/10/26 SphinxCon JP 2014 株式会社達人出版会/一般社団法人日本Rubyの会 高橋征義 @takahashim
  2. 2. 自己紹介 • 高橋征義 • Re:VIEWコミッタ • 株式会社達人出版会代表取締役 • ITエンジニア向け電子書籍の制作・販売 • 一般社団法人日本Rubyの会代表理事 • Sphinx歴はたしなみ程度 • 原稿書くのに使えないかなあ…と調べてみたくらい
  3. 3. 本日のお題
  4. 4. Markdown
  5. 5. 2日前に発売された WEB+DB PRESS Vol.83に 「もっと知りたい! Markdown」 という原稿を書きました
  6. 6. 本日のお題 •Markdownの概要 •Markdownの方言問題 •Markdown→reST変換
  7. 7. 本日のお題 •Markdownの概要 •Markdownの方言問題 •MarkdownをreSTにする
  8. 8. Markdownを 使ったことのない方?
  9. 9. Markdownとは • John Gruber氏が2004年に開発 • 「Daring Fireball」というブログで有名 • Aaron Swartz氏が協力 • 「読みやすく書きやすい」+(X)HTMLに変換で きる • 開発は10年近く絶賛停止中
  10. 10. 記法と処理系の名前 記法処理系 reSTの 場合reST Docutils MDの 場合Markdown Markdown (Markdown.pl)
  11. 11. 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はいつか分からず…
  12. 12. 機能面での比較 • (オリジナルの)Markdownに比べると、 reStructuredTextの方が圧倒的にリッチ • 後発なのになぜ?
  13. 13. 目的の違い 記法主要な(特徴的な)目的 reST プログラムのドキュメント (docstrings等) Markdown Webコンテンツ (ブログ記事等) Re:VIEW 紙の書籍 (コンピュータ書等) 広く使われる記法には「強いポリシー」がある (ことが多い。cf. “Opinionated Software”)
  14. 14. 【宣伝】Re:VIEWのご紹介 • 一言で言うと「Sphinxみたいなやつ」 • 青木峰郎氏が『Rubyソースコード完全解説』などの書 籍執筆時、自分用に開発し、後にOSS化されたもの(現 在は武藤健志氏がメインのメンテナ) • 知名度では圧倒的にSphinxの方が高いが、HTML、 EPUB、LaTeXの他にも、InDesign(IDGXML)への変換 が可能なため、日本での商業出版の利用例は多い • 達人出版会では基本的にRe:VIEWで制作している • https://github.com/kmuto/review
  15. 15. Markdownの長所 • 読みやすい & 書きやすい • 「プレーンテキストのメール」 • 複雑で読みづらい記法を使わせない • HTMLが素で書ける • いざとなればだいたい何でも書ける • ツールが充実 • 数は力
  16. 16. Markdownの欠点 • マークアップの制限がきつい • directiveのような(あると便利でも)文書と して読みづらい記法が許されない • HTMLに頼ると収拾がつかなくなりがち • もうHTMLで書いた方が早いのでは的な • 作者に保守発展させる気がなさそう • 独自拡張の横行→方言問題に
  17. 17. 本日のお題 •Markdownの概要 •Markdownの方言問題 •MarkdownをreSTにする
  18. 18. Markdownの処理系 • 山ほどある • 一言語に複数あるのが当たり前 • Rubyの場合、kramdown、RedCarpet、 RDiscount、Maruku、Blueclothなど • 当然のように全部挙動が違う
  19. 19. Markdownの方言 • 処理系の違い(開発言語の違い) •記法の解釈の違い (独自解釈) •記法の構文の違い(独自拡張)
  20. 20. 記法の解釈の違い • 箇条書きの入れ子問題 • 強調の入れ子問題 • 大文字DIV問題 • リスト中のコメントをどうするか問題 • リストと後続行のインデント問題 • 改行、空行の扱い • その他もろもろ
  21. 21. 箇条書きの入れ子 *foo *bar *buz 基本は4インデントだが、それ以外の インデントの場合が未規定のため、 どうなるかは処理系によってまちまち。
  22. 22. 強調の入れ子 *a **b *a **b** a* b** a* そもそもインラインとして認識されるか それとも「*」と認識されるかどうかから して処理系依存
  23. 23. http://johnmacfarlane.net/babelmark2/?text=*a+**b+*a+**b**+a*+b**+a*
  24. 24. 大文字DIVの挙動 <DIV> hi </DIV> Markdown.plやPHP Markdown Extra ではなぜか<p><div>hi</div></p> となる。Pandoc、RedCarpet、Python- Markdownでは<div>hi</div>
  25. 25. 結局何が問題なのか • 処理系が乱立 • 正しい仕様がない • (↑この辺まではよくある話、まあ仕方ない) • 正しい仕様を決めようとしない • そもそものオリジナルの挙動が微妙なのに開発 が止まっており、変更されない • 誰かに引き継いだりもしない
  26. 26. 記法の構文の違い • テーブル記法 • コードブロック記法 • 脚注記法 • 絵文字 • チェックリスト • この辺はgithub方言かも 詳しい記法の話は省略します (Markdownのイベントというわけでもないので…)
  27. 27. jgm • John MacFarlane • Pandoc、peg-markdown、 Babelmark2の作者 • http://johnmacfarlane.net/ 本職はUCBの哲学科の教授(専門は言語哲学や 数理論理学)、というか学科長?らしい • 哲学の先生がHaskellもCもJSも書くUCBやばい • CommonMarkの中心人物の一人
  28. 28. Pandoc • 汎用文書変換器 • 当然のようにreSTにも対応 • Markdownには特にこだわりが • 多様なオプション類 • 詳しくは後ほど • http://johnmacfarlane.net/pandoc/
  29. 29. peg-markdown • Cで書かれたMarkdownパーサ • 構文はPEGで記述されている • jgmなりの「形式的仕様」 • https://github.com/jgm/peg-markdown
  30. 30. Babelmark 2 • 様々なMarkdown実装の違いを一覧する • Markdown実装はWebサービスAPIになってい て、Ajaxで各サーバから変換結果を取得して表 示する • http://johnmacfarlane.net/babelmark2/
  31. 31. Pandocでのオプション • Pandocで指定できるMarkdownは4種類ある • markdown (Pandoc独自) • markdown_strict (オリジナルに限定) • markdown_phpextra (PHP Markdown Extra互換) • markdown_github (GitHub互換) • さらに細かい指定も可能
  32. 32. Pandocオプション例1 • hard_line_breaks: 改行を<br/>にする • ignore_line_breaks: 改行を完全に無視する (空白にもせず連結する、東アジア向け?) • autolink_bare_uris: URLをリンクにする • mmd_header_identifiers: MultiMarkdown 互換のヘッダID記法を有効にする
  33. 33. Pandocオプション例2 • yaml_metadata_block: YAMLで文書冒頭に メタデータが書ける • all_symbols_escapable: あらゆる文字がで エスケープできる(標準は限られた記号のみ) • intraword_underscores: 単語内の「_」を強 調記法と解釈しないようにする • markdown_in_html_blocks: HTMLブロック 内のMarkdown記法を有効にする • footnotes: 脚注を有効にする
  34. 34. Pandocオプション例3 • blank_before_header: #で始まる見出し行の直前が 空行でなければ見出しにしない • header_attributes: 見出しに属性を付けられる • auto_identifiers: 見出しに自動でidを振る • fenced_code_blocks: GitHubとかのコードブロック 記法を有効にする • line_blocks: reSTの「|」の引用記法を有効にする • fancy_lists: 英字やローマ数字を連番リストにできる • startnum: 連番リストの最初の数値を変えられる • definition_lists: 定義リストを有効にする
  35. 35. Pandocのテーブル記法 • これまた4種類ある • シンプルテーブル simple_tables • マルチラインテーブル multiline_tables • グリッドテーブル grid_tables • パイプテーブル pipe_tables • table_captions: テーブルのキャプションを有効
  36. 36. Pandocオプション例 • 要するに記法の有無・解釈の違いに対応するた めにオプションだらけになる • Markdown文書を正しく解釈してもらうにはオ プションも交換する必要がある • つらい世界…
  37. 37. CommonMark • 2014年8月に勃発 • Markdown Discuss MLからの流れかも • Markdownの標準化運動 • 当初Standard Markdownという名前だった • Jeff Atwoodとjgmが中心(?) • 名前が出てるのは2人以外にも数名いる • John Gruberは関わっていない
  38. 38. http://commonmark.org/
  39. 39. 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年越しの動き
  40. 40. http://blog.codinghorror.com/responsible-open-source-code-parenting/
  41. 41. http://blog.codinghorror.com/the-future-of-markdown/
  42. 42. CommonMarkの仕様 • 仕様の厳密化 • HTMLへのマッピングとして規定 • オリジナルとは微妙な違いはある • オリジナルから拡張は基本しない • 今後の課題 • でもいくつかこっそり追加してある • PandocのMarkdownぽい • 拡張はなし • markdown_strictでもない
  43. 43. CommonMarkの今後 • 仕様案は10/24にv0.4が公開 • 議論等は掲示板とgithubで進んでいる • 細かい提案は出てるがどうまとめるのか不明 • 少なくともGitHubやStackExchangeの挙動 は変更されていない模様 • ロードマップ非公開、リリース予定時期も不明 • とにかく今後に期待、というところ
  44. 44. 本日のお題 •Markdownの概要 •Markdownの方言問題 •MarkdownをreSTにする
  45. 45. PandocでMD→reST • Pandocを使えばMarkdownもreSTにもできる • 「Markdownで書いてたんだけど…」 「Markdownしか知らないんだけど…」 みたいなことを言われても、Sphinxに取り込め る(はず)
  46. 46. Pandocをはじめよう $ pandoc -f markdown_github -t rst foo.md
  47. 47. Pandocをさらに拡張 • Markdown+謎の独自記法で書かれた文書を reSTにしたい!
  48. 48. http://qiita.com/r7kamura/items/faf2189a32e1eaa1a5d4
  49. 49. HTML::Pipelineとか • MarkdownからいったんHTMLを変換 • その変換結果のHTMLに対して独自記法の変換 を行う • HTMLじゃないと使えない…… • TeXとかTeXとか • そこでPandocですよ!
  50. 50. Pandocフィルタ • Pandocは変換結果のASTをJSONに吐き出せる • Markdown → AST → JSON • さらにJSONを入力にして変換することもでき る • JSON → AST → (reST等) • JSONを加工するフィルタを書けば拡張できる
  51. 51. Pandocフィルタ • 例: 絵文字フィルタ (GitHub風) • とりあえずUnicode絵文字に変換してみる • RubyにはEmotというライブラリがあるので それを使うことに(Python力が低くてすみま せん…)
  52. 52. $ pandoc -f markdown -t json emoji.md > emoji.json
  53. 53. https://github.com/takahashim/emo_pandoc
  54. 54. $ pandoc -f markdown -t rst --filter emo_pandoc emoji.md
  55. 55. まとめ • Markdownはいろいろあって大変 • 事前に「どのMarkdown」を決めないと交換 できなくなる危険性 • プロジェクトリーダーはしっかりするべき • 続けるか、後進に任せるか、終わらせるか • Pandocはいろいろすごい • UCBやばい
  56. 56. ついでに(勝手に)宣伝 http://texconf14.tumblr.com/

×