名前¶
perlpodstyle - Perl POD style guide
perlpodstyle - Perl POD スタイルガイド
説明¶
These are general guidelines for how to write POD documentation for Perl scripts and modules, based on general guidelines for writing good UNIX man pages. All of these guidelines are, of course, optional, but following them will make your documentation more consistent with other documentation on the system.
これらは、優れた UNIX の man ページを書くための一般的なガイドラインに 基づいた、Perl スクリプトとモジュール用の POD 文書を書くための 一般的なガイドラインです。 これらのガイドラインはすべて、もちろんオプションですが、 これらに従うことで、システム上の他の文書との一貫性が高まります。
The name of the program being documented is conventionally written in bold (using B<>) wherever it occurs, as are all program options. Arguments should be written in italics (I<>). Function names are traditionally written in italics; if you write a function as function(), Pod::Man will take care of this for you. Literal code or commands should be in C<>. References to other man pages should be in the form manpage(section)
or L<manpage(section)>
, and Pod::Man will automatically format those appropriately. The second form, with L<>, is used to request that a POD formatter make a link to the man page if possible. As an exception, one normally omits the section when referring to module documentation since it's not clear what section module documentation will be in; use L<Module::Name>
for module references instead.
文書化されるプログラムの名前は、すべてのプログラムオプションと同様に、 (B<>を使用して)太字で表記されます。 引数は斜体(I<>)で表記されます。 関数名は伝統的に斜体(I<>)で表記されます; 関数を function() として記述した場合、Pod::Man がこの処理を行います。 リテラルコードまたはコマンドは C<> で記述されます。 他のマニュアルページへの参照は manpage(section)
または L<manpage(section)> の形式で記述すると、 Pod::Man が自動的に適切に書式設定します。 2 番目の形式は L<> で、POD フォーマッタが可能であれば マニュアルページへのリンクを作成するように要求するために使用されます。 例外として、モジュール文書を参照する場合、どのセクションにモジュール文書が 含まれるかが明確でないため、通常はセクションを省略します; 代わりにモジュール参照には
L<Module::Name> を使ってください。
References to other programs or functions are normally in the form of man page references so that cross-referencing tools can provide the user with links and the like. It's possible to overdo this, though, so be careful not to clutter your documentation with too much markup. References to other programs that are not given as man page references should be enclosed in B<>.
他のプログラムや関数への参照は、通常、man ページ参照の形式で行われますので、 クロスリファレンスツールはユーザにリンクなどを提供することができます。 ただし、これはやり過ぎの可能性もありますので、マークアップが多すぎて文書が 乱雑にならないように注意してください。 man ページ参照として提供されていない他のプログラムへの参照は、B<>で 囲む必要があります。
The major headers should be set out using a =head1
directive, and are historically written in the rather startling ALL UPPER CASE format; this is not mandatory, but it's strongly recommended so that sections have consistent naming across different software packages. Minor headers may be included using =head2
, and are typically in mixed case.
メジャーヘッダは =head1
指示子を使用して設定する必要があり、 歴史的には、かなり驚くべき「全て大文字」形式で書かれています; これは必須ではありませんが、セクションが異なるソフトウェアパッケージ間で 一貫した名前を持つように強くお勧めします。 マイナーヘッダは =head2
を使用して含めることができ、 通常は大文字と小文字が混在しています。
The standard sections of a manual page are:
マニュアルページの標準セクションは次のとおりです:
- NAME
-
Mandatory section; should be a comma-separated list of programs or functions documented by this POD page, such as:
必須セクション: 次のように、この POD ページで文書化されているプログラムムまたは機能を コンマで区切ったリストにします:
foo, bar - programs to do something
Manual page indexers are often extremely picky about the format of this section, so don't put anything in it except this line. Every program or function documented by this POD page should be listed, separated by a comma and a space. For a Perl module, just give the module name. A single dash, and only a single dash, should separate the list of programs or functions from the description. Do not use any markup such as C<> or B<> anywhere in this line. Functions should not be qualified with
()
or the like. The description should ideally fit on a single line, even if a man program replaces the dash with a few tabs.マニュアルページインデクサはこのセクションの形式に非常にうるさいことが 多いので、この行以外に何も入れないでください。 この POD ページで文書化されているすべてのプログラムや関数は、 コンマとスペースで区切って列挙する必要があります。 Perl モジュールの場合は、モジュール名を指定してください。 プログラムや関数のリストを説明と区切るのは、一つだけのダッシュです。 この行には、C<> や B<> などのマークアップを 使用しないでください。 関数は
()
などで修飾しないでください。 man プログラムがダッシュをいくつかのタブで置き換えたとしても、 説明は理想的には 1 行に収まるようにしてください。 - SYNOPSIS
-
A short usage summary for programs and functions. This section is mandatory for section 3 pages. For Perl module documentation, it's usually convenient to have the contents of this section be a verbatim block showing some (brief) examples of typical ways the module is used.
プログラムと関数の簡単な使用方法の要約です。 このセクションはセクション 3 ページでは必須です。 Perl モジュールの文書では、このセクションの内容を、 モジュールの典型的な使用方法の(簡単な)例を示す逐語的なブロックにしておくと 便利です。
- DESCRIPTION
-
Extended description and discussion of the program or functions, or the body of the documentation for man pages that document something else. If particularly long, it's a good idea to break this up into subsections
=head2
directives like:プログラムや関数の詳細な説明や説明、あるいは 他のマニュアルページのマニュアルの本文。 特に長い場合は、以下のようにサブセクション
=head2
指示子に 分割することを勧めます:=head2 Normal Usage =head2 Advanced Features =head2 Writing Configuration Files
or whatever is appropriate for your documentation.
この文書に適したものであれば何でも構いません。
For a module, this is generally where the documentation of the interfaces provided by the module goes, usually in the form of a list with an
=item
for each interface. Depending on how many interfaces there are, you may want to put that documentation in separate METHODS, FUNCTIONS, CLASS METHODS, or INSTANCE METHODS sections instead and save the DESCRIPTION section for an overview.モジュールの場合、モジュールによって提供されるインターフェイスの文書は、 通常、インターフェイスごとに
=item
を含むリストの形式で、 ここに置かれます。 インターフェイスの数に応じて、文書を個別の METHODS セクション、 FUNCTIONS セクション、CLASS METHODS セクション、または INSTANCE METHODS セクションに配置し、 概要を説明するために DESCRIPTION セクションを保存します。 - OPTIONS
-
Detailed description of each of the command-line options taken by the program. This should be separate from the description for the use of parsers like Pod::Usage. This is normally presented as a list, with each option as a separate
=item
. The specific option string should be enclosed in B<>. Any values that the option takes should be enclosed in I<>. For example, the section for the option --section=manext would be introduced with:プログラムによって使用される各コマンドラインオプションの詳細な説明です。 これは、Pod::Usage のようなパーサを使用するための説明とは 別にする必要があります。 これは通常、リストとして表示され、各オプションは個別の
=item
として 示されます。 特定のオプション文字列は B<> で囲む必要があります。 オプションが取る値は I<> で囲む必要があります。 たとえば、オプション --section=manext のセクションは、次のように 記述されます。=item B<--section>=I<manext>
Synonymous options (like both the short and long forms) are separated by a comma and a space on the same
=item
line, or optionally listed as their own item with a reference to the canonical name. For example, since --section can also be written as -s, the above would be:同義語オプション(ショート形式とロング形式の両方)は、同じ
=item
行で コンマとスペースで区切られているか、オプションで 正規名への参照と共に独自の項目としてリストされています。 たとえば、--section は -s と記述することもできるため、 上の式は次のようになります。=item B<-s> I<manext>, B<--section>=I<manext>
Writing the short option first is recommended because it's easier to read. The long option is long enough to draw the eye to it anyway and the short option can otherwise get lost in visual noise.
短いオプションは読みやすいので、最初に書くことをお勧めします。 長いオプションはとにかく目を引くのに十分な長さであり、さもなければ 短いオプションは視覚的なノイズで失われる可能性があります。
- RETURN VALUE
-
What the program or function returns, if successful. This section can be omitted for programs whose precise exit codes aren't important, provided they return 0 on success and non-zero on failure as is standard. It should always be present for functions. For modules, it may be useful to summarize return values from the module interface here, or it may be more useful to discuss return values separately in the documentation of each function or method the module provides.
成功した場合のプログラムまたは関数の戻り値。 正確な終了コードが重要でないプログラムでは、このセクションは省略できます; ただし、成功した場合は 0 を返し、失敗した場合は 0 以外を返すことが標準です。 このセクションは、関数に対しては常に存在する必要があります。 モジュールの場合は、ここでモジュールインターフェイスからの 戻り値を要約すると便利です。 または、モジュールが提供する各関数またはメソッドの文書で戻り値を 個別に説明すると便利です。
- ERRORS
-
Exceptions, error return codes, exit statuses, and errno settings. Typically used for function or module documentation; program documentation uses DIAGNOSTICS instead. The general rule of thumb is that errors printed to
STDOUT
orSTDERR
and intended for the end user are documented in DIAGNOSTICS while errors passed internal to the calling program and intended for other programmers are documented in ERRORS. When documenting a function that sets errno, a full list of the possible errno values should be given here.例外、エラーリターンコード、終了ステータス、および errno の設定。 通常、関数またはモジュールの文書に使用されます。 プログラムの文書では、代わりに DIAGNOSTICS が使用されます。 一般的な経験則では、
STDOUT
またはSTDERR
に出力されたエンドユーザ向けの エラーは DIAGNOSTICS に記録されますが、呼び出し元プログラム内部に渡された 他のプログラマ向けのエラーは ERRORS に記録されます。 errno を設定する関数を文書化する場合は、可能な errno 値の完全なリストを ここに示す必要があります。 - DIAGNOSTICS
-
All possible messages the program can print out and what they mean. You may wish to follow the same documentation style as the Perl documentation; see perldiag(1) for more details (and look at the POD source as well).
プログラムが出力する可能性のあるすべてのメッセージとその意味。 Perl の文書と同じ文書スタイルに従うことをお勧めします; 詳細は perldiag(1) を参照してください(POD ソースも参照してください)。
If applicable, please include details on what the user should do to correct the error; documenting an error as indicating "the input buffer is too small" without telling the user how to increase the size of the input buffer (or at least telling them that it isn't possible) aren't very useful.
該当する場合は、ユーザがエラーを修正するために何をすべきかについての 詳細を含めてください; ユーザに入力バッファのサイズを増やす方法を教えずに (あるいは少なくともそれが不可能であることを伝えずに) "入力バッファが小さすぎる"というエラーを記録することは あまり有用ではありません。
- EXAMPLES
-
Give some example uses of the program or function. Don't skimp; users often find this the most useful part of the documentation. The examples are generally given as verbatim paragraphs.
プログラムまたは関数の使用例をいくつか挙げてください。 ここをけちらないでください; ユーザはしばしばこれが文書の中で最も役に立つ部分であると知ることになります。 例は一般的にそのままな段落として与えられています。
Don't just present an example without explaining what it does. Adding a short paragraph saying what the example will do can increase the value of the example immensely.
例が何をするかを説明せずに単に例を示さないでください。 例が何をするかを説明する短い段落を追加することで、 例の価値を大幅に高めることができます。
- ENVIRONMENT
-
Environment variables that the program cares about, normally presented as a list using
=over
,=item
, and=back
. For example:プログラムが考慮する環境変数; 通常、
=over
、=item
、および=back
を 使用してリストとして表示されます。 次に例を示します。=over 6 =item HOME Used to determine the user's home directory. F<.foorc> in this directory is read for configuration details, if it exists. =back
Since environment variables are normally in all uppercase, no additional special formatting is generally needed; they're glaring enough as it is.
環境変数は通常すべて大文字なので、特別な書式設定を追加する 必要はありません; そのままで十分目立っています。
- FILES
-
All files used by the program or function, normally presented as a list, and what it uses them for. File names should be enclosed in F<>. It's particularly important to document files that will be potentially modified.
プログラムまたは関数によって使用されるすべてのファイル (通常はリストとして表示されます)とその使用目的。 ファイル名は F<> で囲む必要があります。 変更される可能性のあるファイルを文書化することは特に重要です。
- CAVEATS
-
Things to take special care with, sometimes called WARNINGS.
WARNINGS と呼ばれることもある、特別な注意が必要なもの。
- BUGS
-
Things that are broken or just don't work quite right.
壊れているもの、あるいは正しく動作しないもの。
- RESTRICTIONS
-
Bugs you don't plan to fix. :-)
修正する予定のないバグ。 :-)
- NOTES
-
Miscellaneous commentary.
その他の注釈。
- AUTHOR
-
Who wrote it (use AUTHORS for multiple people). It's a good idea to include your current e-mail address (or some e-mail address to which bug reports should be sent) or some other contact information so that users have a way of contacting you. Remember that program documentation tends to roam the wild for far longer than you expect and pick a contact method that's likely to last.
誰が書いたのか(複数の人に対しては AUTHORS を使用してください)。 ユーザが連絡できるように、現在の電子メールアドレス (またはバグレポートの送信先となる電子メールアドレス) またはその他の連絡先情報を含めることをお勧めします。 プログラムの文書は予想よりもはるかに長い時間にわたって 公開される傾向があることを覚えておいて、 長く続く可能性の高い連絡方法を選択してください。
- HISTORY
-
Programs derived from other sources sometimes have this. Some people keep a modification log here, but that usually gets long and is normally better maintained in a separate file.
他のソースから派生したプログラムはこの項目がある場合があります。 ここに変更ログを保存している人もいますが、通常は長くなり、 別のファイルに保存した方がよいでしょう。
- COPYRIGHT AND LICENSE
-
For copyright
著作権について。
Copyright YEAR(s) YOUR NAME(s)
(No, (C) is not needed. No, "all rights reserved" is not needed.)
(いいえ、(C)は不要です。 いいえ、"all rights reserved" は不要です。 )
For licensing the easiest way is to use the same licensing as Perl itself:
ライセンスを付けるための最も簡単な方法は、Perl 自体と 同じライセンスを使用することです:
This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.
This makes it easy for people to use your module with Perl. Note that this licensing example is neither an endorsement or a requirement, you are of course free to choose any licensing.
これにより、皆さんのモジュールを Perl で簡単に使用できるようになります。 このライセンスの例は推薦でも要件でもないことに注意してください; もちろん、どのようなライセンスでも自由に選択できます。
- SEE ALSO
-
Other man pages to check out, like man(1), man(7), makewhatis(8), or catman(8). Normally a simple list of man pages separated by commas, or a paragraph giving the name of a reference work. Man page references, if they use the standard
name(section)
form, don't have to be enclosed in L<> (although it's recommended), but other things in this section probably should be when appropriate.man(1)、man(7)、makewhatis(8)、catman(8)などの、 チェックするべきその他の man ページ。 通常、manページをコンマで区切った単純なリストか、 参考文献の名前を示す段落です。 man ページ参照は、標準の
name(section)
形式を使用している場合は、 L<>で囲む必要はありませんが(推奨されています)、 このセクションの他の項目は適切な場合に含める必要があります。If the package has a mailing list, include a URL or subscription instructions here.
パッケージにメーリングリストがある場合は、ここに URL または 購読手順を含めてください。
If the package has a web site, include a URL here.
パッケージに Web サイトがある場合は、ここに URL を追加します。
Documentation of object-oriented libraries or modules may want to use CONSTRUCTORS and METHODS sections, or CLASS METHODS and INSTANCE METHODS sections, for detailed documentation of the parts of the library and save the DESCRIPTION section for an overview. Large modules with a function interface may want to use FUNCTIONS for similar reasons. Some people use OVERVIEW to summarize the description if it's quite long.
オブジェクト指向ライブラリまたはモジュールの文書では、 CONSTRUCTORS セクションと METHODS セクション、または CLASS METHODS セクションと INSTANCE METHODS セクションを使用して ライブラリの各部の詳細な文書を作成し、概要を説明するために DESCRIPTION セクションを保存する必要がある場合があります。 関数インタフェースを持つ大規模なモジュールでも、同様の理由で FUNCTIONS を使用する必要がある場合があります。 非常に長い場合は、説明を要約するために OVERVIEW を使用する人もいます。
Section ordering varies, although NAME must always be the first section (you'll break some man page systems otherwise), and NAME, SYNOPSIS, DESCRIPTION, and OPTIONS generally always occur first and in that order if present. In general, SEE ALSO, AUTHOR, and similar material should be left for last. Some systems also move WARNINGS and NOTES to last. The order given above should be reasonable for most purposes.
セクションの順序は様々ですが、NAME は常に最初のセクションでなければならず (そうでないといくつかの man ページシステムを壊してしまいます)、 NAME、SYNOPSIS、DESCRIPTION、OPTIONSは一般に常に最初に、もしあれば その順序で現れます。 一般に、SEE ALSO、AUTHOR、および同様の資料は最後に残しておくべきです。 システムによっては、WARNINGS や NOTES を最後に移動することもあります。 上記の順序は、ほとんどの目的に対して妥当なものでなければなりません。
Some systems use CONFORMING TO to note conformance to relevant standards and MT-LEVEL to note safeness for use in threaded programs or signal handlers. These headings are primarily useful when documenting parts of a C library.
システムによっては、関連する標準への適合性を示すために CONFORMING TO を使用し、 スレッド化されたプログラムやシグナルハンドラで使用するための 安全性を示すために MT-LEVEL を使用します。 これらの見出しは主に、C ライブラリの一部を文書化する場合に役立ちます。
Finally, as a general note, try not to use an excessive amount of markup. As documented here and in Pod::Man, you can safely leave Perl variables, function names, man page references, and the like unadorned by markup and the POD translators will figure it out for you. This makes it much easier to later edit the documentation. Note that many existing translators will do the wrong thing with e-mail addresses when wrapped in L<>, so don't do that.
最後に、一般的な注意点として、過剰な量のマークアップを 使用しないようにしてください。 ここと Pod::Man で説明されているように、Perl の変数、関数名、man ページ 参照などをマークアップで装飾されないままにしておくことは安全であり、 POD トランスレータがそれを理解してくれます。 これにより、後で文書を編集するのがずっと簡単になります。 多くの既存のトランスレータは、L<> にラップされた 電子メールアドレスに対して間違った操作を行うことに注意してください; したがって、そのような操作は行わないでください。
SEE ALSO¶
For additional information that may be more accurate for your specific system, see either man(5) or man(7) depending on your system manual section numbering conventions.
ご使用のシステムでより正確な追加情報については、 システムマニュアルセクションの番号付け規則に応じて man(5) または man(7) を参照してください。
This documentation is maintained as part of the podlators distribution. The current version is always available from its web site at <http://www.eyrie.org/~eagle/software/podlators/>.
この文書は podlators ディストリビューションの一部として管理されています。 最新バージョンは常に <http://www.eyrie.org/~eagle/software/podlators/> の Web サイトから入手できます。
作者¶
Russ Allbery <rra@stanford.edu>, with large portions of this documentation taken from the documentation of the original pod2man implementation by Larry Wall and Tom Christiansen.
Russ Allbery<rra@stanford.edu>; この文書の大部分は、Larry Wall and Tom Christiansen によるオリジナルの pod2man 実装の文書から引用されています。
コピーライト & ライセンス¶
Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 Russ Allbery <rra@stanford.edu>.
This documentation is free software; you may redistribute it and/or modify it under the same terms as Perl itself.
POD ERRORS¶
Hey! The above document had some coding errors, which are explained below:
- Around line 50:
-
Unterminated C<C<...>> sequence