名前¶

perlpodstyle - Perl POD スタイルガイド

説明¶

これらは、優れた UNIX の man ページを書くための一般的なガイドラインに 基づいた、Perl スクリプトとモジュール用の POD 文書を書くための 一般的なガイドラインです。 これらのガイドラインはすべて、もちろんオプションですが、 これらに従うことで、システム上の他の文書との一貫性が高まります。

文書化されるプログラムの名前は、すべてのプログラムオプションと同様に、 (B<>を使用して)太字で表記されます。 引数は斜体(I<>)で表記されます。 関数名は伝統的に斜体(I<>)で表記されます; 関数を function() として記述した場合、Pod::Man がこの処理を行います。 リテラルコードまたはコマンドは C<> で記述されます。 他のマニュアルページへの参照は manpage(section) または L<manpage(section)> の形式で記述すると、 Pod::Man が自動的に適切に書式設定します。 2 番目の形式は L<> で、POD フォーマッタが可能であれば マニュアルページへのリンクを作成するように要求するために使用されます。 例外として、モジュール文書を参照する場合、どのセクションにモジュール文書が 含まれるかが明確でないため、通常はセクションを省略します; 代わりにモジュール参照には L<Module::Name> を使ってください。

他のプログラムや関数への参照は、通常、man ページ参照の形式で行われますので、 クロスリファレンスツールはユーザにリンクなどを提供することができます。 ただし、これはやり過ぎの可能性もありますので、マークアップが多すぎて文書が 乱雑にならないように注意してください。 man ページ参照として提供されていない他のプログラムへの参照は、B<>で 囲む必要があります。

メジャーヘッダは =head1 指示子を使用して設定する必要があり、 歴史的には、かなり驚くべき「全て大文字」形式で書かれています; これは必須ではありませんが、セクションが異なるソフトウェアパッケージ間で 一貫した名前を持つように強くお勧めします。 マイナーヘッダは =head2 を使用して含めることができ、 通常は大文字と小文字が混在しています。

マニュアルページの標準セクションは次のとおりです:

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 or STDERR 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 を追加します。

オブジェクト指向ライブラリまたはモジュールの文書では、 CONSTRUCTORS セクションと METHODS セクション、または CLASS METHODS セクションと INSTANCE METHODS セクションを使用して ライブラリの各部の詳細な文書を作成し、概要を説明するために DESCRIPTION セクションを保存する必要がある場合があります。 関数インタフェースを持つ大規模なモジュールでも、同様の理由で FUNCTIONS を使用する必要がある場合があります。 非常に長い場合は、説明を要約するために OVERVIEW を使用する人もいます。

セクションの順序は様々ですが、NAME は常に最初のセクションでなければならず (そうでないといくつかの man ページシステムを壊してしまいます)、 NAME、SYNOPSIS、DESCRIPTION、OPTIONSは一般に常に最初に、もしあれば その順序で現れます。 一般に、SEE ALSO、AUTHOR、および同様の資料は最後に残しておくべきです。 システムによっては、WARNINGS や NOTES を最後に移動することもあります。 上記の順序は、ほとんどの目的に対して妥当なものでなければなりません。

システムによっては、関連する標準への適合性を示すために CONFORMING TO を使用し、 スレッド化されたプログラムやシグナルハンドラで使用するための 安全性を示すために MT-LEVEL を使用します。 これらの見出しは主に、C ライブラリの一部を文書化する場合に役立ちます。

最後に、一般的な注意点として、過剰な量のマークアップを 使用しないようにしてください。 ここと Pod::Man で説明されているように、Perl の変数、関数名、man ページ 参照などをマークアップで装飾されないままにしておくことは安全であり、 POD トランスレータがそれを理解してくれます。 これにより、後で文書を編集するのがずっと簡単になります。 多くの既存のトランスレータは、L<> にラップされた 電子メールアドレスに対して間違った操作を行うことに注意してください; したがって、そのような操作は行わないでください。

SEE ALSO¶

ご使用のシステムでより正確な追加情報については、 システムマニュアルセクションの番号付け規則に応じて man(5) または man(7) を参照してください。

この文書は podlators ディストリビューションの一部として管理されています。 最新バージョンは常に <http://www.eyrie.org/~eagle/software/podlators/> の Web サイトから入手できます。

作者¶

Russ Allbery <[email protected]>; この文書の大部分は、Larry Wall and Tom Christiansen によるオリジナルの pod2man 実装の文書から引用されています。

コピーライト & ライセンス¶

Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2015 Russ Allbery <[email protected]>

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.

POD ERRORS¶

Hey! The above document had some coding errors, which are explained below:

Around line 50:

Unterminated C<C<...>> sequence