ドキュメントが少ないというのは本当？

Perlは、歴史が長いわりに有用なドキュメントが少ない、という声を耳にすることがあります。また、ネット上に落ちている情報は断片的すぎるとか、古いものが多すぎるという苦情も聞こえてきます。なるほど、まわりを見回してみれば、たしかにいまさらこれはいかがか、という情報もたくさん見受けられますし、そのような世代間ギャップを埋めるのがこの連載のひとつの目的でもあります。

でも、その一方で、見るべき場所が違うんじゃないか、という気もするのです。Perlの情報は、そんなところには落ちていませんよ、と。

今回は、そのようなPerlのドキュメントまわりの話にスポットを当てていきましょう。

たしかに書籍の数は減っていますが

Perlの情報がない、古い、といわれる背景のひとつに、当今の出版事情が大きく関与しているのは間違いありません。筆者が把握できた範囲内で過去10年間に国内で出版されたPerl関連の本の数を数えてみると、Perl 5.8が登場した2002年（Perl 15歳）に29冊もの単行本が出たのを最後に、出版点数は長らく減少傾向が続いてきました[1]⁠。

もっとも、これがそのままPerlの人気と連動していたかというと、そうとも言い切れないのがむずかしいところ。2005年以降の退潮にバブル的な人気を誇ったRuby on Railsの影響があったのは間違いないでしょうが、内外から500人近い参加者を集めるYAPC::Asiaのチケットがわずか3日で売り切れてしまうくらいの需要はあるのですから、これまで「モダンな本」がなかなか出てこなかった原因は、むしろ20世紀末から続く出版界の不況とそれによる出版傾向の変化や、日本のPerlユーザがブログという個人メディアで旬の話題を消費することに慣れてしまった結果、最低でも2～3ヶ月のタイムラグが生じてしまう出版コストに不満を感じてしまうようになった（2002年というのはMovable Typeの日本語化パッチが出回り始めた年でもあります⁠）⁠、等々の問題の方が大きかったようにも感じられます。

単行本10冊分のドキュメント

ただし、Perlの情報が断片的なものになってしまう（ように見える）のは、そのような出版界の事情ばかりが原因ではありません。わかっている人にしてみれば、Perlにはすでに膨大なドキュメントの蓄積があるから屋上屋を架す必要がないだけ、でもあるのです。

これもまた忘れられがちなことですが、CPANというのは、ソースコードだけでなく、ドキュメントの集積地でもあります。

個々のモジュールのドキュメントについてはふだんよく見るCPAN検索サイトから確認できることをご存知の方も多いでしょうが、CPANに集まっているのはそれだけではありません。いわゆるPerlのコアドキュメントと呼ばれるものや、各モジュールのクックブックのようなものも結構登録されているのです。

しかも、これらのドキュメントは、ネット上だけの存在ではありません。みなさんが使っているコンピュータのなかにもどんどんインストールされていきます。

試しに、お手元のマシンで下記のコマンドをタイプしてみてください。

> perldoc perltoc

これはインストールされているコアドキュメントの目次一覧を表示するものですが、実はこれだけですでに400KBほど、英単語の数に直して5万6000語強の分量があります[2]⁠。

実際にどこにファイルが格納されているか確認したい方は、下記のコマンドを実行するか（lオプションはファイルの位置を教えてくれるものです⁠）⁠、あるいはCPAN検索サイトでperlのソースを確認してみるとよいでしょう。

> perldoc -l perltoc

これらのコアドキュメントはディストリビューション内のpodディレクトリにまとまっているのですが、Perl 5.10.0の場合で、ファイル数が117個、総単語数は75万語弱（Perlのコード例を除いた正味の英単語数で64万語⁠）⁠。単行本にして優に10冊分のドキュメントが、困ったときの味方として同梱されているわけです。

個別のモジュールにしても、そう。たとえば前回紹介したように、MooseチームはPerl Foundationの助成金を受けてドキュメントの整備を行いましたが、その結果、Mooseのドキュメントは、podファイルにまとめられているマニュアル類だけで3万5000語（用例含めて4万5000語⁠）⁠。API仕様書ともいえるモジュール本体のドキュメント類を含めると5万語（用例込みで6万語）を越えるほどになりました。

Catalystにしても、4万4000語ほど（用例込みで6万語）のマニュアルに、1万3000語（同1万5000語）ほどのAPI仕様書が用意されていますし、DBIx::Classもマニュアル、API込みで2万8000語（同3万6000語）くらいの説明は書かれています。

たしかにこれらの大きなフレームワークについては、これでもまだ書かれていない部分はたくさんありますし、ソースの変更が速すぎてドキュメントが追いついていない部分も見受けられますが、このように基本的な説明はそれぞれすでに単行本1冊分くらいは存在しているのですから、ブログなどに書かれるネタはどうしても、そこから外れた枝葉末節や、マニュアルを読むよりソースを読んだほうが早いようなディープなネタ、バッドノウハウの類に限定されてしまいがちになりますし、また、そうでなければ、その人は（プログラマの三大美徳とされる）怠惰さが足りない、ということになるでしょう。

