by Hippo2000(2000/8/6)
Perlに限らず、プログラム開発においてドキュメントは必要不可欠です。
特にPerlの場合、かなり便利な機能があるのですが、あまり知られていないようです。
＃というより、私が知らなかっただけか(^^;;ちょっとその辺をまとめてみようと思います。
当然すぎるほど当然ですが、ラクダ本（「プログラミングPerl」）が、最も基本的な、そしてもっとも重要な情報でしょう。
しかしPerlの場合、インストールするだけでドキュメントがついてきます。またインターネットから各種の最新ドキュメントを取得することができます。（特にCPANに登録されているモジュールを利用する場合には！）
そうした情報源を表にまとめとめてみました。
ここに上げているものは主に英語です。(^^;;;
基本的に単語を調べていけば、Perlや利用するモジュールに関連する技術に対する知識があれば、英語だからわからないというようなドキュメントではないだろうと思います。（モジュールの作者の多くが英語圏の人ばかりですからね）
＃英語の読み方については、別途、個人的な経験についてまとめようとは思っています。.
| 場所 | 説 明 | |
|---|---|---|
| ローカル | perldocやmanによる表示 （POD形式） |
Perlのファイルにはドキュメントが埋め込まれています。 こうしたドキュメントはperldocなどのユーティリティで見ることができます。 特にUNIX系の場合にはmanによっても見ることが可能なことが多いようです。 POD形式をman、HTMLなどに変換するためいくつかのユーティリティが提供されています。 |
| HTML形式 | ActivePerlの場合、インストールしたディレクトリの下にHTML形式のドキュメントが作成されます。 PPMでインストールすると、そのモジュールのHTML形式のドキュメントも登録されます。 （ActiveStateなどでHTML形式を用意しいている場合） ex. c:\perl\html\index.html など またHTMLヘルプの形式になっているものもあります。 c:\perl\htmlhelp （インストールしたディレクトリの下\htmlhelpというディレクトリ） |
|
| インターネット | CPAN | いわずと知れたPerl情報の中心。 CPAN： http://www.cpan.org など |
| ActivePerlオンラインドキュメント | ActiveStateはActivePerlの標準のヘルプをインターネット上でも公開しています。 http://www.activestate.com/ActivePerl/doc |
|
| その他 | DBIやWin32::ODBCなどモジュール開発者のホームページで情報を提供していることもあります。 | |
| インターネット 日本語 |
スクリプティング言語研究室（仮） | http://www.kt.rim.or.jp/%7ekbk/index.html の"Perl 5.005付属のドキュメント邦訳 " |
| Perl初心者の部屋 | http://www.harukaze.net/~mishima/perl/index.html ActivePerl版 Perl for Win32 FAQ 和訳： http://www.harukaze.net/~mishima/perl/index.html |
|
| その他 | 河馬屋二千年堂のチョー訳もあります(^^;;; 他に情報がありましたら教えてください。 |
|
Perlのドキュメントの基本形はPOD（Plain Old Document）形式です。各モジュールのドキュメントはこの形式でプログラムに埋め込まれており、どこかにいってしまうといったことがありません。POD形式がどんなものであるか確かめる一番早い方法は、まずはPerlのモジュールファイルを探してその最後をのぞいてみることでしょう。
PODはパラグラフ単位で構成されます。パラグラフには「そのままのパラグラフ(verbatim paragraph)」、「コマンド・パラグラフ(command paragraph)」、「通常のテキストブロック(ordinary text block)」の３種類があります。その行がインデントされていれば（スペースやタブで開始）「そのままのパラグラフ」、その行の先頭が「=」であれば「コマンド・パラグラフ」、そのどちらでもなければ「通常のテキストブロック」です。各パラグラフは空行によって分割されます。
PODについての詳しい説明はperlpodやその日本語訳http://www.kt.rim.or.jp/%7ekbk/perl5.005/perlpod.html などをご覧下さい。
コマンド・パラグラフのコマンド
| コマンド | 説明 |
|---|---|
| =pod =cut |
PODをプログラムの中に埋め込むときに使われます。 =podから=cutまでを、コンパイラによる解釈を抑止し、フォーマッタにはPODとして認識させます。 |
| =head1 ヘッダ =head2 ヘッダ |
=head1は第1レベルの、=head2は第2レベルのヘッダを出力します。 |
| =over 数値 =item テキスト =back |
=overはリスト項目の開始、=itemはそのリスト項目、backはリストの終了を意味します。 |
| =for X =begin X =end X |
それぞれ特定のフォーマッタにだけ渡される部分を指定します。 =forはそのパラグラフ１つを、=beginと=endはその間のすべてのパラグラフを対象とします。 |
PODでのシーケンス（通常のテキストブロック、コマンド・パラグラフの一部で利用できます）
| シーケンス | 説明 |
|---|---|
| I<テキスト> | イタリックにします |
| B<ボールド> | ボールドにします |
| S<テキスト> | スペースが入っている文字列が分割されることを抑止します。 |
| C<コード> | リテラルコードとして表示 |
| L<名前> | 指定された名前に対するリンク
|
| F<ファイル> | ファイル名として表示 |
| X<インデックス> | 索引(?) 使い方が分かりませんでした。 |
| Z<> | 幅ゼロの文字 |
| E<エスケープ> | 名前付きの文字（HTMLでのエスケープそのまま）
※HTMLに変換したところE<内容>は、&内容;といった形に変換されました。 |
POD形式で書かれたドキュメントは、ユーティリティを使ってUNIXのman形式、HTML、通常のテキストなどさまざまな形式に変換できます。最近ではPDF形式に変換できるユーティリティもあります。
またPerlインストールで提供されているユーテリティの１つh2xsは、モジュール作成のために雛型ファイルを作成してくれます。
それでは実際のPOD形式のドキュメントをテキストとHTMLに変換したものを見てみましょう。
| =head1 河馬屋のテスト ここが普通のテキストブロックになります つまりB<このように>にすると太くなります。 このようにインデントされると「そのまま」扱いになります つまりB<このように>しても太くなりません。シーケンスは無視されます。 =head2 レベル２のヘッダです =over 4 =item * これが点付きの項目なのさ =over 4 =item 1 ここは数字の入った項目なのさ =over 4 =item 何もつかない普通の箇条書き(1) =item 何もつかない普通の箇条書き(2) =back =item 2 ネストもできるってことだね =back =item * 最上位は点付き =back =for html <BR> これはHTML専用なんよ<BR> =begin html そしてここから ずっとここまではHTML専用なんよ =end html そしてここからはシーケンスのチェック：表示関係の I<イタリック>、B<太字>、C<This is a pen>、F<c:/autoexec.bat>とか エスケープシーケンス：E<lt>、E<gt>、E<Agrave> なんかわ分かりやすいでしょう。 S<This is a pen>の効果はわかりにくいかも。 L<"河馬屋のテスト">なんかは日本語が入るとちょっと心配です。 X<index>、Z<>はわかるのかな？ |
Perlをインストールすると標準で以下のPODを扱うユーティリティが提供されます。
| 名前 | 説 明 | |
|---|---|---|
| 検索・表示 | perldoc | 指定されたモジュール名、プログラム名に対応するドキュメントを検索し、表示します。 デフォルトでは、UNIXではman形式にWin32ではテキスト形式に変換します。 |
| フォーマッタ | pod2text | テキスト形式に変換します。 |
| pod2html | HTML形式に変換します。 | |
| pod2man | man形式に変換します | |
| pod2latex | LaTex形式に変換します | |
| pod2usage | POD形式を読みこんでUsageにあたる部分を表示します。 | |
このほかPDF形式に変換するものなどが別に提供されています。
変換ユーティリティのうちもっともよく使われるであろうperldocについて説明します。
perldocには大きく分けて３つのモードがあります。
(1)モジュール、プログラムを指定してそのドキュメントを表示する
perldoc [-h] [-v] [-t] [-u] [-m] [-l] [-F] [-X] ページ名|モジュール名|プログラム名
- 検索したいアイテム。ネストしたモジュール（File::Basenameのような）はFile::BasenameやFile/Basenameのどちらでも指定することができます。perlfuncのように説明のページ名も指定することができます。また"File::Basename"のために"basename"のように一部のみのや、大文字小文字の間違った指定もできます。しかしこれはより遅くなりまし、同じ部分名を持っているページが複数あったら最初の１つしか取得できません。
(2)組込関数の説明を表示する
perldoc -f 組込関数
(3)FAQをキーワード指定で表示する
perldoc -q FAQキーワード
利用できるオプションを以下の表にまとめます：
| 意味 | 説 明 | |||||||
|---|---|---|---|---|---|---|---|---|
| -h | ヘルプ | 簡単なヘルプメッセージの出力 | ||||||
| -v | 詳細説明 | 検索する手順についての途中経過を表示します。 | ||||||
| -t | テキスト出力 | フォーマットなしでテキスト形式で出力。 Windowsではこれが標準。 |
||||||
| -u | フォーマット無し | POD形式のまま出力 | ||||||
| -m | モジュール | モジュールのコードも含めて、すべて表示されます。 | ||||||
| -l | ファイル名のみ | 見つかったモジュールのファイル名を表示します。 | ||||||
| -F | ファイル | 引数をファイル名と見なし、ディレクトリでの検索は行われません。 | ||||||
| -f | perl関数 | -f オプションでperl組みこみ関数の名前を後ろに指定して呼び出すと、perlfuncからこの関数のドキュメントを取り出します。 | ||||||
| -q | perlfaq | -q オプションは正規表現を引数として取ります。perlfaq[1-9]での質問ヘッダを検索し、その正規表現に一致するエントリを出力します。 | ||||||
| -X | インデックス使用 | -X オプションはベース名が$Config{arglib}/pod.idxというファイルの中のコマンド行で与えられる名前にマッチするエントリを検索します。pod.idxファイルには完全に修飾されたファイルが1行ずつはいっていなければなりません。 | ||||||
| -U | セキュリティを甘くして実行 | perldocは適切に汚染検知が行われておらず、セキュリティの問題を持っていることが分かっているので、通常それはスーパーユーザとしては実行されません。もし-Uフラグを使えば実行できますが、限定されます。 | ||||||
メーリング・リストなどで見かけた、ドキュメントを扱う上でちょっと知っておくと便利かな思ったことをまとめます。
ご意見、ご質問はこちらの掲示板で受け付けています。
またメールは河馬屋(Nifty)にお願いします。