Perl Perl_7 Pod

2020年11月17日

Perl Pod (ポド) の利用 (d176)

目次 - Perl Index

Theme

Perl について、復習を兼ねて断片的な情報を掲載して行く連載その d176 回。

今回は、Perl でドキュメントを記述する際に (特にプログラムコードの中で) よく使われるマークアップ言語「 Pod 」(ポド) の実際の記述とその利用方法を確認します。

Pod の概要・仕様および各種フォーマッティングコードなどは前回の「 Perl マークアップ言語 Pod (ポド) (d175) 」で確認しました。

なお、Pod のマークアップ機能は Perl 関連に限らず任意のドキュメントを記述する際にも使えます。

CPAN での一般的な Pod

トランスレータ

例: pod2text

例: pod2man

Perl 文書を検索して表示する「 perldoc 」

Pod の開始と終了

エンコーディング

ヘッダとコマンドパラグラフ

オーディナリー (普通の) パラグラフ

リスト

バーベイタムパラグラフ

pod2FORMAT と perldoc の違い

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	テキスト
pod2html	HTML
pod2man	man (nroff(1), troff(1))
pod2latex	LaTeX
pod2fm	FrameMaker (おそらく 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.



=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 ブロックがここから始まることを示します。

次回は、唐突に Apache HTTP サーバの構成ファイル「 httpd.conf 」にデフォルトで記述されたコメントを確認します。

参考情報は書籍「続・初めての Perl 改訂版」, 「 Effective Perl 第 2 版」を中心に perldoc, Wikipedia および各 Web サイト。それと詳しい先輩。

目次 - Perl Index

同じカテゴリー（Perl）の記事

Perl mp2 翻訳 Web コンテンツ圧縮の FAQ (d228)
Perl mp2 翻訳既知のブラウザのバグの回避策をいくつか (d227)
Perl mp2 翻訳 Perl と Apache でのキュートなトリック (d226)
Perl mp2 翻訳テンプレートシステムの選択 (d225)
Perl mp2 翻訳大規模 E コマースサイトの構築 (d224)
Perl mp2 翻訳チュートリアル (d223)

コメント: 0

名前:
メール:
URL:
情報を記憶:
コメント:	上の画像に書かれている文字を入力して下さい
	＜ご注意＞書き込まれた内容は公開され、ブログの持ち主だけが削除できます。確認せずに書込

blog20100901