マークアップ言語の拡張 メリットとデメリット #hankumi

1. マークアップ言語の拡張
-メリットとデメリット-
小宮健(Takeshi KOMIYA) @tk0miya
#hankumi

2. Who am I ?
 仕事
 (株)タイムインターメディア所属
 Sphinx コミッター(2014/11〜)
 blockdiag 開発者
 Sphinx 拡張開発数世界1位(自分調べ)
 参加コミュニティ
 Sphinx-users.jp
 sendagaya.rb
Twitter: @tk0miya

3. Who am I ?
 blockdiag というツールを作ってます
 テキスト(DSL like .dot)から画像を生成し
ま{ す
トップページ-> ログイン-> マイペー
ジ;
トップページ-> 商品一覧-> 商品詳細;
}

4. http://www.flickr.com/photos/huskyte/7512877940/in/photostream/

5. 今日の発表について
版管理の話も
組版の話もありません

6. Sphinx とは
 reStructuredTextでマークアップされた原
稿をHTML/LaTeX/EPUBなどに変換する
ツール
 Python製
 Python リファレンス、書籍などで使われ
ている

7. reStructured Text とは
 読みやすさに重きをおいたマークアップ言
語
 略称はreST
 マークアップの拡張を考慮している
 処理系としてdocutils がある
 デザイン/レイアウトのマークアップは苦
手

8. reStructured Text とは
 読みやすさに重きをおいたマークアップ言
語
コ==ン===セ==プ= トはeasy-to-read, WYSIWYG
タイトル
========
セクション1
============
この**単語** は強調されます。
セクション2
============
* 箇条書きです
* 箇条書きです

9. reST を拡張する(1)
 インラインマークアップにはrole を用い
る
:role_name:`contents`
 例: Wikipedia へのリンクを作る
:wikipedia:`reStructuredText`

10. reST を拡張する(2)
 ブロック要素にはdirective を用いる
.. directive_name:: 引数
:オプション1: 値
:オプション2: 値
contents

11. reST を拡張する(2)
 例: CSV でテーブルを作る
.. csv-table:: 見出し
:header-rows: 1
"ユーザ名","住所","メールアドレス"
"taro","Tokyo","taro@gmail.com"
"jiro","Kanagawa","jiro@gmail.com"
"saburo","Saitama","saburo@gmail.com"

12. Sphinx とreST の関係
 reST の処理系はdocutils
 (基本的に)複数ファイルを扱えない
 マークアップを拡張するAPI を持っている
 docutils をラップするプログラムを書く必要がある
 Sphinx はdocutils をラップしたもの
 プロジェクト制を採用
 複数ファイルに対応
 Sphinx 独自のdirective, role

13. Sphinx とreST の関係
docutils Sphinx
マークアップ言語reStructuredText
reStructuredText
(独自拡張)
文書の規模1ファイル複数ファイル

14. Sphinx が提供するもの
 複数ファイルのための仕組み
 目次(TOC)
 クロスリファレンス
 HTML テーマ
 言語ドメイン(関数、クラスなどを表現する)
 文書の国際化(I18N)
 autodoc (Javadoc like の仕組み)
 拡張の仕組み(フレームワーク)
 ドキュメンテーション用統合環境パッケージ

15. Sphinx 拡張
 Sphinx は拡張の仕組みを提供している
 autodoc: ソースコードなどからドキュメント
を生成
 builders: 出力フォーマットを追加
 domains: 言語ドメインを増やす
 directive/role: マークアップを拡張する
 HTML テーマ: HTML の見栄えを変える

16. Survey of Sphinx extensions
 200 を超える拡張が存在する
 (HTML テーマを除く)

17. 主な拡張
 sphinxcontrib-exceltable
 Excel ファイルを表として取り込む
 画像系
 画像ファイルを取り込む
 PowerPoint, gnuplot, astah, cacoo, Libre Office, visio
 マークアップから図を生成する
 UML(PlantUML)、ブロック図(blockdiag)、グラフ

18. 主な拡張
multimedia
 動画(Youtube, Flash), スライド(Slideshare)
 その他(googlemaps, gist, twitter)
 roles
 リンク(wikipedia, PyPI), テキスト装飾、メタ
データ
 autodocs
 Doxygen 連携、ソースコード解析
 DBスキーマ解析

19. 拡張によって得られるもの
 テキストが苦手な部分を補うことができる
 図、表は扱いやすいツールで作る
 マルチメディア情報
 マークアップの表現力を上げる
 セマンティックに書く
 シンプルに書く
 自動抽出
 簡潔な記述ができる

20. 拡張のデメリット
 セットアップがちょっと面倒
 拡張を調べる/覚えるのが大変
 1ソースマルチユースに対応していない拡
張もある
 HTML ではうまく動くが…
 PDF やEPUB に変換できない
 reST の方言化

21. 拡張を調べる/覚えるのが大変
 画像に関する拡張は30以上
 gnuplot, blockdiag, astah, cacoo, libreoffice,
PlantUML, TikZ, Visio, PPT などなど
 それぞれ使い方やオプションが異なる
 対応していないオプションもある
 キャプションを付けられないとか

22. reST の方言化
 マークアップが追加され、標準と異なるも
のになる
reStructured
Text
Sphinx
Sphinx
+
拡張

23. reST の方言化
 他の処理系で表示できない
 ex. github, bitbucket, PyPI
 README.rst が〜〜でちゃんと表示されない…
 Sphinx でreST を覚えた人にありがち
 Sphinx で作った文書はSphinx でしか処理
できない
 ゴールが違うので問題無い??
 拡張性≒ 方言化?

24. reST の方言化
 似たような話、どこかで聞いたような…
 markdown ですね
 Github Flavor, PHP Extra, Pandoc,
CommonMark
 Sphinx's reST = Sphinx Flavored reST

25. reST の方言化
 reST は拡張性を提供している
 Sphinx は拡張方法を提供している
 markdown は処理系ごとに文法を拡張
TeX はすべてがマクロでできている
 どのマークアップも少なからず拡張してい
る
 この道は先人が通っているはず…!?

26. reST の方言化
 先人曰く

27. 拡張性の功罪
 メリット
 便利
 表現力アップ
 デメリット
 複雑度が上がる
 他の人に扱いづらくなる
 他の処理系で扱えない
 利便性と方言化はトレードオフ

28. まとめ
 大量の拡張を読んだ経験をまとめました
 言語の拡張は用法用量を守って正しくお使
いください
 使いすぎにはご注意を…

29. 宣伝: ドキュメント話をしませんか
 いろんな垣根を超えて辛いことをシェアし
たい
 プログラミング言語
 マークアップ言語
 処理系/ツール
 題材(書籍、雑誌、同人誌、翻訳、リファレン
ス)
 まずは雑談しませんか
 懇親会(あれば)で雑談しましょう
 あと、この会の2回目をやりましょう

30. ドキュメントの話をしよう
 例：Sphinx+翻訳Hack-a-thon (12/20, 毎月開催)