nDiki : Pod

Perl スクリプトファイルの中に埋み可能なドキュメンテーションフォーマット。 ドキュメンテーションコメントに使われる。

Perl モジュール インストール プログラミング言語 Javadoc 仕様 Wiki Naney Perl Coding Standards Perl style guide CPAN 開発 ActivePerl Perl モジュールの作り方 doxygen Ruby ソースコード LaTeX 識別子 正規表現 API RD HTML reStructuredText メモ PPM パッケージ 現場 ファイルシステム Ming 議事録 WiKicker WikiEngine

■ pod2latex

仕事で書いた Perl モジュールの API 仕様を紙媒体にしなければならないので、今回は pod2latex を使ってみる。

 pod2latex -modify -full -out hoge-utf8.tex lib

で lib ディレクトリ以下の *.pm の Pod が集められて hoge-utf8.tex になる。ソースを UTF-8 で書いているのでこれを lv などで EUC-JP に変換して、platex してdvipdfmx。

前に Javadoc から LaTeX に落とした時に比べて非常にすんなりと変換してくれる。 '=item foo([opt])' とかすると ] 文字が落ちたりする以外は特に今のところ目につく問題なし。

ま、いざとなったらスクリプトに手を入れて直せるだろうし、なかなかいいんじゃないでしょうか。

• Twitter ベイジアンフィルタプロキシ (2007-12-29)
• bundle を作成して Perl モジュールをまとめてインストール。 (2004-10-21)
• 携帯電話(iモード)から Twitter を更新する (2007-04-07)
• pLaTeX + hyperref + dvipdfmx で PDFにしおりを (2005-04-15)
• LaTeX でプレゼンテーション (2005-06-21)

■ bundle を作成して Perl モジュールをまとめてインストール。

依存モジュールが多くなってきて、開発しているPerl モジュールの実行環境構築が面倒になってきた。

ActivePerl では PPM パッケージ化 + PPM リポジトリで芋蔓式インストールが可能である。 素のPerlだとCPANモジュールでネットワークインストールする事になる。 ここで一個づつインストールしていくのがかったるい。 ということでCPANにあるモジュールのように Bundle::* を作る事にした。

調べてみると簡単。

• bundle はただのPerl モジュールである。
• Bundle:: 名前空間に置く。
• =head1 CONTENTS Podセクションを置き、各行に1つづつ依存モジュールを列挙する。

フォーマットは以下。

 Module_Name [Version_String] [- optional text]

これだけ。Pod に書かせるあたり、とりあえずから始まった感じである。

CPAN上に置あるものはきちんと tarball 化してあるが、ローカルで使う分にはこの bundle Perl モジュールを @INC のどこかに置いておけばよい。

Bundle::MyModule を作ったとすると perl -MCPAN -e shell から 'install Bundle::MyModule' でOK。

@ CPAN と @INC 上の '.'

カレントディレクトリの下に Bundle/MyModule.pm を置いて

 perl -I . -MCPAN -e shell

として Bundle::MyModule をインストールしようとしたのだがうまくいかない。CPAN のシェル上の ! コマンドで @INC を出力してみると . が含まれていない。何故? PERL5LIBに設定しても同様。 試行錯誤したところ絶対パスで指定すればOKであった。

CPAN.pm 1.76_01 を読んでみた。

 no lib "."; # we need to run chdir all over and we would get at wrong
             # libraries there

これだ。

• ActivePerl で Ming (2005-02-23)
• PAR::Repository でビルド済み Perl モジュールをネット... (2006-12-12)
• Module::Build でソースパッケージング (2005-08-24)
• 自前 PPM リポジトリの管理 (2006-07-03)
• WiKicker に JSON でのページ出力機能を追加 (2007-04-03)

■ Ming でいきなりハマる

一昨日インストールしたMing 0.3 beta 1 + Perl でいろいろ実験。 Ming 関連は資料が少ない。

@ SWFバージョンの設定

SWF::setVersion(6) をしても吐き出されるバージョンは5。 SWF::Movie の Pod に書いてある

 new SWF::MovieWithVersion(6)

はエラー。

結局 xs ファイルを見て、

 SWF::Movie::newSWFMovieWithVersion(6);

なら呼べてバージョン6形式で吐けることを確認。

