Markdownもはじめよう
Upcoming SlideShare
Loading in...5
×
 

Like this? Share it with your network

Share

Markdownもはじめよう

on

  • 9 views

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

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

Statistics

Views

Total Views
9
Views on SlideShare
9
Embed Views
0

Actions

Likes
1
Downloads
0
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Markdownもはじめよう Presentation Transcript

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