2011年11月 5日
Wiki記法的なものとか文書管理とかに思うこと
Wiki記法的なものとか文書管理とかに思うこと
最近社内向けのドキュメント書いてたりもするので、かねがね思っていたことを書く。かなり与太話。
文書管理とかについて思うこと
文書くときって使い慣れたローカルのエディタで編集したいじゃないですか。長いBlogを書くときって、結局ローカルで書いたのをテキストエリアに貼り付けて、みたいにやっている人は多いと思うんですよ。僕はそうしてます。
BlogにせよWikiにせよドキュメントにせよ、ローカルでテキストファイルを編集できて、バージョン管理して、リポジトリにコミットしたらサイト反映みたいになってると、楽だと思うんですよね。
複数人で編集するときにすごく効果を発揮するはず。Wikiとか編集が競合したらめんどくさいけど、今時のバージョン管理ツールなら上手いことマージしてくれたり、コンフリクトを検出できるし。
文書フォーマットをどうするかというと、LaTeXで書いてPDF出力してみたいな話もあると思うし、書籍を執筆するときなんかはそれで良いと思う。実際問題としてはHTMLに変換できる簡易マークアップ記法が良いんじゃないかと思っている。
HTML+CSSの表現力ってのはすごい
アウトラインを意識すれば文書を書くというレベルで不自由はない。アウトラインを意識せざるをえないってのがHTMLで文書を書く上で逆に良い点だと思う。print.css書けば印刷物としても十分耐えうる。レイアウトもかなり自由が効く。
実際、僕は職務経歴書はHTMLで管理している。「プログラマの職務経歴書なのに綺麗に整ってますね」とか良くわからない褒められ方をされたことがある。HTMLで書いたと言ったら非常に驚いていた。
書籍とかで目次や索引をつけてページ数との対応とかをやるとなると、ワープロソフトに軍配があがると思うけど、実際は逆にハイパーリンクを張れたほうが何かと便利。
ePubの議論も盛んになってきたので、HTMLを紙にした時の見え方やそれに関連するCSSプロパティの対応はだいぶ進んできている。例えば、少し前まで背景画像のサイズ指定ができない問題があったけどbackground-sizeに対応しているブラウザも増えてきた。
Wiki記法とか
ただ、HTMLを直で書くのはきついし、HTMLテキストは可読性も低い。HTMLで使う要素は限られているのだから簡易記法で書くのは理にかなっている。
Markdownはテキストファイルのままでも可読性が高いってのが優れている。
ただ、Wiki的記法に総じて言えることだが、簡易記法である分、HTML→記法の逆変換が難しいってのが問題点。あくまで簡易記法だからHTMLのすべてをまかなえるわけではない。
Markdownは直にタグを書けるようになっていて、Markdownでまかなえないことは自分でタグを書いて解決するという割り切った方針になっている。そして、Markdownが提供するシンタックスも最低限になっている。
その割り切りは好きなんだけど、シンタックスがちょっと最低限すぎるってのがある。ちょっと複雑なHTMLを書きたくなると、すぐにタグが入り交じって可読性が落ちる。やれることが最低限な分、独自拡張が乱立してるのも問題。
そして、タグを書けるようにしているってのは実装上かなり大変。Wikiパーサーはただでさえ処理の前後関係を整理するのが難しいのに、タグ直書きを実現するためにパーサーのコードはさらにカオスなことになっている。だから前後関係を崩さないように拡張するのも大変。
Markdownその他簡易マークアップ言語に不満な点
定義リストとテーブルは欲しい。
定義リストは議事録的なものをとるときに、質疑応答とか小テーマとそれに対する決定事項みたいなものを並べるときに使いたい。(議事録なんかをとるときに簡易マークアップ言語を使うのは、書式の統一がとれて良いと思う)
あと、ソフトウェアのドキュメンテーションとかやると、codeの他に出力やシェルプロンプトを出したいので、sampが書けるとうれしいよなぁと思う。
あと、そろそろHTML5対応した簡易マークアップ言語が欲しいと思うところ。
特にasideが欲しい。実際普通に文章を書いていて横道にそれた時とか、議事録なんかで本筋から外れた話を書くときに使いたいですね。
HTML5の目玉(？)である、セクショニングの頭でh1を使うみたいなのは、既存の基本でもバリバリやっちゃって良いと思う。
このへんの不満を解消すべく、KuaiWikiを書き始めた部分があるんだけど、色々コード的にイケてなさすぎるので、げんなりして開発が止まっている。それに結局こういうWiki記法ってのは使ってもらってなんぼですね。そういう意味ではてな記法は成功したと思う。
Sphinxは便利っぽいけどreSTがイマイチ
あくまで個人的な感想ですが、reSTはイマイチだと思う。
あと、SphinxはePub変換とかPDF変換とか謳ってるけど、ePubは所詮HTMLに辞書情報のXMLファイル付加してzipで固めただけだし、PDFもWkHtmlToPdfとか使えば、HTMLからPDF生成できるわけだからそんな特別な話では無い気がする。要は印刷を意識したprint.cssが書ければあとは自由自在。
HTMLとPDFとePubが出せれば他のフォーマットは特に必要ないだろうし、HTMLがあれば、PDFもePubも出せるのです。
リンクとかリソースとか
Wiki的なものを実現させようとするときに、ページ内リンクをどう実現するかってのは地味にめんどくさかったりする。(ページ名を変えたときのリンク張替えとか、マルチバイトのリソースをどう管理するかとか。ファイルとして保存する場合はファイル名を可搬性のある形でどう保存するかとか。)
数式とか
LaTeXで書けるようになってて、MathMLで出力される感じのシンタックスがあれば良いのかなぁ。MathMLどうなのかなぁ。今日のSugamoでも話題になってたけど。
図とか
blockdiagがすごすぎる。テキストファイルでUMLを記述して画像出力するという素晴らしさ。今後の継続開発に期待。
あとは、Cacooも素晴らしすぎる。前職で社内向にYapafiのドキュメント書いたときに使った。UMLの要素も揃っている。とかそういう話を今日のSugamoでも話が出た。