「Plain Old Documentation」の版間の差分
Interpretation (会話 | 投稿記録) m編集の要約なし |
「POD文書例」と「外部リンク」を大幅メンテ |
||
22行目: | 22行目: | ||
これは文法的に正しい POD であり、節の題名についても規約に従っている。 |
これは文法的に正しい POD であり、節の題名についても規約に従っている。 |
||
{| class="wikitable" |
|||
=head1 NAME |
|||
!POD文書ソース !! HTML変換結果<ref>上段はHTML表示イメージ(ウィキペディアに適した形に修正しています)、下段はHTMLソース。実際には、ヘッダタグ、節の目次リスト(デフォルト)、フッタタグも出力される。</ref> |
|||
|
|||
|- |
|||
podsample - A sample POD document |
|||
| style="width:50%; background-color: white; vertical-align:top;" rowspan="2" | |
|||
|
|||
<pre style="overflow:auto; margin-left:0"> |
|||
=head1 SYNOPSIS |
|||
=head1 名前 |
|||
|
|||
$here->isa(Piece::Of::Code); |
|||
podsample - POD文書のサンプル |
|||
print <<"END"; |
|||
This indented block will not be scanned for formatting |
|||
=head1 概要 |
|||
codes or directives, and spacing will be preserved. |
|||
END |
|||
$here->isa(Piece::Of::Code); |
|||
|
|||
print <<"END"; |
|||
=head1 DESCRIPTION |
|||
このインデントされたブロックはフォーマットされた |
|||
|
|||
コードか指示のため、走査されずに、スペースは保持 |
|||
Here's some normal text. It includes text that is |
|||
されるでしょう。 |
|||
B<bolded>, I<italicized>, U<underlined>, and |
|||
END |
|||
C<$code>-formatted. |
|||
|
|||
=head1 記述 |
|||
=head2 An Example List |
|||
|
|||
これは標準テキストです。これはB<ボールド>、I<イタリック>、 |
|||
=over 4 |
|||
U<アンダーライン>、C<$リテラルコード>のテキスト書式を |
|||
|
|||
内部に含んでいます。 |
|||
=item * This is a bulleted list. |
|||
|
|||
=head2 例の一覧 |
|||
=item * Here's another item. |
|||
|
|||
|
=over 4 |
||
|
|||
=item * これは正丸リストです。 |
|||
=begin html |
|||
|
|||
=item * ここに別口があります。 |
|||
<img src="fig1.png" align="right" alt="Figure 1." /> |
|||
<p> |
|||
=back |
|||
Here's some embedded HTML. In this block I can |
|||
include images, apply <span style="color: green"> |
|||
=begin html |
|||
styles</span>, or do anything else I can do with |
|||
HTML. POD parsers that aren't outputting HTML will |
|||
<img src="Example.png" align="right" alt="範例" /> |
|||
completely ignore it. |
|||
<p> |
|||
</p> |
|||
ここに、何らかの埋め込まれたHTMLがあります。 |
|||
|
|||
このブロックでは、画像を入れたり、 |
|||
=end html |
|||
<span style="color: green">スタイル</span>を |
|||
|
|||
適用するか、HTMLで記述しています。PODパーサは |
|||
=head1 SEE ALSO |
|||
HTML出力中にそれを完全に無視することはありません。 |
|||
|
|||
</p> |
|||
L<perlpod>, L<perldoc>, L<Pod::Parser>. |
|||
|
|||
=end html |
|||
=head1 COPYRIGHT |
|||
|
|||
=head1 参照 |
|||
Copyright 2005 [[:en:J. Random Hacker|J. Random Hacker]] <jrh@cpan.org>. |
|||
|
|||
L<perlpod>, L<perldoc>, L<Pod::Parser>. |
|||
Permission is granted to copy, distribute and/or modify this |
|||
document under the terms of the GNU Free Documentation |
|||
=head1 著作権 |
|||
License, Version 1.2 or any later version published by the |
|||
Free Software Foundation; with no Invariant Sections, with |
|||
Copyright 2005 J. Random Hacker <jrh@cpan.org>. |
|||
no Front-Cover Texts, and with no Back-Cover Texts. |
|||
|
|||
Permission is granted to copy, distribute and/or modify this |
|||
=cut |
|||
document under the terms of the GNU Free Documentation |
|||
License, Version 1.2 or any later version published by the |
|||
Free Software Foundation; with no Invariant Sections, with |
|||
no Front-Cover Texts, and with no Back-Cover Texts. |
|||
=cut |
|||
</pre> |
|||
* ActivePerl 5.8.8に最初からインストールされている構文解析器の'''pod2html'''では、U<アンダーライン>、C<$コード> には対応していません。 |
|||
* 変換ツールによってHTML変換の結果は変わってきます。 |
|||
| style="width:50%; background-color: white; vertical-align:top" | |
|||
<!-- HTMLイメージ --> |
|||
<div style="overflow:auto; margin-left:0"> |
|||
<span style="font-size:188%">名前</span><br /> |
|||
<p>podsample - POD文書のサンプル</p> |
|||
<p> |
|||
</p> |
|||
<hr /> |
|||
<div style="font-size:188%; padding-top: .5em; padding-bottom:.17em;">概要</div> |
|||
<nowiki> $here->isa(Piece::Of::Code);</nowiki><br /> |
|||
<nowiki> print <<"END";</nowiki><br /> |
|||
<nowiki> このインデントされたブロックはフォーマットされた</nowiki><br /> |
|||
<nowiki> コードか指示のため、走査されずに、スペースは保持</nowiki><br /> |
|||
<nowiki> されるでしょう。</nowiki><br /> |
|||
<nowiki> END</nowiki> |
|||
<p> |
|||
</p> |
|||
<hr /> |
|||
<div style="font-size:188%; padding-top: .5em; padding-bottom:.17em;">記述</div> |
|||
<p>これは標準テキストです。これは<strong>ボールド</strong>、 |
|||
<em>イタリック</em>、<ins>アンダーライン</ins>、<code>リテラルコード</code>の |
|||
テキスト書式を内部に含んでいます。</p> |
|||
<p> |
|||
</p> |
|||
<div style="font-size:150%; font-weight:bold; padding-top: .5em; padding-bottom:.17em;">例の一覧</div> |
|||
<ul> |
|||
<li><strong>これは正丸リストです。</strong> |
|||
<li><strong>ここに別口があります。</strong> |
|||
</ul> |
|||
[[Image:Example.png|範例|right|thumb]] |
|||
<p> |
|||
ここに、何らかの埋め込まれたHTMLがあります。 |
|||
このブロックでは、画像を入れたり、 |
|||
<span style="color: green">スタイル</span>を |
|||
適用するか、HTMLで記述しています。PODパーサは |
|||
HTML出力中にそれを完全に無視することはありません。 |
|||
</p><p> |
|||
</p> |
|||
<hr /> |
|||
<div style="font-size:188%; padding-top: .5em; padding-bottom:.17em;">参照</div> |
|||
<p><em>perlpod</em>, <em>perldoc</em>, [[/Pod/Parser|the Pod::Parser manpage]].</p> |
|||
<p> |
|||
</p> |
|||
<hr /> |
|||
<div style="font-size:188%; padding-top: .5em; padding-bottom:.17em;">著作権</div> |
|||
<p>Copyright 2005 J. Random Hacker <[mailto:jrh@cpan.org jrh@cpan.org]>.</p> |
|||
<p>Permission is granted to copy, distribute and/or modify this |
|||
document under the terms of the GNU Free Documentation |
|||
License, Version 1.2 or any later version published by the |
|||
Free Software Foundation; with no Invariant Sections, with |
|||
no Front-Cover Texts, and with no Back-Cover Texts.</p> |
|||
</div> |
|||
|- |
|||
| style="vertical-align: top" | |
|||
<!-- HTMLソース --> |
|||
<pre style="overflow:auto; margin-left:0"> |
|||
<nowiki><h1><span id="name">名前</span></h1></nowiki> |
|||
<nowiki><p>podsample - POD文書のサンプル</p></nowiki> |
|||
<nowiki><p></nowiki> |
|||
<nowiki></p></nowiki> |
|||
<nowiki><hr /></nowiki> |
|||
<nowiki><h1><span id="synopsis">概要</span></h1></nowiki> |
|||
<nowiki><pre></nowiki> |
|||
<nowiki> $here->isa(Piece::Of::Code);</nowiki> |
|||
<nowiki> print <<"END";</nowiki> |
|||
<nowiki> このインデントされたブロックはフォーマットされた</nowiki> |
|||
<nowiki> コードか指示のため、走査されずに、スペースは保持</nowiki> |
|||
<nowiki> されるでしょう。</nowiki> |
|||
<nowiki> END</pre></nowiki> |
|||
<nowiki><p></nowiki> |
|||
<nowiki></p></nowiki> |
|||
<nowiki><hr /></nowiki> |
|||
<nowiki><h1><span id="description">記述</span></h1></nowiki> |
|||
<nowiki><p>これは標準テキストです。これは<strong>ボールド</strong>、</nowiki> |
|||
<nowiki><em>イタリック</em>、<ins>アンダーライン</ins>、<code>リテラルコード</code>の</nowiki> |
|||
<nowiki>テキスト書式を内部に含んでいます。</p></nowiki> |
|||
<nowiki><p></nowiki> |
|||
<nowiki></p></nowiki> |
|||
<nowiki><h2><span id="an_example_list">例の一覧</span></h2></nowiki> |
|||
<nowiki><ul></nowiki> |
|||
<nowiki><li><strong><span id="item_this_is_a_bulleted_list_2e">これは正丸リストです。</span></strong></nowiki> |
|||
<nowiki><li><strong><span id="item_here_27s_another_item_2e">ここに別口があります。</span></strong></nowiki> |
|||
<nowiki></ul></nowiki> |
|||
<nowiki>[[Image:Example.png|範例|right|thumb]]</nowiki> |
|||
<nowiki><p></nowiki> |
|||
<nowiki> ここに、何らかの埋め込まれたHTMLがあります。</nowiki> |
|||
<nowiki> このブロックでは、画像を入れたり、</nowiki> |
|||
<nowiki> <span style="color: green">スタイル</span>を</nowiki> |
|||
<nowiki> 適用するか、HTMLで記述しています。PODパーサは</nowiki> |
|||
<nowiki> HTML出力中にそれを完全に無視することはありません。 </nowiki> |
|||
<nowiki></p><p></nowiki> |
|||
<nowiki></p></nowiki> |
|||
<nowiki><hr /></nowiki> |
|||
<nowiki><h1><span id="see_also">参照</span></h1></nowiki> |
|||
<nowiki><p><em>perlpod</em>, <em>perldoc</em>, <a href="/Pod/Parser.html">the Pod::Parser manpage</a></nowiki> |
|||
<nowiki><p></nowiki> |
|||
<nowiki></p></nowiki> |
|||
<nowiki><hr /></nowiki> |
|||
<nowiki><h1><span id="copyright">著作権</span></h1></nowiki> |
|||
<nowiki><p>Copyright 2005 J. Random Hacker <jrh@cpan.org>.</p></nowiki> |
|||
<nowiki><p>Permission is granted to copy, distribute and/or modify this </nowiki> |
|||
<nowiki>document under the terms of the GNU Free Documentation </nowiki> |
|||
<nowiki>License, Version 1.2 or any later version published by the </nowiki> |
|||
<nowiki>Free Software Foundation; with no Invariant Sections, with </nowiki> |
|||
<nowiki>no Front-Cover Texts, and with no Back-Cover Texts.</p></nowiki> |
|||
</pre> |
|||
|} |
|||
== POD における書式の詳細 == |
== POD における書式の詳細 == |
||
90行目: | 208行目: | ||
POD 内のコマンド(ディレクティブ)には、4段階の節、番号なしと番号つきのリスト、他の言語の節などがある。他の言語の節は、その言語を解釈する構文解析器による特殊な整形を可能にする。 |
POD 内のコマンド(ディレクティブ)には、4段階の節、番号なしと番号つきのリスト、他の言語の節などがある。他の言語の節は、その言語を解釈する構文解析器による特殊な整形を可能にする。 |
||
== 参考文献 == |
|||
* Wall, Larry; Christiansen, Tom; & Orwant, Jon (2000). ''Programming Perl'' (3rd ed.). Sebastopol: O'Reilly & Associates. ISBN 0-12-345678-9. |
|||
== 脚注 == |
|||
<references /> |
|||
== 関連項目 == |
== 関連項目 == |
||
* [[Perl]] |
* [[Perl]] |
||
* [[ラリー・ウォール]] |
* [[ラリー・ウォール]] |
||
== 参考文献 == |
|||
* Wall, Larry; Christiansen, Tom; & Orwant, Jon (2000). ''Programming Perl'' (3rd ed.). Sebastopol: O'Reilly & Associates. ISBN 0-12-345678-9. |
|||
== 外部リンク == |
== 外部リンク == |
||
* [http://homepage3.nifty.com/hippo2000/perltips/ Perlの小技] |
|||
* [http://search.cpan.org/~nwclark/perl-5.8.8/pod/perlpod.pod perlpod] POD形式の文書を書く人向けの説明 |
|||
** [http://homepage3.nifty.com/hippo2000/perltips/podread.htm#2. Perlドキュメントの読み方] |
|||
* [http://search.cpan.org/~nwclark/perl-5.8.8/pod/perlpodspec.pod perlpodspec] POD形式の構文解析器を書く人向けの説明 |
|||
* [http://hio.jp/ 氷魚.jp] |
|||
* Perl のマニュアルページの解釈前のPOD形式は [http://search.cpan.org/src/NWCLARK/perl-5.8.8/pod/] にある。 |
|||
** [http://hio.jp/tips/perl/perldoc-5.8.0-old/pod/perlpod.html perlpod] - <small>Perlに標準インストールされているPODの書き方マニュアル(和訳)</small> |
|||
* ディレクトリ [http://search.cpan.org/src/NWCLARK/perl-5.8.7/lib/] には POD書式が埋め込まれたモジュールが多数存在する。 |
|||
** [http://hio.jp/tips/perl/perldoc-5.8.0-old/pod/pod2html.html pod2html] - <small>POD→HTMLに変換するツールのマニュアル(和訳)</small> |
|||
* [http://search.cpan.org/perldoc?Getopt%3A%3AEuclid Getopt::Euclid module] は入力を POD タグに基づいて自動的に構文解析する。 |
|||
** [http://hio.jp/tips/perl/perldoc-5.8.0/lib/Pod/ index of /Pod] - <small>Perlに標準搭載されているPOD関連のモジュールマニュアル。Pod::××なので該当する配下モジュールをクリック。(Pod::)Htmlなどを参照。︵和訳︶</small>
|
|||
* [http://search.cpan.org/ The CPAN search site] - <small>Perlで一番信頼のおけるモジュール配布サイト。 (英語)</small> |
|||
** [http://search.cpan.org/~nwclark/perl-5.8.8/pod/perlpod.pod perlpod] - <small>POD形式の<u>文書</u>を書く人向けの説明。</small> |
|||
** [http://search.cpan.org/~nwclark/perl-5.8.8/pod/perlpodspec.pod perlpodspec] - <small>POD形式の<u>構文解析器</u>を書く人向けの説明。</small> |
|||
** [http://search.cpan.org/~rgarcia/perl-5.10.0/pod/pod2html.PL pod2html] - <small>POD→HTMLに変換するツールのマニュアル</small> |
|||
** [http://search.cpan.org/~dland/Pod-Html-1.09_01/Html.pm Pod::Html] - <small>POD→HTMLに変換する標準モジュールのマニュアル</small> |
|||
** [http://search.cpan.org/perldoc?Getopt%3A%3AEuclid Getopt::Euclid module] - <small>入力を POD タグに基づいて自動的に構文解析する。</small> |
|||
** [http://search.cpan.org/src/NWCLARK/perl-5.8.8/pod/ Index of /src/NWCLARK/perl-5.8.8/pod/] - <small>Perl のマニュアルページの解釈前のPOD形式を公開。</small> |
|||
** [http://search.cpan.org/src/NWCLARK/perl-5.8.7/lib/ Index of /src/NWCLARK/perl-5.8.7/lib/] - <small>ディレクトリにPOD書式が埋め込まれたモジュールが多数存在する。</small> |
|||
[[Category:Perl]] |
[[Category:Perl]] |
2008年5月3日 (土) 17:36時点における版
特徴
POD は必要十分な文法を持つ単純で明快な言語として設計された。書体、画像、色、表などの機構を意図的に排除し、必要な機能だけを持つようにしている。その目的は以下の通りである。 ●構文解析が簡単である。 ●他の言語︵HTML や TeX︶への変換が簡単である。 ●サンプルコードを含めるのが簡単である。 ●フォーマッタで整形しなくても︵ソースコードのままで︶読むのが簡単である。 ●書くのが簡単である。さもなくばプログラマは文書を書きたがらない。 perlpod の筆者は﹁POD形式は本を書くのには不十分である﹂と書いているが、PODを拡張した書式で本が実際に書かれている。この拡張版PODには表や脚注の機能があり、オライリーメディアから出ているいくつかのPerlに関する本で使われた。例えば、ラリー・ウォール、ジョン・オーワント、トム・クリスチャンセンの Programming Perl︵邦題は﹃プログラミング Perl﹄︶が有名である。POD を若干拡張修正した版として MOD があり、Mark Jason Dominus による Higher-Order Perl で使われた。利用
POD は Perl 関連での文書作成に使われている。Perl 自身、ほとんど全ての公開されている Perl モジュール、多くのスクリプト言語、多くの設計文書、Perl.com などの Perl 関連 Webサイトにある多くの記事、Parrot仮想機械などで使われている。 POD形式のソースコードをそのまま読むことは少ないが、そのままでも読めるように設計されている。一般に、perldoc ツールを使って読んだり、UNIXマニュアル形式に変換したり、HTML形式に変換したりする。 純粋な POD ファイルの拡張子は.pod
だが、POD は通常 Perl のソースコードに埋め込んで使われるため、拡張子は .
pl
または .pm
であることが多い。Perl インタプリタの構文解析器はソースコード内の POD 部分を無視するよう設計されている。
POD文書例
これは文法的に正しい POD であり、節の題名についても規約に従っている。POD文書ソース | HTML変換結果[1] |
---|---|
=head1 名前 podsample - POD文書のサンプル =head1 概要 $here->isa(Piece::Of::Code); print <<"END"; このインデントされたブロックはフォーマットされた コードか指示のため、走査されずに、スペースは保持 されるでしょう。 END =head1 記述 これは標準テキストです。これはB<ボールド>、I<イタリック>、 U<アンダーライン>、C<$リテラルコード>のテキスト書式を 内部に含んでいます。 =head2 例の一覧 =over 4 =item * これは正丸リストです。 =item * ここに別口があります。 =back =begin html <img src="Example.png" align="right" alt="範例" /> <p> ここに、何らかの埋め込まれたHTMLがあります。 このブロックでは、画像を入れたり、 <span style="color: green">スタイル</span>を 適用するか、HTMLで記述しています。PODパーサは HTML出力中にそれを完全に無視することはありません。 </p> =end html =head1 参照 L<perlpod>, L<perldoc>, L<Pod::Parser>. =head1 著作権 Copyright 2005 J. Random Hacker <jrh@cpan.org>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. =cut
|
名前
podsample - POD文書のサンプル
リテラルコード の
テキスト書式を内部に含んでいます。
例の一覧
●これは正丸リストです。
●ここに別口があります。
![]() |
<h1><span id="name">名前</span></h1> <p>podsample - POD文書のサンプル</p> <p> </p> <hr /> <h1><span id="synopsis">概要</span></h1> <pre> $here->isa(Piece::Of::Code); print <<"END"; このインデントされたブロックはフォーマットされた コードか指示のため、走査されずに、スペースは保持 されるでしょう。 END</pre> <p> </p> <hr /> <h1><span id="description">記述</span></h1> <p>これは標準テキストです。これは<strong>ボールド</strong>、 <em>イタリック</em>、<ins>アンダーライン</ins>、<code>リテラルコード</code>の テキスト書式を内部に含んでいます。</p> <p> </p> <h2><span id="an_example_list">例の一覧</span></h2> <ul> <li><strong><span id="item_this_is_a_bulleted_list_2e">これは正丸リストです。</span></strong> <li><strong><span id="item_here_27s_another_item_2e">ここに別口があります。</span></strong> </ul> [[Image:Example.png|範例|right|thumb]] <p> ここに、何らかの埋め込まれたHTMLがあります。 このブロックでは、画像を入れたり、 <span style="color: green">スタイル</span>を 適用するか、HTMLで記述しています。PODパーサは HTML出力中にそれを完全に無視することはありません。 </p><p> </p> <hr /> <h1><span id="see_also">参照</span></h1> <p><em>perlpod</em>, <em>perldoc</em>, <a href="/Pod/Parser.html">the Pod::Parser manpage</a> <p> </p> <hr /> <h1><span id="copyright">著作権</span></h1> <p>Copyright 2005 J. Random Hacker <jrh@cpan.org>.</p> <p>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.</p> |
POD における書式の詳細
B<bolded t
ext>
となる。
●1文字の大文字の後に2つ以上の不等号(<<)が続き、その後に整形すべき内容、さらにその後に同じ個数の不等号(>>)が続く。例えば、B<< bolded text >>
となる。これは内容に不等号が含まれる場合に使われる。
POD 内のコマンド︵ディレクティブ︶には、4段階の節、番号なしと番号つきのリスト、他の言語の節などがある。他の言語の節は、その言語を解釈する構文解析器による特殊な整形を可能にする。