nDiki : reStructuredText

可読性の高いプレーンテキストマークアップ文法、および Docutils 用パーサコンポーネント。 パーサは Python で書かれている。

Docutils には reStructuredText から

• HTML
• LaTeX
• XML

へのコンバータが用意されている。

メール 要求仕様書 書き方 ポイント WiKicker LaTeX2e 開発 仕様 DOM ソフトウェア PDF ガイドライン プログラミング言語 YAML Perl モジュール CSS Template Toolkit IronPython Zope SCons メモ XML::LibXML Unicode コミュニケーション ロック 現場 folksonomy 議事録 アイデア DocBook 印刷

■ 定型書式で内容を記述していくのに便利な形式は?

今要求仕様書を LaTeX で書いている。 要求と仕様の組をまとめて longtable で記述しているのだが、 LaTeX らしい繁雑さがあってちょっと効率が悪い。 マクロを定義すればある程度書きやすくなると思うが、それでもそこそこまでな気がする。

文書の中にレコードの並びが書けて、レコードの並びの中に文章が書きやすいそんなフォーマットはないものかなぁ。

• LaTeX + マクロ
  • 整形は綺麗。
  • 記述が繁雑になりがち。\マクロ名とか {} とか。
• DocBook
  • 仕様デカスギ
  • 以前使ってみたことがあるが、手で書くのにはしんどい。
• XML
  • 構造的な情報の表現には良いのだが、手で書くのはしんどい。開きタグも閉じタグも。
  • 普通の章節や、マークアップのルールを考えなければならない(定義するか借りてくるか)。
  • LaTeX等へのコンバータを書く必要あり。
• YAML
  • レコードの並びだけだったら良いが、文書の他の要素を一緒に書くのには適さない。
  • ある程度の構造やボリュームがあると、思ったほど手書きしやすくない。
  • YAML Perl モジュールで痛い目にあっている。

Wiki に慣れきっている自分にとっては Wiki 文法のような感じで記述できて、一部に定型レコードの並びが書けて、そこの整形ルールだけ定義してあげれば LaTeX に変換できるとかそういった感じがのものが欲しい。 定型レコードの部分は RFC822 のヘッダみたいな感じで良くで、値の部分に長めの文章を複数行で書けるものがいい。

構造化テキスト用フォーマット、あるいはWiki フォーマットをアレンジするのがいいかもしれないな。 このあたりのフォーマットは、ソーステキストのままでも充分読み易いことを意識して定義されているので書くのは楽。

• reStructuredText
  • いいらしい。
  • HTML、LaTeX、XML へのコンバータがある。
  • 拡張性も考慮されているらしい。
  • でも Python。
• Markdown
  • reStructuredText よりもソーステキストが読み易いらしい。
  • Perl
  • HTMLへの変換しかない。
• WiKicker (Wiki)
  • かなり書き慣れている。
  • レコードの並びの書き方を考える必要あり。
  • 複数行にまたがる処理を書くのが面倒。
  • 自分で書いているシステムなので中身は何でも知っている。
  • マイナー。

レコード部分とは関係ないけれど reStructuredText や Markdown の「アンダーラインのあるテキストを見出しとする」っていうのはいいな。 普段メールやプレーンテキストでちょっと文書を打つときに使っているスタイルと一緒だ。

要求仕様書用に使うかどうかは別として、要チェック。

• 早速 reStructuredText から LaTeX へのコンバータを書く (2005-11-24)
• reStructuredText いいんじゃない? (2005-11-22)
• Docutils は自分にとっての Python キラーアプリかも (2005-12-01)
• 私的10大ニュース2005 [ comp ] (2005-12-31)
• WiKicker に JSON でのページ出力機能を追加 (2007-04-03)

■ reStructuredText いいんじゃない?

昨日の続きであるが、reStructuredText がライトなドキュメント書きにはいいんじゃないかという感蝕を得た。

基本的にプレーンテキストのままで充分見られるので、そのままメールに貼りつけられる。

今までは文書を作成する際、メールで草稿をやりとりしたのち内容が固まったら LaTeX のコマンドでマークアップしてコンパイルしてPDF化していた。 これだとちょっと手間であるのだが、最初から reStructuredText 形式で書いていれば、そのまま rst2latex で LaTeX に落とせる。

また必要に応じて rst2html で HTMLに変換してWebサイトに置いておくこともできる。

これらで満足できない場合は Python のコードをいじって変更ということになるが、Python が駄目でも rst2xml でXMLに変換してしまえば他の言語でも reStructuredText のパーサを書かなくても(XMLの処理系を使って)コンバータを書くことができるの比較的楽である。