一般に、プログラマの世界ではわからないことがあったらまず検索をかけてみなさい（汚い言葉を使うなら「ググレカス⁠」⁠）と言われるわけですが、Perlの場合、Googleのような検索エンジンに頼るのは本当に最後の手段でしかありません。困ったらCPANに聞け、というのがPerlユーザの合い言葉であり、必要なものは全部インストールしておくから、あとは必要なときに自分の読みやすい形に整形して読んでね、というのがPerlユーザの怠惰のあり方。メーテルリンクの童話ではありませんが、幸せの青い鳥はもっと身近なところにいるのです[3]⁠。

perldocコマンドも進化しています

Perl 5は、その黎明期から常にドキュメントを重視してきました。

ドキュメントをHTMLとUNIXのman形式に整形するスクリプトは1994年の誕生当時から添付されてきましたし、1996年にリリースされたPerl 5.002では、ドキュメントをテキストに整形するためのPod::Textや、manコマンドがない環境でもドキュメントを閲覧しやすくするためにperldocというコマンドが導入されました。

このコマンドを使うと、先にも紹介したコアドキュメントだけでなく、モジュールやプラグマのドキュメント部分のみを抽出して画面に表示することもできるようになりますし、「⁠-m」オプションを使えばソースコードそのものを確認することもできる――ということくらいは、すでにおなじみのことでしょう。

翌1997年にリリースされた5.004では、Pod::HTMLというモジュールが導入されたほか、perldocコマンドが進化して、「⁠-f」オプションで組み込み関数のマニュアルも表示できるようになりました（これは、実際にはperlfuncというコアドキュメントの一部を表示する機能です⁠）⁠。また、翌1998年のPerl 5.005ではさらに「-q」オプションが追加され、Perl FAQの見出しから関連語を検索できるようになっています[4]⁠。

2000年に登場したPerl 5.6系列では、Podまわりのモジュールが再編されて、Pod::Parserやpodlatorsといったパッケージがコアに入りましたし、2003年リリースの5.8.1ではperldocコマンドが一新され、あらたにPod::Perldocというモジュールがコアに登録されました（このときにもperldocコマンドにはさまざまなオプションが追加されています⁠）⁠。

2006年リリースの5.9.3ではPod::SimpleとPod::Escapesというモジュールがコア入りして、さらに表現力豊かな変換ができるようになったほか、perldocコマンドには「-L」という言語を指定するオプションが追加されました。

この「-L」オプションは、イタリアのPerlユーザグループが中心になって進めているPerlドキュメント翻訳プロジェクトの一環として生まれたもの。このオプションを使うと、適切な翻訳ファイルがインストールされている場合は、通常の英語版ドキュメントではなく、翻訳済みドキュメントのほうが表示されるようになります。

> perldoc -L <言語コード> <ドキュメント名など>

いまのところ多少なりともプロジェクトが進行しているのはイタリア語とフランス語、リトアニア語くらいで、日本語版はありませんし（いまはCPANから削除されているようですが、一時は中国版も存在していました⁠）⁠、エンコード系の機能はまだ入っていないようなので、日本語版を用意してもかならずしもうまく閲覧できるとは限らないのですが、perldocコマンドを実行するだけでそのまま日本語のドキュメントが読めるようになる日が来るのも、そう先のことではないかもしれません[5]⁠。

英語の壁と過去の翻訳

Perlの（というかCPANの）世界は英語が公用語ですから、本格的にPerlを利用するのであればある程度英語の読み書きはできたほうが得ですが、大量の英文を読めるようになるまでにはそれなりに手間も時間もかかります。もちろんPerlの場合はソースコードがあるのですから、そちらを読めば済むこととはいえ、毎回すべてのモジュールのすべてのソースを理解しないと先に進めないようでは、生産性に問題が出ても不思議はありません。

そのため、国内でも以前から、有志の方々が独自にドキュメントの翻訳を行ってきたのですが、そのほとんどは個人で利用しているサーバのディレクトリ内にひっそりと保管されているため、その存在そのものを知らないとなかなかたどりつけないことが問題になっていました。

そのような問題を解決するために登場したのが、Japanized Perl Resources Projectという翻訳プロジェクトと、いまは利用できなくなっていますが、CPAN.jpで提供されていたperl日本語ドキュメント検索です（2002年⁠）⁠。

このJapanized Perl Resources Projectの成果は、SourceForge.JP内のプロジェクトページだけでなく、perldoc.jpというドメインからも確認できるようになっていますが、2009年4月現在で56のコアドキュメントと、245のモジュールが翻訳済み。この数年は登録メンバーが忙しくなったこともあって活動は停滞気味のようですが、freemlのメーリングリストを見る限り、いまも淡々と翻訳を続けてくださっている方はいるので、興味を持たれた方は参加してみるのもよいかもしれません。

JPA翻訳プロジェクト

ただ、perldoc.jpの活動はいまのところ個人の厚意に依存する部分が大きいため、需要はあっても規模の大きいモジュールのドキュメントなどはなかなか翻訳されない、また、ドキュメントが古くなっても改訂されないといった問題を抱えていました。

そのため、先日発足したJapan Perl Associationでは、事業の一環としてPerl関連ドキュメントの充実をはかる計画が進められています[6]⁠。

既存のperldoc.jpとの整合性をどう取るかなど、解決すべき課題は残っていますが、この事業が軌道に乗れば、日本語で読めるドキュメントの安定供給につながることは間違いありません。関心のある方はぜひJPAにお問い合わせいただければと思います。