POD(Plain Old Documentation)の書き方
Perlはソースコードの中にドキュメントを埋め込むことができます。このソース内ドキュメントのことをPODといい独自の記述方法があります。
Perlにはモジュールを公開できるCPANというサイトがありますが、CPANに公開されるモジュールのドキュメントはすべてPODで書かれています。
感覚的にはPODはHTMLを簡易に記述できて、自動的にHTMLに変換されると考えましょう。
文字コード
英数字以外をドキュメントに含める場合は文字コードを設定する必要があります。「UTF-8」で記述する場合はドキュメントの先頭に以下のように書きます。
=encoding utf8
ヘッダ
HTMLのh1からh6に対応します。
=head1 ヘッダ1 =head2 ヘッダ2 =head3 ヘッダ3 =head4 ヘッダ4 =head5 ヘッダ5 =head6 ヘッダ6
PODを書くときの注意点ですが、必ず次の行には改行を入れる必要があります。たとえば次の記述はうまくいきません。
=head1 ヘッダ1 =head2 ヘッダ2
ソースコード
ソースコードを記述するにはソースコードに対して、先頭に空白を設定します。これはHTMLのpreに該当します。
use DBIx::Custom; my $dbi = DBIx::Custom->connect(...);
空白は1でも2でも4でも、自由な幅でかまいません。
リスト
リストの記述方法を解説します。
順序なしリスト
順序なしリストは次のように記述します。
「=over」の後ろにはリストのインデント幅を指定します。「=item」の後ろに「*」を指定すると順序なしリストになります。「=over」の終わりを示すために最後に「=back」と書く必要があります。
=over 4 =item * 項目1 =item * 項目2 =item * 項目3 =back
順序リスト
順序リストは次のように記述します。順序なしリストとほとんど同じですが、「=item」の後ろに数字を指定すると順序リストになります。
=over 4 =item 1 項目1 =item 2 項目2 =item 3 項目3 =back
書式
PODで書式を設定する方法です。
太字
太字を設定するには「B<>」という記述を使います。
B<あいうえお>
斜体
斜体を設定するには「I<>」という記述を使います。
I<あいうえお>
プログラムテキスト
テキストの中の関数名などをそれとわかる形でフォーマットしたい場合は「C<>」が使えます。
C<select>
ハイパーリンク
ハイパーリンクの記法を解説します。
他のCPANモジュール
他のCPANモジュールへのリンクを記述するには「L<>」を使って以下のように書きます。Object::Simpleのページへのリンクになります。
L<Object::Simple>
一般のURLへのリンク
一般のURLは「L<テキスト|URL>」のように記述します。
L<Perlゼミ|http://d.hatena.ne.jp/perlcodesample>
PODの開始と終わり
PODの開始は「=pod」でPODの終わりは「=cut」で終わります。
=pod ドキュメント =cut
一般的には「=head1」などのPODの記述が一つでも出現するとPODが開始されるので「=pod」と書くことはあまりありません。ただしソースコードの中で複数行コメントを使うときは、この記述方法が利用されます。
文字エスケープ
PODで利用される記号を使いたい場合はエスケープする必要があります。エスケープは「」を使って行うことができます。
E<lt> < E<gt> >
FAQ
PODに関するFAQです。
PODでテーブルを記述することはできますか。
PODでテーブルを記述することはできません。
PODで画像を利用することはできますか。
PODで画像を利用することはできません。
CPANモジュールにおける慣習的な書き方を教えてください
CPANモジュールのドキュメントは一般的に次のような書き方になっています。
=head1 NAME モジュール名 - モジュールの簡単な解説 =head1 SYNOPSIS ソースコードのサンプル =head1 DESCRIPTION モジュールの解説 =head1 METHODS =head2 メソッド1 =head2 メソッド2 =head1 AUTHOR 著者名 =head1 COPYRIGHT & LICENSE 著作権表示 =cut
PODの詳細なドキュメント
PODの詳細なドキュメントについては、PerlのPODに関するドキュメントを見てください。