しかも欲しかったレコードの表現用にフィールドリストというシンタックスがあるではないか。

いいじゃん。

ということで早速今日から使うことにした。

Debian GNU/Linux sid にある Docutils 0.3.9 ではいわゆる全角文字も文字幅を1として扱かう。 このためテーブルなど桁揃えを用いる書式の部分がこのままだと不便である。 画面上では2文字分幅があっても1文字として数えられるため Docutils が通るようにするためには余計な空白などを入れて文字数を調整しなければならないが、そうすると今度は見た目的にずれるので可読性がかなり落ちてしまう。

この問題のためにMatsumoto,Tadashi氏がパッチ

• http://city.plala.jp/.../rst/README.html

を作成されているので、これを適用。

これでばっちり。

• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• Docutils は自分にとっての Python キラーアプリかも (2005-12-01)
• FreeMind でマインドマップ (2005-06-02)
• Docutils の reStructuredText から LaTeX ... (2005-12-07)
• Debian GNU/Linux に Hyper Estraier 1.2... (2006-05-31)

■ 早速 reStructuredText から LaTeX へのコンバータを書く

要求仕様書を書くのに reStructuredText を使ってみることにしる。 reStructuredText の文法の上で、あるルールに従って書いた特定のセクションやフィールドリストを要求レコードや要求仕様レコードとし、自前でコンバータを書いて LaTeX へ変換する形。

まずは最初のアイデア通り rst2xml で XML に変換してから、Perl スクリプトで読み込んで処理することにする。

Perl 側の処理は XML::LibXML で (何となく XML::DOM より好き)。 しかし毎度ながら DOM 面倒くさい。 とりあえず、今必要な要素のみ変換コードを書く。 reStructuredText を XML へ変換した時の DTD があるので、おいおいこれを見ながらきちんと埋めていかねば。

最低限のものができて、早速コンバート。

これで生 LaTeX で書くより随分楽になった。よし。

• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• Docutils は自分にとっての Python キラーアプリかも (2005-12-01)
• JavaScript でのプログラミングやっぱり面倒くさい (2006-07-23)
• Docutils の reStructuredText から LaTeX ... (2005-12-07)
• Progect -> XML -> text, HTML (2004-04-16)

■ Docutils は自分にとっての Python キラーアプリかも

先日 reStructuredText ベースの要求仕様書ファイルから、LaTeX への変換プログラムを Perl で作成した。rst2xml で変換した XML 文書経由で。

欲しいところだけまずは実装して使ったんだけれど、この先使っていくには細かいところを組んでいく必要がある。やっぱりフルスクラッチするのは面倒だな。

本来は Docutils 用の Writer を作成するのが王道。

しかし Python なんだよね。以前に何度か覚えておこうと思ったんだけれど動機付けが弱かったのかいつも途中でフェードアウト。 しかし今回は明確な目的があるので、もりもりやりそう。

まずは既存の docutils.writers.latex2e.py あたりをコピーしていじって遊んでみるかな。 自分の場合この方法が一番覚えるのが早い。 小学生の時に最初にBASICをいじった時も、既存のゲームのパラメータとか改造から入ったし。

さて、その latex2e.py であるが「documentclass がオプションや設定ファイルで変更できるものの、標準の LaTeX2e 用のもののどれかしか駄目」だったりなど、普通に使うにもちょっといじる必要がありそう(jsbook とか使いたいし)。

一旦自分好みの LaTeX2e Writer を作ってから、それを拡張する形で特定文書毎の Writer を作るのがよさそうだ。

• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• reStructuredText いいんじゃない? (2005-11-22)
• 早速 reStructuredText から LaTeX へのコンバータを書く (2005-11-24)
• Docutils の reStructuredText から LaTeX ... (2005-12-07)
• SCons は GNU Autotools のかわりになるか (2005-04-20)

■ Docutils の reStructuredText から LaTeX への Writer は継承しづらい

この間やっつけでPerl で コンバータをちょっと書いたのだが、やはりここは正攻法で Docutils の Writer として書いておきたい。

Docutils に含まれている LaTeX2e Writer (docutils.writers.latex2e) のクラスを継承してカスタマイズ版を作ればいいかなと着手。 この Writer の生成する TeX ファイルがちょっと好みではないので、継承して自分好みの Writer を書いた上で、それを継承してドメイン毎の Writer を書く事にする。

Python でコードを書いたことはほとんどないのだがそれほど迷う点はない。 素直な言語なのかな。$ とか @ が出てこないのはちょっと寂しい。ブロックをインデントで示すので「閉じ」がなく、ちょっと「スースー」する。 わかる? この気持ち。

