Perl本身自帶了很豐富的文檔,如果把它們都打印出來,恐怕要耗費大量紙墨。我們試圖清點過,但數到2000頁左右的時候就數不清了(不用擔心,我們用虛擬打印機計算頁面數量,這樣不會對樹木造成威脅,挺環保的)。
Perl文檔中包含大量有價值的信息,這些文檔絕對值得仔細品讀,哪怕只花一點功夫,學會如何從這些文檔中查找所需的資料也是值得的。要從這些文檔中迅速找到需要的內容,除了要具備相關的知識外,得力的工具也必不可少。
1. perldoc文檔閱讀器
perldoc這個命令能搜索Perl安裝目錄樹中內嵌文檔的Perl模塊文件(擴展名為.pm)、.pod結尾的POD文檔(見條款82),以及已安裝的各種Perl工具的文檔。該命令會將它找到的文檔格式化后顯示出來。讓我們先從閱讀perldoc自身的文檔開始吧:
- % perldoc perldoc
- PERLDOC(1) User Contributed Perl Documentation
- NAME
- C<perldoc> - Look up Perl documentation in pod format.
- SYNOPSIS
- C<perldoc> [-h] [-v] [-t] [-u] [-m] [-l]
- ……省略了剩余內容……
一般來說,將文檔的名稱作為參數傳遞給perldoc命令,即可查閱該文檔。比如下面,給定文檔名稱perltoc,就會顯示所有內置文檔的目錄:
- % perldoc perltoc
你也許會對perlsyn文檔的內容感興趣,該文檔主要描述Perl的基本語法:
- % perldoc perlsyn
如果想閱讀關於Perl內置函數的用法,可以查看perlfunc文檔:
- % perldoc perlfunc
至少得把perlfunc文檔通讀一遍,才能大致了解Perl都能提供些什么功能。當然,不需要把它們都記下來,只要在大腦中有個印象就夠了。比如說,只要知道Perl有個內置函數可以處理/etc/passwd文件,但具體是哪個,可以到perlfunc文檔里找。要是覺得滾動這么長的頁面太過麻煩,只要記得內置函數的名字,就可以用-f開關指定,直接閱讀該函數相關的內容:
- % perldoc -f split
也可以用perldoc來閱讀模塊內嵌的文檔,只需提供模塊名作為參數即可:
- % perldoc Pod::Simple
如果想了解這個模塊安裝在什么地方,可以用-l(小寫的L)開關打印該模塊的路徑:
- % perldoc -l Pod::Simple
如果要查看模塊源代碼,可以用-m開關:
- % perldoc -m Pod::Simple
Perl文檔還包括了FAQ,可以在其中找到許多常見問題的解答。雖然有個在線版本可以閱讀,但命令行的perldoc有個好處,就是可以用-q開關搜索相關主題,非常方便。比如有關隨機數的處理,可以試試這個:
- % perldoc -q random
2. 在線文檔
在寫本書時,http://perldoc.perl.org/是最好的Perl在線文檔站點。它包含了Perl最近幾個版本的核心文檔(包括HTML和PDF格式),不只如此,它還會記錄你曾經看過哪些文檔。
但該站點並不提供所有模塊的文檔。想要看到所有模塊的文檔,可以到CPAN Search(http://search.cpan.org/)和Kobes's Search(http://kobesearch.cpan.org/)這兩個站點去看看。這兩個站點都提供CPAN的網頁查詢界面。許多人甚至覺得直接訪問以上站點,比閱讀本機附帶的文檔還要方便。
CPAN Search很有用,尤其是它在每個模塊頁面中都提供了其他工具鏈接。其中一個工具有類似grep的功能,用它可以方便地在某個模塊不同的發行版本中搜索特定內容。比如想要跟蹤某個出錯信息來自哪個模塊中的哪個文件,就可以用它來試一試。
AnnoCPAN(http://annocpan.org/)是另一個提供模塊文檔的站點。但它的出發點是讓任何人都有機會對模塊文檔本身添加評注,或是給作者或其他用戶留言。這個功能在文檔信息不全或者不正確、不完整的情況下顯得特別有用。
3. 本地文檔
在本地也能夠實現部分和CPAN Search站點類似的功能。借助CPAN::Mini::Webserver模塊,我們可以在本地搭建一台Web服務器,然后通過瀏覽器查閱自己的MiniCPAN庫(見條款66)。如果運行的是Apache Web服務器,你還可以用Apache::Perldoc模塊,在Web界面中調用本地的perldoc命令。
此外,Pod::POM::Web模塊也能讓你以Web方式查看本地文檔。以mod_perl或者CGI腳本的形式在Apache上運行都沒問題,或者干脆直接使用其內置的Web服務器:
- % perl -MPod::POM::Web -e "Pod::POM::Web->server