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

マークアップ言語の拡張

-メリットとデメリット-

小宮健 (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","taro@gmail.com""jiro","Kanagawa","jiro@gmail.com""saburo","Saitama","saburo@gmail.com"

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, 毎月開催)