Docutils はパースした結果 DOM ライクなツリーができて、これに対して visit / depart 式の visitor を使って処理をしていけるようになっている。 そのあたりはフレームワークがあるし、典型的なパターンなので楽ではある。

ただし、docutils.writers.latex2e のクラスが継承されることを意識されている感じがしないので、メソッドをコピーして書き換えてオーバーライドといった事が必要になる箇所が思ったよりあるのがちょっと気になる。 今後バージョンアップした時に内部も変わる可能性があるだろうし、最終的にはごっそり Writer を作ってしまう方が良さそうだ。

• Docutils は自分にとっての Python キラーアプリかも (2005-12-01)
• reStructuredText いいんじゃない? (2005-11-22)
• 早速 reStructuredText から LaTeX へのコンバータを書く (2005-11-24)
• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• SCons は GNU Autotools のかわりになるか (2005-04-20)

■ 私的10大ニュース2005 [ comp ]

今年は主に開発等よりもオンラインサービスの活用が中心的な話題であった。 来年度は、積極的に何かを産み出していきたところである。

@ Skype

年初はまずは Skype。 社内でも本社との連絡に活用されるようになった。 これほどツールがスムーズに社内に広まるのは珍しい。

社内といえば、やっと Wiki の利用が社内で広まってきた。今後より利用が進むといろいろ不満も出てくるはず。 それをうまく吸い上げていくことが重要。

@ ソーシャルブックマークサービス

Squrl を使いはじめて、はてなブックマーク1本へ。 2月のサービス開始から使いはじめてブックマークの数は 3,337。

folksonomy という観点では folk (folc / people) を実感できなかった。 タグは主に自分で分類するのに使っているというところ。

@ Flickr

2月に使い始めて、5月に Pro Account へ。 これで www.naney.org の容量を気にしなくて良いようになった。

@ Bloglines

RSS を発行しているサイトの巡回は Bloglines へほぼ集約。 斜め読み化が進んだ。

@ reStructuredText

可読性の高いプレーンテキストマークアップ文法。

この文法で書いておけば、メールでやり取りをしてまとまった内容をそのまま書き換え直さずに、小綺麗に整形してHTMLやPDF形式にすることができる。

ちょっとした文書の作成にもってこい。

今後環境整備や、自分なりの運用スタイルの確立がポイント。

• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• Rubric でプライベート SBS を立てるも 0.140 では日本語に不具合 (2006-07-22)
• Bloglines に巡回先の一部を集約 (2005-02-13)
• reStructuredText いいんじゃない? (2005-11-22)
• Linux 母艦ノート PC を使わずに仕事ができるかチャレンジ (2007-08-20)

■ Docutils 0.4 の日本語文字対応はまだまだ駄目

reStructuredText 形式の parse が失敗するようになったと思ったら、Docutils のパッケージが upstream の 0.4 に追従してバージョンが上がっていた。

Release Notes に

Added Japanese and Simplified Chinese language mappings, and support for double-width CJK-characters in tables and section titles.

とあって期待したのだが、試してみたところまだまだ駄目っぽい。

0.3.9 に戻して 以前入れた時と同様 patch をあて、元の環境に戻す。

今後に期待。

• reStructuredText いいんじゃない? (2005-11-22)
• Docutils の reStructuredText から LaTeX ... (2005-12-07)
• Docutils は自分にとっての Python キラーアプリかも (2005-12-01)
• ドキュメンテーション大全 (2006-02-15)
• Mule-UCS の設定 (2006-03-08)

■ ドキュメンテーション大全

プロジェクトの後半で納品用ドキュメントの整備を始めるのだが、その時はたいがいもう切羽詰りはじめていて構成やら体裁やらマネジメントやらを工夫する余力が無かったりする。 ついつい(次回は改良しようと思っていつも思っている)前回のプロジェクトの手法を踏襲してしまいがちだ。 ともすれば劣化コピーになりかねない。

やはり、忙しくても日頃からの改善は重要である。

最近はアジェンダ・議事録・開発メモなどを、積極的に Wiki や Subversion で共有するようにし、その点では以前より改善してきている。

今後はさらに、出荷ドキュメントのレビュープロセスなどを確立し品質を高めていきたいところである。 現状でもチームメンバでのピアデスクチェックやパスアランドを非形式的に行っているのだが、「チェックの程度」やその後の「修正」および「修正の確認」については、まだなんとなくやったかなという具合。この辺りを工夫したい。

先月発売されていて気になっていた「開発の現場 Vol.003」に、何かヒントがあるかなと思って買ってみた。

• 開発の現場 Vol.003 効率UP&スキルUP ドキュメンテーション大全

