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 印刷 GNU

■ 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)
• Twitter ベイジアンフィルタプロキシ (2007-12-29)
• 私的10大ニュース2005 [ comp ] (2005-12-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)
• reStructuredText いいんじゃない? (2005-11-22)
• 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)
• Bloglines に巡回先の一部を集約 (2005-02-13)
• Rubric でプライベート SBS を立てるも 0.140 では日本語に不具合 (2006-07-22)
• Plagger のインストールが大変なので XML::RSS で RSS ... (2006-06-10)
• はてなブックマーク上の最新ブックマークを nDiki に (2005-05-16)

■ 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 をあて、元の環境に戻す。

今後に期待。

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

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

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

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

最近はアジェンダ・議事録・開発メモなどを、積極的に 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 には見当らない。 実はどっかにあるのだろうか。

[ 書評 ]

• 私的10大ニュース2004 [ comp ] (2004-12-31)
• bundle を作成して Perl モジュールをまとめてインストール。 (2004-10-21)
• ソフト契約と見積りの基本がよ～くわかる本 (2005-10-14)
• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• 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)

を追加してく。

• kterm から mlterm へ (2004-11-26)
• Docutils 0.4 の日本語文字対応はまだまだ駄目 (2006-02-07)
• xyzzyを読み取り専用メディアから起動する (2004-07-28)
• Linux 母艦ノート PC を使わずに仕事ができるかチャレンジ (2007-08-20)
• reStructuredText いいんじゃない? (2005-11-22)

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

■ ビジネスメールガイドライン案

以前メールによる社内コミュニケーションの問題について書いて以来、いろいろと考えてみている。

そんな中、東洋経済新報社の「Think! SPRING 2006 No.17 超ロジカルシンキング」の中に参考になる記事を発見。 照屋華子氏の「ロジカル・ライティング - 論理的に考え、伝えるための3つの鍵を身につける」という記事だ。

すべてのビジネス・コミュニケーションは「伝え手」「受け手」「テーマ」「答え」「期待する反応」という5つの基本要素で成り立っている。-- Think! SPRING 2006 No.17 p.43

おお、ちょうどこういう切り口を探していたところだったんだ。 電子メールによるコミュニケーションも全く同じ枠組みである。 記事の中ではロジカル・シンキングをコミュニケーションで生かすという話題を中心に展開しているが、十分メールの書き方に通じるものがある。

この記事と、さらにちょっと前に買った「SEの実力を磨く究極仕事術」のメール術の章を参考にガイドライン案のスケルトンを作ってみた。

感情論は今回は置いておいて、情報共有・課題共有・リクエストの明確化・処理促進をポイントに列挙。 それから署名その他、一般的な話もいまのところ省略。

ポイントを列挙しただけなので、他人にもわかる形にはなっていない。

まずは自分自身に適用して、整理していってみることにする。

@ 1. 考える

• 【伝え手】伝え手は誰? (自分)
• 【受け手】受け手は誰?
• 【テーマ】テーマは何? 問いの形で。メールのテーマは1つに絞られているか?
• 【答え】 テーマに対する答え(テーマに対する説明)は何?
• 【期待する反応】受け手に期待する反応は何?
  • 誰に、いつまでに、何をどうして欲しい?
• コミュニケーション手段としてメールは適切?

@ 2. メールを書く

 ○○様へ                     # 受け手

 △△の××(自分)です。       # 伝え手

 テーマ
 ******
 コミュニケーション設定

 ○○の結論                   # 答え (結論)
 ==========
 ...

 (ここまででポイントを言いきる。)

 具体的な内容                 # 答え (詳細)
 ============

 項目1
 -----
 ....

 - リスト項目
 - リスト項目

 項目2
 -----
 ...

 - リスト項目
 - リスト項目

@ サブジェクトを書く

• 見ただけでわかるようにする
  • □ 具体的に書く

@ 導入部を書く

コミュニケーション設定を行う。

• □ 冒頭に宛先【受け手】を明記する。(誰に読んで欲しいのか? 他に誰に送られているのか?)
• □ 次に発信者【伝え手】を明記する。(From: フィールドに頼らず書く → 印刷・コピー用)
• □ 【テーマ】を書く。
• □ (オプション)【テーマ】の経緯・背景を書く。(「なぜこのテーマのメールがくるの?」)
• □ (オプション)なぜこの【伝え手】からなのかを書く。(←「なぜあなたからリクエストされるの?」)
• □ 【期待する反応】を明記する。
  • □ 「誰が」「何を」「いつまでに」「どのような品質で」して欲しいのかを書く? (← 「で何をして欲しいの?」)
  • □ 反応のメリットを書く (←「なぜこの反応をとらなければならないの?」)
  • NG 「ご意見があればお願いします」 → ない場合は?
  • NG 「どちらが良いと思いますか?」 → 意見として? 決定として?
  • NG 「ご検討ください」→ 検討した後どうして欲しいのか?
• □ (オプション)なぜこの【受け手】に読んでもらいたいのかを書く (←「何で自分なの?」)
• □ 特記事項があれば書く
  • □ 答えの情報源など

@ 答え (結論)

結論を書く。

• □ 詳細まで読まなくても済むようにする。
  • NG 「以下のように……」 → 要旨を書く
  • NG 「添付ファイルの通り」 → 要旨を書く

@ 答え (詳細)

根拠・資料などを書く。

• □ 受け手から見て必要十分な情報を書く
  • NG 「添付ファイルの通り」 → 要旨を書く
• □ 受け手が読みやすいように書く
  • □ リスト化する

@ 全般

• □ 具体的に
  • NG 「来週までに……」 → 「×月×日までに……」
  • NG 「先日の……」 → 「×月×日の……」
  • NG 「この間の……」 → 「×月×日の……」
  • 説明は肯定形で書く (否定形だと具体的に何なのかわからない)
• □ 論理的に
  • □ 構造化する
  • □ リスト化する (箇条書き化する)
• □ 受け手が読みやすいように
  • □ フォーマットを工夫する (ソフトウェア技術者間なら reStructuredText がお薦め)

@ 3. 送信する

• □ 送信する前に見直す
  • □ typo チェック
  • □ スペルチェッカ通す

@ A. メールを受信した時

@ まず返信する

どれか

• リクエストを「受ける」 / 返信で処理する (意思決定を返すなど)
• リクエストを「断わる」
• 「別の提案をする」
• 明確化の質問をする

メールでは不適当と思ったらコミュニケーション手段を 直接 / 電話に切り換える。

@ B. 返信する時

@ サブジェクト

• □ テーマが変わったら書き換える

• メールによる社内コミュニケーションの問題 (2006-04-12)
• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• 「プロジェクトマネジメント」はどうやって勉強すれば良いですか? (2006-11-22)
• ソフトウェア技術者御用達のプロジェクトマネジメントツール TaskJuggler (2007-04-23)
• ソフトウェアかんばん「見えない化」 (2006-04-10)