@ テキストフィールドのインスタンス名? 変数名?

テキストフィールドの onChanged イベント処理のテスト。

SWF::TextField インスタンスに setName で名前を設定して ActionScript から onChanged イベントハンドラを設定するも、ウンともスンとも言わない。 設定した名前に文字列を代入すると表示が書き換えられるはする。 はて。

どうやらMacromedia Flash ではテキストフィールドにインスタンス名と変数名があるようだ。 setName で設定した名前はどっちだったのか? どうやら変数名っぽいのだが。

また手元の本によると onChanged はインスタンス名を指定するらしい。 Ming ではどうする?

いろいろいじったところ、SWF::Movie に add した後の返り値である SWF::DisplayItemオブジェクトに対して setName し、ActionScript でこの名前のインスタンスに対して onChanged にハンドラを与えたところうまく動くようになった。 ということはこれがインスタンス名なのか?

• ActivePerl で Ming (2005-02-23)
• wxPerl で daemon モニタ (2005-03-11)
• Perl で遺伝的プログラミング (2004-07-05)
• 最新の Module::Install は Perl 5.005_03 ステ? (2006-04-29)
• Perl テストスクリプトの中で標準エラー出力を一時的に止める (2006-12-15)

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

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

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

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

[ 書評 ]

• bundle を作成して Perl モジュールをまとめてインストール。 (2004-10-21)
• Wiki Way (2002-09-07)
• CGI プログラム、Out of memory! に泣く (2001-01-04)
• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• 私的10大ニュース2005 [ comp ] (2005-12-31)

■ Perl 用の doxygen のようなツールはないのかな

WiKicker のソースコードを人に説明するのにプリントアウトして説明するのに、doxygen のようなツールが欲しいのだけれど Perl 用のものはないのかな。

1. ソースコードを色付けした HTML に変換してくれる
2. Pod とコード本体を混在してドキュメント化してくれる
3. ソースツリー内のファイルをそれぞれ処理してくれて、インデックスファイルも生成してくれる。
4. できれば識別子がリンクになってくれる

というのが希望。1 だけなら結構いろいろなツールがあり、1 + 2 なら perltidy で実現できる。 しかし 3、4 までしてくれるツールが見つけられない。

とりあえず perltidy の Perl::Tidy と File::Find で再帰的にまとめて HTML に変換するスクリプトだけは書いて、一気に変換だけはできるようにしておいた。

インデックスの作成までは面倒なので未着手。

• 第2回 社内 Perl 勉強会 (2006-04-28)
• Perl プリティプリンタの定番 perltidy (2006-04-23)
• Emacs でお好きな言語のソースコードを色付き HTML テキストに変換 (2006-04-21)
• 定型書式で内容を記述していくのに便利な形式は? (2005-11-21)
• WiKicker に JSON でのページ出力機能を追加 (2007-04-03)

■ Perl で CR/LF/CRLF 全対応の1行毎読み込み処理

Perl プログラムでテキストファイル処理を 改行コード CR/LF/CRLF 全対応にしようと思ったが、書こうとするとこれが結構面倒臭いことに気がつく。

$/ に正規表現が設定できないため、<FILEHANDLE> で単純に3パターン対応ができない (LF と CRLF に対応とかならすぐできる)。

小さいファイルと仮定して良いなら全部読み込んで自前で行分割、大きいファイルならまじめにバッファリングして改行コードをスキャンして行処理するのが正攻法かな。 多少効率悪くなりそうだけれど。

@ Pod::Html (1.0504) の場合

Perl 5.8.8 の Pod::Html (1.0504) だと pod2html の中で $/ = "" と設定して、パラグラフ単位で読み込んでそのあと処理している。

@ PerlIO レイヤー

最近の Perl であれば PerlIO::crlf、 PerlIO::eol あたりが使えそうである。

もちろん Perl 5.005_03 だと NG。

• [ WiKicker ] 通知メールの Subject: フィールドのエン... (2004-01-25)
• 第6回 社内 Perl 勉強会 (2006-06-05)
• ドキュメンテーション大全 (2006-02-15)
• Perl 用の doxygen のようなツールはないのかな (2006-07-25)
• mixipress でコミュニティ掲示板もチェック (2005-10-01)