=encoding euc-jp =head1 NAME =begin original perlpodstyle - Perl POD style guide =end original perlpodstyle - Perl POD スタイルガイド =head1 DESCRIPTION =begin original 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. =end original これらは、優れた UNIX の man ページを書くための一般的なガイドラインに 基づいた、Perl スクリプトとモジュール用の POD 文書を書くための 一般的なガイドラインです。 これらのガイドラインはすべて、もちろんオプションですが、 これらに従うことで、システム上の他の文書との一貫性が高まります。 =begin original The name of the program being documented is conventionally written in bold (using BEE) wherever it occurs, as are all program options. Arguments should be written in italics (IEE). 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 CEE. References to other man pages should be in the form C or Cmanpage(section)E>, and Pod::Man will automatically format those appropriately. The second form, with LEE, 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 CModule::NameE> for module references instead. =end original 文書化されるプログラムの名前は、すべてのプログラムオプションと同様に、 (BEEを使用して)太字で表記されます。 引数は斜体(IEE)で表記されます。 関数名は伝統的に斜体(IEE)で表記されます; 関数を function() として記述した場合、Pod::Man がこの処理を行います。 リテラルコードまたはコマンドは CEE で記述されます。 他のマニュアルページへの参照は C または Cmanpage(section)E の形式で記述すると、 Pod::Man が自動的に適切に書式設定します。 2 番目の形式は LEE で、POD フォーマッタが可能であれば マニュアルページへのリンクを作成するように要求するために使用されます。 例外として、モジュール文書を参照する場合、どのセクションにモジュール文書が 含まれるかが明確でないため、通常はセクションを省略します; 代わりにモジュール参照には CModule::NameE を使ってください。 =begin original 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 BEE. =end original 他のプログラムや関数への参照は、通常、man ページ参照の形式で行われますので、 クロスリファレンスツールはユーザにリンクなどを提供することができます。 ただし、これはやり過ぎの可能性もありますので、マークアップが多すぎて文書が 乱雑にならないように注意してください。 man ページ参照として提供されていない他のプログラムへの参照は、BEEで 囲む必要があります。 =begin original The major headers should be set out using a C<=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 C<=head2>, and are typically in mixed case. =end original メジャーヘッダは C<=head1> 指示子を使用して設定する必要があり、 歴史的には、かなり驚くべき「全て大文字」形式で書かれています; これは必須ではありませんが、セクションが異なるソフトウェアパッケージ間で 一貫した名前を持つように強くお勧めします。 マイナーヘッダは C<=head2> を使用して含めることができ、 通常は大文字と小文字が混在しています。 =begin original The standard sections of a manual page are: =end original マニュアルページの標準セクションは次のとおりです: =over 4 =item NAME =begin original Mandatory section; should be a comma-separated list of programs or functions documented by this POD page, such as: =end original 必須セクション: 次のように、この POD ページで文書化されているプログラムムまたは機能を コンマで区切ったリストにします: foo, bar - programs to do something =begin original 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 CEE or BEE anywhere in this line. Functions should not be qualified with C<()> or the like. The description should ideally fit on a single line, even if a man program replaces the dash with a few tabs. =end original マニュアルページインデクサはこのセクションの形式に非常にうるさいことが 多いので、この行以外に何も入れないでください。 この POD ページで文書化されているすべてのプログラムや関数は、 コンマとスペースで区切って列挙する必要があります。 Perl モジュールの場合は、モジュール名を指定してください。 プログラムや関数のリストを説明と区切るのは、一つだけのダッシュです。 この行には、CEE や BEE などのマークアップを 使用しないでください。 関数は C<()> などで修飾しないでください。 man プログラムがダッシュをいくつかのタブで置き換えたとしても、 説明は理想的には 1 行に収まるようにしてください。 =item SYNOPSIS =begin original 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. =end original プログラムと関数の簡単な使用方法の要約です。 このセクションはセクション 3 ページでは必須です。 Perl モジュールの文書では、このセクションの内容を、 モジュールの典型的な使用方法の(簡単な)例を示す逐語的なブロックにしておくと 便利です。 =item DESCRIPTION =begin original 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 C<=head2> directives like: =end original プログラムや関数の詳細な説明や説明、あるいは 他のマニュアルページのマニュアルの本文。 特に長い場合は、以下のようにサブセクション C<=head2> 指示子に 分割することを勧めます: =head2 Normal Usage =head2 Advanced Features =head2 Writing Configuration Files =begin original or whatever is appropriate for your documentation. =end original この文書に適したものであれば何でも構いません。 =begin original 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 C<=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. =end original モジュールの場合、モジュールによって提供されるインターフェイスの文書は、 通常、インターフェイスごとに C<=item> を含むリストの形式で、 ここに置かれます。 インターフェイスの数に応じて、文書を個別の METHODS セクション、 FUNCTIONS セクション、CLASS METHODS セクション、または INSTANCE METHODS セクションに配置し、 概要を説明するために DESCRIPTION セクションを保存します。 =item OPTIONS =begin original 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 L. This is normally presented as a list, with each option as a separate C<=item>. The specific option string should be enclosed in BEE. Any values that the option takes should be enclosed in IEE. For example, the section for the option B<--section>=I would be introduced with: =end original プログラムによって使用される各コマンドラインオプションの詳細な説明です。 これは、L のようなパーサを使用するための説明とは 別にする必要があります。 これは通常、リストとして表示され、各オプションは個別の C<=item> として 示されます。 特定のオプション文字列は BEE で囲む必要があります。 オプションが取る値は IEE で囲む必要があります。 たとえば、オプション B<--section>=I のセクションは、次のように 記述されます。 =item B<--section>=I =begin original Synonymous options (like both the short and long forms) are separated by a comma and a space on the same C<=item> line, or optionally listed as their own item with a reference to the canonical name. For example, since B<--section> can also be written as B<-s>, the above would be: =end original 同義語オプション(ショート形式とロング形式の両方)は、同じ C<=item> 行で コンマとスペースで区切られているか、オプションで 正規名への参照と共に独自の項目としてリストされています。 たとえば、B<--section> は B<-s> と記述することもできるため、 上の式は次のようになります。 =item B<-s> I, B<--section>=I =begin original 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. =end original 短いオプションは読みやすいので、最初に書くことをお勧めします。 長いオプションはとにかく目を引くのに十分な長さであり、さもなければ 短いオプションは視覚的なノイズで失われる可能性があります。 =item RETURN VALUE =begin original 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. =end original 成功した場合のプログラムまたは関数の戻り値。 正確な終了コードが重要でないプログラムでは、このセクションは省略できます; ただし、成功した場合は 0 を返し、失敗した場合は 0 以外を返すことが標準です。 このセクションは、関数に対しては常に存在する必要があります。 モジュールの場合は、ここでモジュールインターフェイスからの 戻り値を要約すると便利です。 または、モジュールが提供する各関数またはメソッドの文書で戻り値を 個別に説明すると便利です。 =item ERRORS =begin original 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 C or C 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. =end original 例外、エラーリターンコード、終了ステータス、および errno の設定。 通常、関数またはモジュールの文書に使用されます。 プログラムの文書では、代わりに DIAGNOSTICS が使用されます。 一般的な経験則では、C または C に出力されたエンドユーザ向けの エラーは DIAGNOSTICS に記録されますが、呼び出し元プログラム内部に渡された 他のプログラマ向けのエラーは ERRORS に記録されます。 errno を設定する関数を文書化する場合は、可能な errno 値の完全なリストを ここに示す必要があります。 =item DIAGNOSTICS =begin original 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). =end original プログラムが出力する可能性のあるすべてのメッセージとその意味。 Perl の文書と同じ文書スタイルに従うことをお勧めします; 詳細は perldiag(1) を参照してください(POD ソースも参照してください)。 =begin original 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. =end original 該当する場合は、ユーザがエラーを修正するために何をすべきかについての 詳細を含めてください; ユーザに入力バッファのサイズを増やす方法を教えずに (あるいは少なくともそれが不可能であることを伝えずに) "入力バッファが小さすぎる"というエラーを記録することは あまり有用ではありません。 =item EXAMPLES =begin original 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. =end original プログラムまたは関数の使用例をいくつか挙げてください。 ここをけちらないでください; ユーザはしばしばこれが文書の中で最も役に立つ部分であると知ることになります。 例は一般的にそのままな段落として与えられています。 =begin original 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. =end original 例が何をするかを説明せずに単に例を示さないでください。 例が何をするかを説明する短い段落を追加することで、 例の価値を大幅に高めることができます。 =item ENVIRONMENT =begin original Environment variables that the program cares about, normally presented as a list using C<=over>, C<=item>, and C<=back>. For example: =end original プログラムが考慮する環境変数; 通常、C<=over>、C<=item>、および C<=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 =begin original Since environment variables are normally in all uppercase, no additional special formatting is generally needed; they're glaring enough as it is. =end original 環境変数は通常すべて大文字なので、特別な書式設定を追加する 必要はありません; そのままで十分目立っています。 =item FILES =begin original 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 FEE. It's particularly important to document files that will be potentially modified. =end original プログラムまたは関数によって使用されるすべてのファイル (通常はリストとして表示されます)とその使用目的。 ファイル名は FEE で囲む必要があります。 変更される可能性のあるファイルを文書化することは特に重要です。 =item CAVEATS =begin original Things to take special care with, sometimes called WARNINGS. =end original WARNINGS と呼ばれることもある、特別な注意が必要なもの。 =item BUGS =begin original Things that are broken or just don't work quite right. =end original 壊れているもの、あるいは正しく動作しないもの。 =item RESTRICTIONS =begin original Bugs you don't plan to fix. :-) =end original 修正する予定のないバグ。 :-) =item NOTES =begin original Miscellaneous commentary. =end original その他の注釈。 =item AUTHOR =begin original 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. =end original 誰が書いたのか(複数の人に対しては AUTHORS を使用してください)。 ユーザが連絡できるように、現在の電子メールアドレス (またはバグレポートの送信先となる電子メールアドレス) またはその他の連絡先情報を含めることをお勧めします。 プログラムの文書は予想よりもはるかに長い時間にわたって 公開される傾向があることを覚えておいて、 長く続く可能性の高い連絡方法を選択してください。 =item HISTORY =begin original 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. =end original 他のソースから派生したプログラムはこの項目がある場合があります。 ここに変更ログを保存している人もいますが、通常は長くなり、 別のファイルに保存した方がよいでしょう。 =item COPYRIGHT AND LICENSE =begin original For copyright =end original 著作権について。 Copyright YEAR(s) YOUR NAME(s) =begin original (No, (C) is not needed. No, "all rights reserved" is not needed.) =end original (いいえ、(C)は不要です。 いいえ、"all rights reserved" は不要です。 ) =begin original For licensing the easiest way is to use the same licensing as Perl itself: =end original ライセンスを付けるための最も簡単な方法は、Perl 自体と 同じライセンスを使用することです: This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself. =begin original 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. =end original これにより、皆さんのモジュールを Perl で簡単に使用できるようになります。 このライセンスの例は推薦でも要件でもないことに注意してください; もちろん、どのようなライセンスでも自由に選択できます。 =item SEE ALSO =begin original 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 C form, don't have to be enclosed in LEE (although it's recommended), but other things in this section probably should be when appropriate. =end original man(1)、man(7)、makewhatis(8)、catman(8)などの、 チェックするべきその他の man ページ。 通常、manページをコンマで区切った単純なリストか、 参考文献の名前を示す段落です。 man ページ参照は、標準の C 形式を使用している場合は、 LEEで囲む必要はありませんが(推奨されています)、 このセクションの他の項目は適切な場合に含める必要があります。 =begin original If the package has a mailing list, include a URL or subscription instructions here. =end original パッケージにメーリングリストがある場合は、ここに URL または 購読手順を含めてください。 =begin original If the package has a web site, include a URL here. =end original パッケージに Web サイトがある場合は、ここに URL を追加します。 =back =begin original 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. =end original オブジェクト指向ライブラリまたはモジュールの文書では、 CONSTRUCTORS セクションと METHODS セクション、または CLASS METHODS セクションと INSTANCE METHODS セクションを使用して ライブラリの各部の詳細な文書を作成し、概要を説明するために DESCRIPTION セクションを保存する必要がある場合があります。 関数インタフェースを持つ大規模なモジュールでも、同様の理由で FUNCTIONS を使用する必要がある場合があります。 非常に長い場合は、説明を要約するために OVERVIEW を使用する人もいます。 =begin original 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. =end original セクションの順序は様々ですが、NAME は常に最初のセクションでなければならず (そうでないといくつかの man ページシステムを壊してしまいます)、 NAME、SYNOPSIS、DESCRIPTION、OPTIONSは一般に常に最初に、もしあれば その順序で現れます。 一般に、SEE ALSO、AUTHOR、および同様の資料は最後に残しておくべきです。 システムによっては、WARNINGS や NOTES を最後に移動することもあります。 上記の順序は、ほとんどの目的に対して妥当なものでなければなりません。 =begin original 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. =end original システムによっては、関連する標準への適合性を示すために CONFORMING TO を使用し、 スレッド化されたプログラムやシグナルハンドラで使用するための 安全性を示すために MT-LEVEL を使用します。 これらの見出しは主に、C ライブラリの一部を文書化する場合に役立ちます。 =begin original Finally, as a general note, try not to use an excessive amount of markup. As documented here and in L, 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 LEE, so don't do that. =end original 最後に、一般的な注意点として、過剰な量のマークアップを 使用しないようにしてください。 ここと L で説明されているように、Perl の変数、関数名、man ページ 参照などをマークアップで装飾されないままにしておくことは安全であり、 POD トランスレータがそれを理解してくれます。 これにより、後で文書を編集するのがずっと簡単になります。 多くの既存のトランスレータは、LEE にラップされた 電子メールアドレスに対して間違った操作を行うことに注意してください; したがって、そのような操作は行わないでください。 =head1 SEE ALSO =begin original For additional information that may be more accurate for your specific system, see either L or L depending on your system manual section numbering conventions. =end original ご使用のシステムでより正確な追加情報については、 システムマニュアルセクションの番号付け規則に応じて L または L を参照してください。 =begin original This documentation is maintained as part of the podlators distribution. The current version is always available from its web site at L. =end original この文書は podlators ディストリビューションの一部として管理されています。 最新バージョンは常に L の Web サイトから入手できます。 =head1 AUTHOR =begin original Russ Allbery , with large portions of this documentation taken from the documentation of the original B implementation by Larry Wall and Tom Christiansen. =end original Russ Allbery ; この文書の大部分は、Larry Wall and Tom Christiansen によるオリジナルの B 実装の文書から引用されています。 =head1 COPYRIGHT AND LICENSE Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2015 Russ Allbery Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty. =cut =begin meta Translate: SHIRAKATA Kentaro Status: completed =end meta