パラパラと見た感じではテクニカルライティングの話はあまりなく、主にソフトウェア開発における中間成果物としてのドキュメントや開発者間ドキュメントをどうとりまとめていくかという話が中心のよう。 Wiki による開発資料のライトな共有など、うちのチームでも進めている話など。

「(最初から)完全なドキュメントを書こうとしない」というのはもっとも。 状況はほとんどの場合変わるし、最初の段階では未確定の部分も多い。 だからといって、いつまでたっても手元で温めていてもしょうがない。

技術的な話では Perl の Pod を活用しようという話。 Perl 以外の言語のコメント中に Pod 形式でドキュメントを書こうという提案や、Apache で動的に Pod ドキュメントを整形しようという話とか。

テキストフォーマットとしての Pod は =over / =item / =back によるリスト表現など、最近のフォーマットに比べてすごく読み易いわけではないが、たしかに他の言語のコメントに埋め込んでおいて処理するのは、標準の Pod 関連のモジュールでできるな。

自分も Pod でドキュメントを書くけれど、(Perl 以外は) 個人的には reStructuredText にしたいと考えている。 ただ Pod みたいに他のテキストの一部に埋め込んでその部分のみ処理する記法およびツールがが標準の reStructuredText / Docutils には見当らない。 実はどっかにあるのだろうか。

[ 書評 ]

• 第1回 社内 Perl 勉強会 (2006-04-21)
• 私的10大ニュース2004 [ comp ] (2004-12-31)
• [ WiKicker ] 日記機能開発開始 (2003-12-27)
• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• bundle を作成して Perl モジュールをまとめてインストール。 (2004-10-21)

■ Mule-UCS の設定

reStructuredText では表を作る時は文字数で桁揃えして、表セルを表現していく。 ASCII 文字などフォント幅がいわゆる半角幅であるものだけならば、良いのだが全角幅の文字がある場合はちょっと厄介である。

文字数的には1文字なのだが、プレーンテキストファイル上では2文字分の幅を取るので見た目上桁が揃わなくなってしまう。 というかそれを忘れて桁を揃えておくと、パーサに怒られる。

このためにパッチがあったり、Docutil 0.4 ではこの対策がほどこされたりしている(不完全であるが)。

さらに厄介なのが Unicode 変換がからむところで、 Emacs + Mule-UCS ではいくつかの(いわゆる)全角文字は UTF-8 で保存すると違う文字に変換されてしまい、これまた Docutils のパーサに、桁があっていないと怒られることになる。

できるだけ全角文字はそのままにしておくということで、以下の設定を追加しておいた。

 (require 'un-define)
 (un-define-change-charset-order
  (append '(ascii japanese-jisx0208)
          unicode-basic-translation-charset-order-list))

またバックスラシュと円記号の方も混乱が少ないように

 (require 'un-supple)
 (un-supple-enable 'windows)

を追加してく。

• 日本語ファイル名どんとこい (2005-03-07)
• reStructuredText いいんじゃない? (2005-11-22)
• [ Java ] Unicode (UCS) -> 別の charset (2003-12-12)
• ドキュメンテーション大全 (2006-02-15)
• kterm から mlterm へ (2004-11-26)

■ GTD 参照資料ファイル置場として howm を使い始めてみた

Life Hacks PRESSの巻末「執筆陣に聞きました!」で、角谷信太郎氏が、howm でメモをしていると述べていた。

以前話題なった時にも気になったんだけれど、その時は emacs-wiki を使っていたこともあって手を出しそびれてしまった。

howm は検索を中心としたリンク機能を持つメモツール。名前を指定せずにちょっとしたメモを作成し、後で探し出すことできる。

GTD で参照資料扱いとするメモをどこに保存しておこうかと思案していたのだが、丁度よさそうだ。

ソフトウェアインストール時の作業履歴やら、ちょっとした下書きやらのファイルも散在して後で扱いに困っていたのだが、これらもまとめて放り込んでおける。 しばらく使い込んでカスタマイズしたりして、自分流のスタイルを模索してみることにしよう。

howm 自体はほとんど書式というものがない。 自分の好きな形式で自由に書くことができる。 自分は reStructuredText か WiKicker 形式で書くことになるかな。

その辺も含めていろいろ遊んでみよう。

• howm で nDiki の記事も検索対象にする (2006-04-02)
• Rubric でプライベート SBS を立てるも 0.140 では日本語に不具合 (2006-07-22)
• GTD Next Actions リスト用ノートをやめる (2007-07-25)
• 社内 Blog 開設 (2006-05-16)
• [ WiKicker ] Memcached を使った検索結果のキャッシング (2004-01-15)