Upload
takeshi-komiya
View
1.175
Download
0
Embed Size (px)
DESCRIPTION
マークアップ言語の拡張 メリットとデメリット #hankumi
Citation preview
マークアップ言語の拡張
-メリットとデメリット-
小宮健 (Takeshi KOMIYA) @tk0miya
#hankumi
Who am I ?
仕事
(株)タイムインターメディア所属
Sphinx コミッター (2014/11〜)
blockdiag開発者
Sphinx 拡張開発数世界1位 (自分調べ)
参加コミュニティ
Sphinx-users.jp
sendagaya.rb
Twitter: @tk0miya
Who am I ?
blockdiagというツールを作ってます
テキスト(DSL like .dot)から画像を生成します{トップページ -> ログイン -> マイページ;トップページ -> 商品一覧 -> 商品詳細;
}
http://www.flickr.com/photos/huskyte/7512877940/in/photostream/
版管理の話も
組版の話もありません
今日の発表について
Sphinx とは
reStructuredTextでマークアップされた原稿をHTML/LaTeX/EPUBなどに変換するツール
Python製
Python リファレンス、書籍などで使われている
reStructured Text とは
読みやすさに重きをおいたマークアップ言語
略称は reST
マークアップの拡張を考慮している
処理系として docutilsがある
デザイン/レイアウトのマークアップは苦手
reStructured Text とは
読みやすさに重きをおいたマークアップ言語
コンセプトは easy-to-read, WYSIWYG========タイトル========
セクション 1============
この **単語** は強調されます。
セクション 2============
* 箇条書きです* 箇条書きです
reSTを拡張する (1)
インラインマークアップには role を用いる
例: Wikipedia へのリンクを作る
:role_name:`contents`
:wikipedia:`reStructuredText`
reSTを拡張する (2)
ブロック要素には directive を用いる
.. directive_name:: 引数:オプション1: 値:オプション2: 値
contents
reSTを拡張する (2)
例: CSV でテーブルを作る
.. csv-table:: 見出し:header-rows: 1
"ユーザ名","住所","メールアドレス""taro","Tokyo","[email protected]""jiro","Kanagawa","[email protected]""saburo","Saitama","[email protected]"
Sphinx と reSTの関係
reSTの処理系は docutils
(基本的に)複数ファイルを扱えない
マークアップを拡張する API を持っている
docutilsをラップするプログラムを書く必要がある
Sphinx は docutilsをラップしたもの
プロジェクト制を採用
複数ファイルに対応
Sphinx 独自の directive, role
Sphinx と reSTの関係
docutils Sphinx
マークアップ言語 reStructuredTextreStructuredText
(独自拡張)
文書の規模 1ファイル 複数ファイル
Sphinx が提供するもの
複数ファイルのための仕組み目次(TOC)
クロスリファレンス
HTML テーマ
言語ドメイン (関数、クラスなどを表現する)
文書の国際化(I18N)
autodoc (Javadoc like の仕組み)
拡張の仕組み (フレームワーク)
ドキュメンテーション用統合環境パッケージ
Sphinx 拡張
Sphinx は拡張の仕組みを提供している
autodoc: ソースコードなどからドキュメントを生成
builders: 出力フォーマットを追加
domains: 言語ドメインを増やす
directive/role: マークアップを拡張する
HTML テーマ: HTML の見栄えを変える
Survey of Sphinx extensions
200 を超える拡張が存在する
(HTML テーマを除く)
主な拡張
sphinxcontrib-exceltable
Excel ファイルを表として取り込む
画像系
画像ファイルを取り込む
PowerPoint, gnuplot, astah, cacoo, Libre Office, visio
マークアップから図を生成する
UML(PlantUML)、ブロック図(blockdiag)、グラフ
主な拡張
multimedia
動画 (Youtube, Flash), スライド (Slideshare)
その他 (googlemaps, gist, twitter)
roles
リンク(wikipedia, PyPI), テキスト装飾、メタデータ
autodocs
Doxygen連携、ソースコード解析
DBスキーマ解析
拡張によって得られるもの
テキストが苦手な部分を補うことができる
図、表は扱いやすいツールで作る
マルチメディア情報
マークアップの表現力を上げる
セマンティックに書く
シンプルに書く
自動抽出
簡潔な記述ができる
拡張のデメリット
セットアップがちょっと面倒
拡張を調べる/覚えるのが大変
1ソースマルチユースに対応していない拡張もある
HTML ではうまく動くが…
PDF や EPUB に変換できない
reSTの方言化
拡張を調べる/覚えるのが大変
画像に関する拡張は30以上
gnuplot, blockdiag, astah, cacoo, libreoffice, PlantUML, TikZ, Visio, PPT などなど
それぞれ使い方やオプションが異なる
対応していないオプションもある
キャプションを付けられないとか
reSTの方言化
マークアップが追加され、標準と異なるものになる
reStructuredText
SphinxSphinx
+拡張
reSTの方言化
他の処理系で表示できない
ex. github, bitbucket, PyPI
README.rstが〜〜でちゃんと表示されない…
Sphinx で reSTを覚えた人にありがち
Sphinx で作った文書は Sphinx でしか処理できない
ゴールが違うので問題無い??
拡張性 ≒方言化 ?
reSTの方言化
似たような話、どこかで聞いたような…
markdown ですね
Github Flavor, PHP Extra, Pandoc, CommonMark
Sphinx's reST = Sphinx Flavored reST
reSTの方言化
reSTは拡張性を提供している
Sphinx は拡張方法を提供している
markdown は処理系ごとに文法を拡張
TeXはすべてがマクロでできている
どのマークアップも少なからず拡張している
この道は先人が通っているはず…!?
reSTの方言化
先人曰く
拡張性の功罪
メリット
便利
表現力アップ
デメリット
複雑度が上がる
他の人に扱いづらくなる
他の処理系で扱えない
利便性と方言化はトレードオフ
まとめ
大量の拡張を読んだ経験をまとめました
言語の拡張は用法用量を守って正しくお使いください
使いすぎにはご注意を…
宣伝: ドキュメント話をしませんか
いろんな垣根を超えて辛いことをシェアしたい
プログラミング言語
マークアップ言語
処理系/ツール
題材 (書籍、雑誌、同人誌、翻訳、リファレンス)
まずは雑談しませんか
懇親会(あれば)で雑談しましょう
あと、この会の2回目をやりましょう
ドキュメントの話をしよう
例:Sphinx+翻訳 Hack-a-thon (12/20, 毎月開催)