Loading article…
Plain Old Documentation ( pod ) は、Perlプログラミング言語、モジュール、およびプログラムを文書化するために使用される軽量マークアップ言語です。
Podは、必要最低限の構文を備えたシンプルでクリーンな言語として設計されています。フォント、画像、色、表などの機能は意図的に省略されています。その目標の一部は以下のとおりです。
表や脚注をサポートする拡張版のpodであるPseudoPODは、O'Reilly & AssociatesによっていくつかのPerl関連書籍の制作に使用されており、中でもLarry Wall、Tom Christiansen、Jon Orwant共著の『Programming Perl』が最も有名である。
Pod を使用すると、ユーザー向けのドキュメントに適したマニュアルページを簡単に作成できます。一方、Python のDocstringや Java のJavadocなどの他のドキュメントシステムは、ユーザー向けドキュメントにも使用できますが、ソフトウェアプロジェクトのソースコードに関する開発者向けのドキュメントの生成を容易にするように設計されています。
Podは、Perlの世界におけるほとんどのドキュメント作成に使用されている言語です。これには、Perl自体、ほぼすべての公開モジュール、多くのスクリプト、ほとんどの設計ドキュメント、Perl.comやその他のPerl関連Webサイトの多くの記事、そしてParrot仮想マシンが含まれます。
Pod はフォーマットツールを使わずに読めるように設計されていますが、生のまま読まれることはほとんどありません。代わりに、perldocツール、またはUnixのマニュアルページやWeb標準のHTMLページに変換されます。
Perl以外のコンテキストでもpodを使用することが可能です。たとえば、bashスクリプトに簡単なドキュメントを追加し、それを簡単にmanページに変換することができます。[ 1 ]このような使用法では、pod部分を隠すために言語固有のハックに依存しています。たとえば、(bashでは) PODセクションの前に、:<<=cutbashのno-op:コマンドを呼び出すことで機能する行を追加し、Podブロック全体をヒアドキュメントとして入力します。
純粋な pod ファイルは通常拡張子 を持ちます.podが、pod は主に Perl コード内で直接使用され、通常は拡張子.plとが使用されます.pm。(Perlインタープリタのパーサーは、Perl コード内の pod を無視するように設計されています。) ソース コード ファイルでは、ドキュメントは一般的に__END__マーカーの後に配置されます (これにより、一部のエディタで構文ハイライトがコメントとして表示されるようになります)。
ポッドは、Pod::Simple::Wiki を使用して、他の形式 (たとえば、WikiWikiWeb、Kwiki、TWiki、UseModWiki、TiddlyWiki、Textile、MediaWiki、MoinMoin 、 Confluenceなど) などのさまざまなWiki形式に簡単に変換できます。
この文書は構文的に正しい文書であり、セクション命名に関する主要な慣例にも従おうとしています。[ 2 ]
=head1 名前My::Module- サンプルモジュール =head1 概要useMy::Module;my$object=My::Module->new();print$object->as_string;=head1 説明 このモジュールは実際には存在しません。 唯一の目的のために作られた PODの仕組みを実演します。 =head2 メソッド ＝12歳以上 =アイテム C<新規> 新しいオブジェクトを返します。My::Module=アイテム C<as_string> 文字列化された表現を返します オブジェクト。これは主にデバッグ用です。 目的。 =戻る =head1 ライセンス これは芸術的ライセンスに基づいて公開されています。 L<perlartistic>を参照してください。 =head1 著者 Juerd - L< http://juerd.nl/ > =head1 関連項目 L<perlpod>、L<perlpodspec> =カット
Pod ファイルは、 Latin-1やUTF-8などのASCII互換エンコーディングで記述されます。Pod パーサーは、解析対象のファイルが pod で始まっていないことを常に想定し、pod ディレクティブが見つかるまで全ての行を無視します。pod ディレクティブは行頭にあり、全て等号で始まります。その後、pod パーサーは、"=cut" ディレクティブを含む行に遭遇するまで、後続の全ての行が pod であると想定します。その後の内容は、パーサーが別の pod ディレクティブに遭遇するまで無視されます。したがって、言語のパーサーが pod を認識して無視する方法を知っていれば、pod を実行可能なソースコードと混在させることができます。
Pod コンテンツは、空行によって段落に分割されます。タブやスペースなどの空白文字で始まる段落は「逐語段落」とみなされ、書式設定されません。これらはサンプルコードやASCIIアートなどに使用されます。等号で始まる段落は「コマンド段落」です。等号の直後に続く英数字のシーケンスは Pod ディレクティブとして扱われ、段落の残りの部分はそのディレクティブに従って書式設定されます。一部のディレクティブは、後続の段落にも影響します。段落が等号または空白以外の文字で始まる場合は、「通常の段落」とみなされます。
通常の段落とコマンド段落の内容の両方が、書式コードのために解析されます。pod の書式設定は非常にシンプルで、主に太字、斜体、下線、等幅フォント、およびその他のいくつかの形式に限定されています。pod ドキュメント間、または同じドキュメント内の別のセクションにリンクするためのコードが存在します。書式コードは次のいずれかで構成されます。
B<bolded text>、またはB<< bolded text >>。この形式は、書式設定コードが終了する大なり記号を含むコードスニペットによく使用されます。pod のコマンドには、4 レベルの見出し、箇条書きと番号付きリスト、およびセクションを別の言語で記述するコマンドが含まれています。最後の機能を使用すると、対応するパーサーに特別な書式設定を適用できます。