nDiki : reStructuredText

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

Docutils には reStructuredText から

• HTML
• LaTeX
• XML

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

メール 要求仕様書 DOM PDF LaTeX2e ソフトウェア ポイント WiKicker 検索 開発 書き方 仕様 howm www.naney.org CSS folksonomy 布団 コミュニケーション ソフトウェア開発 RSS ソフトバンク 箇条書き Twitter Bloglines 電子メール svn patch 注文 Ruby Perl モジュール

■ 早速 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)
• Twitter ベイジアンフィルタプロキシ (2007-12-29)
• reStructuredText いいんじゃない? (2005-11-22)

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

■ 私的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)
• Evernote 使用開始 (2009-03-03)
• Bloglines に巡回先の一部を集約 (2005-02-13)
• Rubric でプライベート SBS を立てるも 0.140 では日本語に不具合 (2006-07-22)
• reStructuredText いいんじゃない? (2005-11-22)

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

今後に期待。

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

[ 書評 ]

• 今日のさえずり - 京都の小学校のコンピュータ室にいったら、Squeak が (2008-03-06)
• 私的10大ニュース2005 [ comp ] (2005-12-31)
• 過去の今ごろ (2004-09-19)
• Google ドキュメントでソフトウェアかんばん (2008-03-30)
• 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)

を追加してく。

• reStructuredText いいんじゃない? (2005-11-22)
• 私的10大ニュース2005 [ comp ] (2005-12-31)
• Evernote 使用開始 (2009-03-03)
• 今日のさえずり - ゲップが香るブルガリアンローズ(DHC) (2008-10-22)
• OpenOffice.org 2.0.3 をインストール (2006-08-03)

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

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

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

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

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

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

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

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

• Evernote 使用開始 (2009-03-03)
• howm で nDiki の記事も検索対象にする (2006-04-02)
• 社内 Blog 開設 (2006-05-16)
• Rubric でプライベート SBS を立てるも 0.140 では日本語に不具合 (2006-07-22)
• GTD Next Actions リスト用ノートをやめる (2007-07-25)

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

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

そんな中、東洋経済新報社の「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)
• ソフトウェアかんばん「見えない化」 (2006-04-10)
• パーソナルファクシミリを物色 (2007-01-07)
• 私的10大ニュース2005 [ comp ] (2005-12-31)
• 今日のさえずり - PuTTY って「パティ」なのか (2008-09-11)

■ 今日のさえずり - たまにオッサンみたいな驚き方する

@ 2009年11月09日

• 08:18 ベンザブロック L服用。 [mb]
• 09:27 駅が混沌としている。 [mb]
• 09:32 山手線運転再開しているのか。京浜東北線混雑にはもう影響しないかな? [mb]
• 09:40 京浜東北線田町駅で山手線内回りと並走。山手線も空いている。 [mb]
• 12:39 ベンザブロックL服用。
• 12:42 「たまにオッサンみたいな驚き方する」って言われてしまった。
• 12:50 フグ田マスオ28歳。 RT @wtnabe: @Naney そういうときのために「マスオさんが驚いたときのマネ」を体得しとくといいですよ。
• 14:08 うーん、喉がイガイガするので飴買ってくる。
• 14:15 プロポリスのど飴にした。プロポリス成分はきっと気休め程度しか入ってないんだろうな。 [mb]
• 14:23 UHA味覚糖のプロラボ プロポリスのど飴が予想以上にビリビリくる。刺激的で赤面。
• 14:27 @Michiaki 初めて舐めたんですが、これって効きますか?
• 15:10 svn2cl 使った。まずまず使える。
• 17:26 喉のイガイガがおさまったけれど、プロポリスのど飴のせいなのかベンザブロックLのせいなのか、はたまた自然治癒なのか不明。
• 19:05 また reStructuredText 使いたくなってきた。
• 19:18 セブン-イレブン限定 ZAKU II。 http://movapic.com/...
• 19:29 隣の人が日本酒臭い。酒臭いじゃなくて日本酒臭い。 [mb]
• 21:11 @maru_kei 確かに体臭+香水はきついよね。 [mb]
• 21:48 @maru_kei あ、今読みました。オメデトウ!
• 23:58 なんとか日付が変わる前に布団に入った。 [mb]

@ 2009年11月10日

• 09:15 自殺点とかサドンデスってもうみんな使ってない? 狩られきった? [mb]
• 09:41 MovaTwitter で #sb2009 つぶやき検索しながら出勤中。 [mb]
• 09:44 ヨドバシカメラ マルチメディア Akiba のソフトバンクショップ/コーナーは 何事もないような雰囲気。 #sb2009 #Akihabara L:秋葉原 [mb]
• 10:36 新しい名刺をもらった。シングルネームになった。
• 12:27 風邪で喉が不調。声が出ないのでおとなしくしている。Twitter は声が出なくてもさえずれるからいいね。
• 12:31 840P に帆立色。
• 12:51 ポットパイをホットパイという2人組をやっつけるために Google 検索した。
• 13:06 誰かがネットワークカメラもりもり動かしている。
• 15:09 後ろの人にビタミン C もらった。みかん。感謝。というか、ねだった。
• 17:37 注文した ThinkPad X200 用にリカバリー・メディアを作るための光学ドライブを買うか、丸ごとコピー用の HDD を買うか迷っている。後者の丸ごとコピーが簡単にできるのか不明。
• 18:01 柿の種のあまりのピーナッツを押し付けられた。
• 19:25 声優のたまごが駅前で何か配ってる。 #Akihabara L:秋葉原 [mb]
• 19:46 明日コンサートなので喉回復させんと。 [mb]
• 20:02 多慶屋パープルのビニール袋持っている人発見。そういえばあまり見かけないな。 [mb]

• 今日のさえずり - あれ移転後の日比谷神社なのかあ (2009-06-10)
• 今日のさえずり - フロスティ食べたい (2009-12-10)
• 今日のさえずり - やはりデジにはない歓びが味わえるな (2008-04-08)
• 今日のさえずり - PuTTY って「パティ」なのか (2008-09-11)
• 今日のさえずり - 待受画面が巨大仏像写真なのでビビった (2009-11-06)