nDiki : Docutils

Python で書かれたオープンソースのテキスト処理システム。

LaTeX Perl LaTeX2e XML TeX Wiki HTML PDF sid プログラミング言語 Markdown IronPython Zope SCons メモ Unicode ロック 現場 要求仕様書 議事録 開発 DOM UTF-8 Pod コンポーネント プレゼンテーション Subversion フレームワーク Emacs メール

■ 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)
• Docutils の reStructuredText から LaTeX ... (2005-12-07)
• FreeMind でマインドマップ (2005-06-02)
• Debian GNU/Linux に Hyper Estraier 1.2... (2006-05-31)

■ 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)
• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• 早速 reStructuredText から LaTeX へのコンバータを書く (2005-11-24)
• SCons は GNU Autotools のかわりになるか (2005-04-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 をあて、元の環境に戻す。

今後に期待。

• Docutils は自分にとっての Python キラーアプリかも (2005-12-01)
• reStructuredText いいんじゃない? (2005-11-22)
• ドキュメンテーション大全 (2006-02-15)
• Docutils の reStructuredText から LaTeX ... (2005-12-07)
• 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 には見当らない。 実はどっかにあるのだろうか。

[ 書評 ]

• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• 第1回 社内 Perl 勉強会 (2006-04-21)
• ソフト契約と見積りの基本がよ～くわかる本 (2005-10-14)
• 開発の現場 Vol.004 「上流脳」をつくろう! (2006-04-14)
• Joel on Software - 必読書 (2008-08-14)

■ 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)

を追加してく。

• [ Java ] Unicode (UCS) -> 別の charset (2003-12-12)
• reStructuredText いいんじゃない? (2005-11-22)
• ドキュメンテーション大全 (2006-02-15)
• Docutils は自分にとっての Python キラーアプリかも (2005-12-01)
• kterm から mlterm へ (2004-11-26)