CPAN での一般的な Pod
CPAN 上では次のような構成の Pod ドキュメンテーションがよくみられます。プログラムコードの合間に Pod を置くことは少なく、基本的にはコードを記述したファイルの末尾にトークン「 __END__ 」と「 空行 」を置いて Pod を開始します。
... Some Modules code
1;
__END__
=encoding utf8
=head1 NAME
Dummy::Module - Common Pod documentation on CPAN
=head1 SYNOPSIS
use Dummy::Moduls;
my $val = Dummy::Module->some_method('arg1', 'arg2');
my $obj = Dummy::Module->new;
my $val = $obj->some_method('arg1', 'arg2');
=head1 DESCRIPTION
This module is a dummy for explaining the Pod.
=head1 METHODS
=over 2
=item * new
How to use the method new().
my $obj = Dummy::Module->new;
=item * some_method
How to use the method some_method().
my $val = Dummy::Module->some_method('arg1', 'arg2');
or
my $obj = Dummy::Module->new;
my $val = $obj->some_method('arg1', 'arg2');
=back
=head1 Ohter Items
=over
=item 1. other item(1)
=item 2. other item(2)
=item 3. other item(3)
=back
=head1 SEE ALSO
Information that the user should refer to.
L<ohter::module1>, L<other::module2>
=head1 AUTHOR
The author of this module.
Who Am I C<< <authors@address> >>
=head1 COPYRIGHTorLICENSE
Present the copyright and/or license.
=cut
トランスレータ
Pod のルールに従って記述したドキュメントは用途に応じたトランスレータ (aka フォーマッタ) によって任意の形式に整形できます。主なトランスレータには次のものがあります。
トランスレータ形式
pod2textテキスト
pod2htmlHTML
pod2manman (nroff(1), troff(1))
pod2latexLaTeX
pod2fmFrameMaker (おそらく Adobe)
例: pod2text
pod2text を利用して「 CPAN での一般的な Pod 」を整形すると次のような出力がえられます。
$ pod2text pod_file
NAME
Dummy::Module - Common Pod documentation on CPAN
SYNOPSIS
use Dummy::Moduls;
my $val = Dummy::Module->some_method('arg1', 'arg2');
my $obj = Dummy::Module->new;
my $val = $obj->some_method('arg1', 'arg2');
DESCRIPTION
This module is a dummy for explaining the Pod.
METHODS
* new
How to use the method new().
my $obj = Dummy::Module->new;
* some_method
How to use the method some_method().
my $val = Dummy::Module->some_method('arg1', 'arg2');
or
my $obj = Dummy::Module->new;
my $val = $obj->some_method('arg1', 'arg2');
Ohter Items
1. other item(1)
2. other item(2)
3. other item(3)
SEE ALSO
Information that the user should refer to.
ohter::module1, other::module2
AUTHOR
The author of this module.
Who Am I "<authors@address>"
COPYRIGHTorLICENSE
Present the copyright and/or license.
例: pod2man
pod2man を利用して「 CPAN での一般的な Pod 」を整形した場合の例です。pod2man は「 nroff 」または「 troff 」用のデータを出力するので、ターミナル上で出力をチェックしたい場合は出力を nroff にパイプすると見やすくなります。
$ pod2man pod_file | nroff -man
Pod_FILE(1) User Contributed Perl Documentation Pod_FILE(1)
NAME
Dummy::Module - Common Pod documentation on CPAN
SYNOPSIS
use Dummy::Moduls;
my $val = Dummy::Module->some_method('arg1', 'arg2');
my $obj = Dummy::Module->new;
my $val = $obj->some_method('arg1', 'arg2');
DESCRIPTION
This module is a dummy for explaining the Pod.
METHODS
· new
How to use the method new().
my $obj = Dummy::Module->new;
· some_method
How to use the method some_method().
my $val = Dummy::Module->some_method('arg1', 'arg2');
or
my $obj = Dummy::Module->new;
my $val = $obj->some_method('arg1', 'arg2');
Ohter Items
1. other item(1)
2. other item(2)
3. other item(3)
SEE ALSO
Information that the user should refer to.
ohter::module1, other::module2
AUTHOR
The author of this module.
Who Am I "<authors@address>"
COPYRIGHTorLICENSE
Present the copyright and/or license.
perl v5.28.1 2020-10-14 Pod_FILE(1)
Perl 文書を検索して表示する「 perldoc 」
Pod 形式の Perl ドキュメントを検索・表示するツールとして「
perldoc 」があります。
perldoc は「 組み込み関数 」や「 FAQ 」など Perl に関する様々なドキュメントや、各種モジュール内に記述された Pod を確認できます。Perl 関連のドキュメントは「
perltoc 」(Table Of Contents) で一覧できます。
perldoc の中身 (The guts) は「
Pod::Perldoc 」です。
perldoc の引数に Pod を含むファイルを指定すれば、システムにインストールされている Pod::Perldoc のフォーマッタクラス (Formatter Class) を利用して Pod を整形します。
$ perldoc pod_file
フォーマッタクラスには「 Pod::Perldoc::Totext 」をはじめとした様々なトランスレータが用意されています。perldoc をオプション「 -D 」付きで実行すればどのフォーマッタクラスを使っているかを確認出来ます。
$ perldoc -D pod_file
環境変数「 PERLDOCDEBUG 」を使うとさらに詳細な情報を出力します。
$ PERLDOCDEBUG=5 perldoc pod_file
環境変数に与える整数は大きいほど詳細な情報を得られますが、Pod::Perldoc のコードを確認する限り最大値は「 5 」であるようです。
perldoc ドキュメントの「
オプション 」にあるとおり、オプション「 -o output-formatname 」または「 -M module-name 」を使うことで perldoc が使うフォーマッタクラスを任意に指定することもできます。
なお、手元の環境 Ubuntu 18.04.5 では「 Pod::Perldoc::ToText 」が、macOS Catalina では「 Pod::Text::Color::Delight 」がデフォルトのフォーマッタとして使われています。
Pod の開始と終了
Pod はコマンド「 =pod 」で開始できますが、実際には例えば「 =head1 」や「 =encoding encodingname 」など他のコマンドでも開始できます。ただし Pod を開始するコマンドの前後には空行が必要です。
Pod の終了は「 =cut 」を使います。なお「 =cut 」では Pod を開始することは出来ません。
エンコーディング
上記で例示した Pod ではコマンド「 =encoding encodingname 」を利用して Pod を開始しています。
=encoding utf-8
このコマンドは英語 (US-ASCII) のみで記述する場合は不要です。しかし日本語を含む非 US-ASCII のデータを含む場合は、少なくともその文字が出現する以前の行にこのコマンドを置かなければなりません。つまりドキュメントの最初に置けば問題ありません。
もちろん US-ASCII のみで記述する場合にこのコマンドを使っても問題ありません。
「
Encode 」が認識するものであれば任意のエンコードを利用可能です。
ヘッダとコマンドパラグラフ
ドキュメントの見出しにはコマンド「 =head 」を使います。コマンド「 =head 」には次の種類があります。
=head1
=head2
=head3
=head4
コマンド「 =head 」だけに限らず「 m/\A=[a-zA-Z]/ 」で始まる行、つまりコマンドの段落を「 コマンドパラグラフ 」と呼びます。
いくつかのコマンドでは次のように続けて文章を置くことができます。また、いくつかのコマンドではその文章に「 フォーマッティングコード 」を使うことができます。
=head1 Formatting code
=head2 Object Atrributes
=head3 Possible Values for C<$/>
=head4 What B<Not> to Do!
ここで使われているフォーマッティングコードはコードを表す「 C<> 」と太字を表す「 B<> 」です。これを例えば pod2html で整形すると次のような出力が得られます。
<h1 id="Formatting-code">Formatting code</h1>
<h2 id="Object-Atrributes">Object Atrributes</h2>
<h3 id="Possible-Values-for">Possible Values for <code>$/</code></h3>
<h4 id="What-Not-to-Do">What <b>Not</b> to Do!</h4>
オーディナリー (普通の) パラグラフ
「 オーディナリーパラグラフ 」(ordinary paragraph) はつまり「 普通の段落 」です。オーディナリーパラグラフは行の先頭から文章を書き出しますが、そのパラグラフの前後には空行が必要です。
例えば次の部分はオーディナリーパラグラフを含みます。
=head1 NAME
Dummy::Module - Common Pod documentation on CPAN
この項目はコマンドパラグラフ「 =head1 NAME 」とオーディナリーパラグラフ「 Dummy::Module - Common Pod documentation on CPAN 」から成っています。
同様に次の「 This module is ... 」もオーディナリーパラグラフです。
=head1 DESCRIPTION
This module is a dummy for explaining the Pod.
オーディナリーパラグラフには任意のフォーマッティングコードが使えます。
=head1 Formatting code in the ordinary paragraph
This I<paragraph> is B<ordinay> and uses a formatting code.
リスト
Pod におけるリストはコマンド「 =over ... =back 」の領域内にコマンド「 =item 」を配置して記述します。
=head1 METHODS
=over 2
=item * new
How to use the method new().
my $obj = Dummy::Module->new;
=item * some_method
How to use the method some_method().
my $val = Dummy::Module->some_method('arg1', 'arg2');
or
my $obj = Dummy::Module->new;
my $val = $obj->some_method('arg1', 'arg2');
=back
コマンド「 =over 2 」の「 2 」はインデントレベルを指定する値で非ゼロの整数のみを受付けますが、この指定を無視するフォーマッタも存在するそうです。デフォルトのインデントレベルは「 4 」です。
ここでは「 =over ... =back 」の領域に置かれた 2 つのコマンド「 =item 」がリストのアイテムになります。コマンド「 =item 」に続く「 * 」は箇条書きのための「 点 」を出力します。
コマンド「 =item 」のリストアイテムは次のように番号付きにすることもできますし、そのコマンドパラグラフ内でフォーマッティングコードを使うこともできます。
=over
=item 1. C<< $thing->stuff(I<dodad>) >>
=item 2. Using C<$|> to Control Buffering
=back
バーベイタムパラグラフ
次のうち先頭にスペースを含む「 my $obj = Dummy::Module->new; 」の行は「 バーベイタムパラグラフ 」(verbatim paragraph) です。
=item * new
How to use the method new().
my $obj = Dummy::Module->new;
バーベイタムパラグラフは「 逐語的 」すなわち「 そのまま 」でレンダリングされる段落です。
バーベイタムパラグラフの行は「 リテラルのスペース 」または「 タブ 」(8 カラム仮定) で始まります。
バーベイタムパラグラフは「 そのまま 」表示されることを意図したものなので、記号やスペースが重要な意味を持つ「 コードブロック 」としてよく使われます。
pod2html ではバーベイタムパラグラフを「 <pre><code>[any space]VERBATIM PARAGRAPH</code></pre> 」に変換します。
「 perldoc -o html pod_file 」を実行した場合は「 Pod::Simple::HTML 」によってバーベイタムパラグラフが「 <pre>[any space]VERBATIM PARAGRAPH</pre> 」に変換されました。
pod2FORMAT と perldoc の違い
Pod ドキュメントはコマンド「 =pod 」で開始してコマンド「 =cut 」で終了できますが、その扱いについて「 pod2FORMAT 」系のスクリプトと「 perldoc 」ではやや異なる挙動をすることがわかりました。
例えば空のファイルに次を記述してファイル名「 podfile 」として保存します。これはコマンドパラグラフ (=pod, =cut) とオーディナリーパラグラフ (This is the Pod) のみから成っています。
=pod
This is the Pod
=cut
このファイル podfile を「 pod2FORMAT 」系のスクリプトで処理すれば、次のように Pod ドキュメントとして問題なく整形できます。
$ pod2man podfile | nroff -man
PodFILE(1) User Contributed Perl Documentation PodFILE(1)
This is the the Pod ?
perl v5.28.1 2020-10-15 PodFILE(1)
この記述は Pod の構文をチェックするスクリプト「 podchecker 」による判定でも「 syntax OK 」として評価されます。
しかし、これを「 perldoc 」(中身は Pod::Perldoc) で処理しようとすると次のように「 ドキュメントが見つからない 」と表示されプログラムが終了します。
$ perldoc podfile
No documentation found for "podfile".
ところが、次のようにコマンド「 =pod 」の代わりにコマンド「 =head 」を使うと perldoc でも問題なく整形できるようになります。
=head1 the Pod
This is the Pod
=cut
Pod 単独でドキュメントを記述することはほとんどないと思いますが、ざっと確認した限り、このようなコンテンツを perldoc で処理する場合はファイルの先頭行がコマンド「 =head 」始まる必要があるようです (=pod や =over で開始すると "No documentation found")。
実のところこれ (perldoc が =pod で開始する Pod ドキュメントを見つけられない) はドキュメント perlpod の「
Perl モジュールへの pod の埋め込み 」にある以下の記述どおりの挙動です。
Perl モジュールとスクリプトに Pod ドキュメントを埋め込むことができます。 ドキュメントを空行および“=head1”コマンドで始め、“=cut”と空行で終えます。
しかし同じドキュメント perlpod「
コマンド段落 」の以下の記述とは矛盾する挙動でもあります。
"=pod" コマンドはそれ自身ではほとんど何もしませんが、 Perl (と Pod フォーマッタ)に Pod ブロックがここから始まることを示します。
NEXT
次回は、唐突に Apache HTTP サーバの構成ファイル「 httpd.conf 」にデフォルトで記述されたコメントを確認します。
参考情報は書籍「 続・初めての Perl 改訂版 」, 「 Effective Perl 第 2 版 」を中心に perldoc, Wikipedia および各 Web サイト。それと詳しい先輩。
目次 - Perl Index