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