名前

perldocstyle - A style guide for writing Perl's documentation

perldocstyle - Perl の文書を書くためのスタイルガイド

(訳注: (TBR)がついている段落は「みんなの自動翻訳@TexTra®」による 機械翻訳です。)

説明

This document is a guide for the authorship and maintenance of the documentation that ships with Perl. This includes the following:

この文書は、Perlに同梱されている文書の作成と保守のためのガイドです。 これには次のものが含まれます。 (TBR)

  • The several dozen manual sections whose filenames begin with "perl", such as perlobj, perlre, and perlintro. (And, yes, perl.)

    perlobjperlreperlintroなど、ファイル名が"perl"で始まる数十のマニュアルセクション(もちろんperl)。 (TBR)

  • The documentation for all the modules included with Perl (as listed by perlmodlib).

    Perlに含まれているすべてのモジュールの文書(perlmodlibによってリストされています)。 (TBR)

  • The hundreds of individually presented reference sections derived from the perlfunc file.

    perlfuncファイルから派生した、個別に表示される数百の参照セクション。 (TBR)

This guide will hereafter refer to user-manual section files as man pages, per Unix convention.

このマニュアルでは、Unixの規則に従って、ユーザマニュアルセクションファイルをman pagesと呼びます。 (TBR)

Purpose of this guide

This style guide aims to establish standards, procedures, and philosophies applicable to Perl's core documentation.

このスタイルガイドは、Perlのコア文書に適用できる標準、手順、および理念を確立することを目的としています。 (TBR)

Adherence to these standards will help ensure that any one part of Perl's manual has a tone and style consistent with that of any other. As with the rest of the Perl project, the language's documentation collection is an open-source project authored over a long period of time by many people. Maintaining consistency across such a wide swath of work presents a challenge; this guide provides a foundation to help mitigate this difficulty.

これらの標準を遵守することで、Perlのマニュアルのいずれかの部分が他の部分と一貫したトンマナを持つことが保証されます。 Perlプロジェクトの他の部分と同様に、言語の文書コレクションは、多くの人々によって長期間にわたって作成されたオープンソースプロジェクトです。 このような広範囲の作業にわたって一貫性を維持することには課題があります。 このガイドは、この困難を緩和するための基礎を提供します。 (TBR)

This will help its readers--especially those new to Perl--to feel more welcome and engaged with Perl's documentation, and this in turn will help the Perl project itself grow stronger through having a larger, more diverse, and more confident population of knowledgeable users.

これは、Perlの読者、特にPerlに慣れていない読者が、Perlの文書に対してより歓迎され、関心を持つようになるのに役立ちます。 また、Perlプロジェクト自体が、より多くの、より多様で、より自信に満ちた知識のあるユーザーを持つことによって、より強くなるのにも役立ちます。 (TBR)

Intended audience

Anyone interested in contributing to Perl's core documentation should familiarize themselves with the standards outlined by this guide.

Perlのコア文書への貢献に興味がある人は、このガイドで概説されている標準をよく理解しておく必要があります。 (TBR)

Programmers documenting their own work apart from the Perl project itself may also find this guide worthwhile, especially if they wish their work to extend the tone and style of Perl's own manual.

Perlプロジェクト自体とは別に自分の作業を文書化しているプログラマーも、特に自分の作業でPerl自身のマニュアルのトンマナを拡張したいと思っている場合には、このガイドに価値があると感じるでしょう。 (TBR)

Status of this document

This guide was initially drafted in late 2020, drawing from the documentation style guides of several open-source technologies contemporary with Perl. This has included Python, Raku, Rust, and the Linux kernel.

このガイドは2020年後半に最初に作成され、Python、Rak、Rust、Linuxカーネルなど、Perlと同時代のオープンソース技術の文書スタイルガイドを参考にしています。 (TBR)

The author intends to see this guide used as starting place from which to launch a review of Perl's reams of extant documentation, with the expectation that those conducting this review should grow and modify this guide as needed to account for the requirements and quirks particular to Perl's programming manual.

著者は、このガイドを出発点として、Perlの膨大な現存文書のレビューを開始するつもりです。 このレビューを行う人たちが、Perlのプログラミングマニュアルに特有の要件や癖を説明するために必要に応じてこのガイドを成長させ、修正することを期待しています。 (TBR)

FUNDAMENTALS

Choice of markup: Pod

All of Perl's core documentation uses Pod ("Plain Old Documentation"), a simple markup language, to format its source text. Pod is similar in spirit to other contemporary lightweight markup technologies, such as Markdown and reStructuredText, and has a decades-long shared history with Perl itself.

Perlのコア文書はすべて、ソーステキストをフォーマットするために、単純なマークアップ言語であるPod("Plain Old Documentation")を使用しています。 Podは、MarkdownやreStructuredTextなどの他の現代的な軽量マークアップ技術と精神が似ており、Perl自体と数十年の歴史を共有してきました。 (TBR)

For a comprehensive reference to Pod syntax, see perlpod. For the sake of reading this guide, familiarity with the Pod syntax for section headers (=head2, et cetera) and for inline text formatting (C<like this>) should suffice.

Pod構文の詳細については、perlpodを参照してください。 このガイドを読むためには、セクションヘッダー(=head2など)とインラインテキストフォーマット(C<like this>)のPod構文に精通していれば十分です。 (TBR)

Perl programmers also use Pod to document their own scripts, libraries, and modules. This use of Pod has its own style guide, outlined by perlpodstyle.

Perlプログラマーは、独自のスクリプト、ライブラリー、モジュールを文書化するためにもPodを使用します。 このPodの使用方法には、perlpodstyleによって概説されている独自のスタイルガイドがあります。 (TBR)

Choice of language: American English

Perl's core documentation is written in English, with a preference for American spelling of words and expression of phrases. That means "color" over "colour", "math" versus "maths", "the team has decided" and not "the team have decided", and so on.

Perlのコア文書は英語で書かれていますが、単語のスペルやフレーズの表現はアメリカ式が好まれています。 これは、「色」よりも「色」、「数学」対「数学」、「チームが決定した」ではなく「チームが決定した」などを意味します。 (TBR)

We name one style of English for the sake of consistency across Perl's documentation, much as a software project might declare a four-space indentation standard--even when that doesn't affect how well the code compiles. Both efforts result in an easier read by avoiding jarring, mid-document changes in format or style.

Perlの文書全体に一貫性を持たせるために、英語のスタイルを1つ命名していますが、これはソフトウェアプロジェクトが4スペースのインデント標準を宣言しているように(コードのコンパイルに影響しない場合でも)、どちらの取り組みも、文書の途中でフォーマットやスタイルが変更されることを避けることで、読みやすくなります。 (TBR)

Contributors to Perl's documentation should note that this rule describes the ultimate, published output of the project, and does not prescribe the dialect used within community contributions. The documentation team enthusiastically welcomes any English-language contributions, and will actively assist in Americanizing spelling and style when warranted.

Perlの文書への寄稿者は、この規則がプロジェクトの最終的に公開された出力を記述したものであり、コミュニティコントリビューションで使用されている方言を規定したものではないことに注意してください。 文書チームは、英語によるコントリビューションを熱烈に歓迎しており、正当な理由がある場合には、スペリングとスタイルのアメリカ化を積極的に支援します。 (TBR)

Other languages and translations

Community-authored translations of Perl's documentation do exist, covering a variety of languages. While the Perl project appreciates these translation efforts and promotes them when applicable, it does not officially support or maintain any of them.

Perlの文書には、コミュニティによる翻訳があり、さまざまな言語に対応しています。 Perlプロジェクトでは、これらの翻訳の取り組みを評価し、必要に応じて推進していますが、公式にはサポートも保守もしていません。 (TBR)

That said, keeping Perl's documentation clear, simple, and short has a welcome side effect of aiding any such translation project.

そうは言っても、Perlの文書を明確で単純で簡潔なものにしておくことは、そのような翻訳プロジェクトを支援するという歓迎すべき副作用をもたらします。 (TBR)

(Note that the Chinese, Japanese, and Korean-language README files included with Perl's source distributions provide an exception to this choice of language--but these documents fall outside the scope of this guide.)

(Perlのソース配布物に含まれている中国語、日本語、韓国語のREADMEファイルには、この言語選択の例外があることに注意してください。 しかし、これらの文書はこのガイドの範囲外です。 (TBR)

Choice of encoding: UTF-8

Perl's core documentation files are encoded in UTF-8, and can make use of the full range of characters this encoding allows.

Perlのコア文書ファイルはUTF-8でエンコードされており、このエンコードで許可されの全範囲を利用することができます。 (TBR)

As such, every core doc file (or the Pod section of every core module) should commence with an =encoding utf8 declaration.

そのため、すべてのコアdocファイル(またはすべてのコアモジュールのPodセクション)は、=encoding utf8宣言で始まる必要があります。 (TBR)

Choice of underlying style guide: CMOS

Perl's documentation uses the Chicago Manual of Style (CMOS), 17th Edition, as its baseline guide for style and grammar. While the document you are currently reading endeavors to serve as an adequate stand-alone style guide for the purposes of documenting Perl, authors should consider CMOS the fallback authority for any pertinent topics not covered here.

Perlの文書では、スタイルと文法のベースラインガイドとしてChicago Manual of Style(CMOS),17 th Editionを使用しています。 現在読んでいる文書は、Perlを文書化するための適切なスタンドアロンスタイルガイドとして機能するよう努力していますが、ここで取り上げていない関連トピックについては、CMOSをフォールバック権限として考慮する必要があります。 (TBR)

Because CMOS is not a free resource, access to it is not a prerequisite for contributing to Perl's documentation; the doc team will help contributors learn about and apply its guidelines as needed. However, we do encourage anyone interested in significant doc contributions to obtain or at least read through CMOS. (Copies are likely available through most public libraries, and CMOS-derived fundamentals can be found online as well.)

CMOSは無料のリソースではないため、CMOSへのアクセスはPerlの文書に貢献するための前提条件ではありません。 文書チームは、貢献者がCMOSのガイドラインを学び、必要に応じて適用するのを支援します。 しかし、重要な文書への貢献に関心のある人には、CMOSを入手するか、少なくともCMOSを通じて読むことをお勧めします(コピーはほとんどの公共図書館を通じて入手できる可能性が高く、CMOS由来の基礎はオンラインでも見つけることができます)。 (TBR)

Contributing to Perl's documentation

Perl, like any programming language, is only as good as its documentation. Perl depends upon clear, friendly, and thorough documentation in order to welcome brand-new users, teach and explain the language's various concepts and components, and serve as a lifelong reference for experienced Perl programmers. As such, the Perl project welcomes and values all community efforts to improve the language's documentation.

Perlは、他のプログラミング言語と同じように、文書だけが優れています。 Perlは、新規ユーザーを歓迎し、Perlのさまざまな概念とコンポーネントを教えて説明し、経験豊富なPerlプログラマーの生涯にわたる参考資料として使用するために、明確で親しみやすく、徹底した文書に依存しています。 Perlプロジェクトは、Perlの文書を改善するためのコミュニティのあらゆる努力を歓迎し、評価しています。 (TBR)

Perl accepts documentation contributions through the same open-source project pipeline as code contributions. See perlhack for more information.

Perlは、コードコントリビューションと同じオープンソースプロジェクトパイプラインを通じて文書コントリビューションを受け入れています。 詳細については、perlhackを参照してください。 (TBR)

FORMATTING AND STRUCTURE

This section details specific Pod syntax and style that all core Perl documentation should adhere to, in the interest of consistency and readability.

このセクションでは、一貫性と読みやすさのために、すべてのコアPerl文書が従うべき特定のPod構文とスタイルについて詳しく説明します。 (TBR)

Document structure

Each individual work of core Perl documentation, whether contained within a .pod file or in the Pod section of a standard code module, patterns its structure after a number of long-time Unix man page conventions. (Hence this guide's use of "man page" to refer to any one self-contained part of Perl's documentation.)

コアPerl文書の個々の作業は、.podファイルに含まれているか、標準コードモジュールのPodセクションに含まれているかにかかわらず、その構造をUnixの長いマニュアルページの規則に従ってパターン化します(したがって、このガイドでは"man page"を使用して、Perl文書の独立した部分を参照しています)。 (TBR)

Adhering to these conventions helps Pod formatters present a Perl man page's content in different contexts--whether a terminal, the web, or even print. Many of the following requirements originate with perlpodstyle, which derives its recommendations in turn from these well-established practices.

これらの規則に従うことで、PodフォーマッタはPerlのmanページのコンテンツをさまざまなコンテキスト(ターミナル、Web、さらには印刷物など)で表示することができます。 以下の要件の多くは、perlpodstyleに由来しており、これはこれらの確立されたプラクティスから推奨事項を導き出しています。 (TBR)

Name

After its =encoding utf8 declaration, a Perl man page must present a level-one header named "NAME" (literally), followed by a paragraph containing the page's name and a very brief description.

=encoding utf8 declaration の後に、Perlのmanページmustは"NAME"(文字通り)というレベル1ののヘッダを提示し、その後にページの名前と非常に簡単な説明を含む段落が続きます。 (TBR)

The first few lines of a notional page named perlpodexample:

perlpodexampleという名前の架空のページの最初の数行: (TBR)

    =encoding utf8

    =head1 NAME

    perlpodexample - An example of formatting a manual page's title line

Description and synopsis

Most Perl man pages also contain a DESCRIPTION section featuring a summary of, or introduction to, the document's content and purpose.

ほとんどのPerlのmanページには、DESCRIPTIONセクションがあり、その文書の内容と目的の概要や紹介が書かれています。 (TBR)

This section should also, one way or another, clearly identify the audience that the page addresses, especially if it has expectations about the reader's prior knowledge. For example, a man page that dives deep into the inner workings of Perl's regular expression engine should state its assumptions up front--and quickly redirect readers who are instead looking for a more basic reference or tutorial.

また、このセクションでは、何らかの方法で、ページが対象とする読者を明確に特定する必要があります。 特に、読者の事前知識に期待がある場合には、そのことが重要です。 例えば、Perlの正規表現エンジンの内部動作を深く掘り下げたmanページでは、前提条件を事前に説明し、より基本的なリファレンスやチュートリアルを探している読者をすぐにリダイレクトする必要があります。 (TBR)

Reference pages, when appropriate, can precede the DESCRIPTION with a SYNOPSIS section that lists, within one or more code blocks, some very brief examples of the referenced feature's use. This section should show a handful of common-case and best-practice examples, rather than an exhaustive list of every obscure method or alternate syntax available.

参照ページは、必要に応じて、DESCRIPTIONの前にSYNOPSISセクションを付けることができます。 このセクションでは、1つまたは複数のコードブロック内で、参照される機能の使用に関する非常に簡単な例を一覧表示します。 このセクションでは、使用可能なすべてのあいまいなメソッドや代替構文を網羅したリストではなく、いくつかの一般的な例とベストプラクティスの例を示す必要があります。 (TBR)

Other sections and subsections

Pages should conclude, when appropriate, with a SEE ALSO section containing hyperlinks to relevant sections of Perl's manual, other Unix man pages, or appropriate web pages. Hyperlink each such cross-reference via L<...>.

ページは、必要に応じて、Perlのマニュアル、他のUnixのmanページ、または適切なWebページの関連セクションへのハイパーリンクを含むSEE ALSOセクションで締めくくられるべきです。 L<.>を経由してこのような相互参照をハイパーリンクしてください。 (TBR)

What other sections to include depends entirely upon the topic at hand. Authors should feel free to include further =head1-level sections, whether other standard ones listed by perlpodstyle, or ones specific to the page's topic; in either case, render these top-level headings in all-capital letters.

他にどのようなセクションを含めるかは、そのトピックに完全に依存します。 著者は、=head1レベルのセクションを、perlpodstyleによってリストされた他の標準的なセクションであっても、ページのトピックに固有のセクションであっても、自由に追加する必要があります。 いずれの場合も、これらのトップレベルの見出しはすべて大文字で表示してください。 (TBR)

You may then include as many subsections beneath them as needed to meet the standards of clarity, accessibility, and cross-reference affinity suggested elsewhere in this guide.

次に、明確さ、アクセシビリティ、相互参照親和性の基準を満たすために必要な数のサブセクションをその下に含めることができます。 suggested elsewhere in this guide (TBR)

Author and copyright

In most circumstances, Perl's stand-alone man pages--those contained within .pod files--do not need to include any copyright or license information about themselves. Their source Pod files are part of Perl's own core software repository, and that already covers them under the same copyright and license terms as Perl itself. You do not need to include additional "LICENSE" or "COPYRIGHT" sections of your own.

ほとんどの場合、Perlのスタンドアロンマニュアルページ(.podファイルに含まれているマニュアルページ)には、それ自体に関する著作権情報やライセンス情報を含める必要はありません。 PerlのソースPodファイルはPerl自身のコアソフトウェアリポジトリーの一部であり、Perl自体と同じ著作権とライセンス条件のもとですでにカバーされています。 独自の"LICENSE"や"COPYRIGHT"セクションを追加する必要はありません。 (TBR)

These man pages may optionally credit their primary author, or include a list of significant contributors, under "AUTHOR" or "CONTRIBUTORS" headings. Note that the presence of authors' names does not preclude a given page from writing in a voice consistent with the rest of Perl's documentation.

これらのmanページは、"AUTHOR"または"CONTRIBUTORS"という見出しの下に、その主著者をクレジットしたり、重要な貢献者のリストを含んだりすることができます。 著者の名前があるからといって、そのページが writing in a voice consistent with the rest of Perl's documentation ことを妨げるものではないことに注意してください。 (TBR)

Note that these guidelines do not apply to the core software modules that ship with Perl. These have their own standards for authorship and copyright statements, as found in perlpodstyle.

これらのガイドラインは、Perlに同梱されているコアソフトウェアモジュールには適用されないことに注意してください。 これらのモジュールには、perlpodstyleにあるように、著者やコピーライトに関する独自の基準があります。 (TBR)

Formatting rules

Line length and line wrap

Each line within a Perl man page's Pod source file should measure 72 characters or fewer in length.

PerlのマニュアルページのPodソースファイル内の各行の長さは、72文字以下でなければなりません。 (TBR)

Please break paragraphs up into blocks of short lines, rather than "soft wrapping" paragraphs across hundreds of characters with no line breaks.

改行なしで何百文字にもわたって段落を「ソフトラッピング」するのではなく、段落を短い行のブロックに分割してください。 (TBR)

Code blocks

Just like the text around them, all code examples should be as short and readable as possible, displaying no more complexity than absolutely necessary to illustrate the concept at hand.

すべてのコード例は、周囲のテキストと同じように、できるだけ短くて読みやすいものでなければならず、手元の概念を説明するために絶対に必要な以上の複雑さを示す必要はありません。 (TBR)

For the sake of consistency within and across Perl's man pages, all examples must adhere to the code-layout principles set out by perlstyle.

Perlのmanページ内およびmanページ間で一貫性を保つために、すべての例はperlstyleによって定められたコードレイアウト原則に従わなければなりません。 (TBR)

Sample code should deviate from these standards only when necessary: during a demonstration of how Perl disregards whitespace, for example, or to temporarily switch to two-column indentation for an unavoidably verbose illustration.

サンプルコードは、必要な場合にのみこれらの標準から逸脱すべきです。 例えば、Perlがどのように空白文字を無視するかを示すデモを行っているときや、避けられない冗長な説明のために一時的に2列のインデントに切り替えるときなどです。 (TBR)

You may include comments within example code to further clarify or label the code's behavior in-line. You may also use comments as placeholder for code normally present but not relevant to the current topic, like so:

サンプルコード内にコメントを含めて、インラインでのコードの動作をさらに明確にしたり、ラベル付けしたりすることができます。 次のように、通常は存在するが現在のトピックとは関係のないコードのプレースホルダとしてコメントを使用することもできます。 (TBR)

    while (my $line = <$fh>) {
        #
        # (Do something interesting with $line here.)
        #
    }

Even the simplest code blocks often require the use of example variables and subroutines, whose names you should choose with care.

最も単純なコードブロックであっても、多くの場合、変数とサブルーチンの例を使用する必要があります。 whose names you should choose with care を使用する必要があります。 (TBR)

Inline code and literals

Within a paragraph of text, use C<...> when quoting or referring to any bit of Perl code--even if it is only one character long.

テキストの段落内で、Perlコードを引用したり参照したりする場合は、C<.>を使用します。 これは、1文字の長さであっても同じです。 (TBR)

For instance, when referring within an explanatory paragraph to Perl's operator for adding two numbers together, you'd write "C<+>".

例えば、説明段落で2つの数字を加算するPerlの演算子を参照する場合は、「C<+>」と記述します。 (TBR)

Function names

Use C<...> to render all Perl function names in monospace, whenever they appear in text.

C<.>を使用すると、すべてのPerl関数名がテキストに表示されている場合は常に、モノスペースで表示されます。 (TBR)

Unless you need to specifically quote a function call with a list of arguments, do not follow a function's name in text with a pair of empty parentheses. That is, when referring in general to Perl's print function, write it as "print", not "print()".

引数のリストを使用して関数呼び出しを明示的に引用する必要がない限り、テキスト内の関数名の後に空のかっこを付けないでください。 つまり、一般的にPerlのprint関数を参照する場合は、"print()"ではなく"print"と記述してください。 (TBR)

Function arguments

Represent functions' expected arguments in all-caps, with no sigils, and using C<...> to render them in monospace. These arguments should have short names making their nature and purpose clear. Convention specifies a few ones commonly seen throughout Perl's documentation:

関数の期待される引数を、記号なしで、C<.>を使用してモノスペースで表現します。 これらの引数には、その性質と目的を明確にした短い名前を付ける必要があります。 規約では、Perlの文書で一般的に見られる引数をいくつか指定しています。 (TBR)

  • EXPR

    EXPR (TBR)

    The "generic" argument: any scalar value, or a Perl expression that evaluates to one.

    "generic"引数:任意のスカラー値、または1と評価されるPerl式。 (TBR)

  • ARRAY

    アレイ (TBR)

    An array, stored in a named variable.

    名前付き変数に格納された配列。 (TBR)

  • HASH

    ハッシュ (TBR)

    A hash, stored in a named variable.

    名前付き変数に格納されたハッシュ。 (TBR)

  • BLOCK

    BLOCK (TBR)

    A curly-braced code block, or a subroutine reference.

    A curly-braced code block, or a subroutine reference. (TBR)

  • LIST

    LIST (TBR)

    Any number of values, stored across any number of variables or expressions, which the function will "flatten" and treat as a single list. (And because it can contain any number of variables, it must be the last argument, when present.)

    Any number of values, stored across any number of variables or expressions, which the function will "flatten" and treat as a single list. (And because it can contain any number of variables, it must be the last argument, when present.) (TBT)

When possible, give scalar arguments names that suggest their purpose among the arguments. See, for example, substr's documentation, whose listed arguments include EXPR, OFFSET, LENGTH, and REPLACEMENT.

When possible, give scalar arguments names that suggest their purpose among the arguments. See, for example, substr's documentation, whose listed arguments include EXPR, OFFSET, LENGTH, and REPLACEMENT. (TBT)

Apostrophes, quotes, and dashes

In Pod source, use straight quotes, and not "curly quotes": "Like this", not “like this”. The same goes for apostrophes: Here's a positive example, and here’s a negative one.

In Pod source, use straight quotes, and not "curly quotes": "Like this", not “like this”. The same goes for apostrophes: Here's a positive example, and here’s a negative one. (TBT)

Render em dashes as two hyphens--like this:

Render em dashes as two hyphens--like this: (TBR)

    Render em dashes as two hyphens--like this.

Leave it up to formatters to reformat and reshape these punctuation marks as best fits their respective target media.

Leave it up to formatters to reformat and reshape these punctuation marks as best fits their respective target media. (TBR)

Unix programs and C functions

When referring to a Unix program or C function with its own man page (outside of Perl's documentation), include its manual section number in parentheses. For example: malloc(3), or mkdir(1).

When referring to a Unix program or C function with its own man page (outside of Perl's documentation), include its manual section number in parentheses. For example: malloc(3), or mkdir(1). (TBR)

If mentioning this program for the first time within a man page or section, make it a cross reference, e.g. L<malloc(3)>.

If mentioning this program for the first time within a man page or section, make it a cross reference, e.g. L<malloc(3)>. (TBR)

Do not otherwise style this text.

このテキストにスタイルを設定しないでください。 (TBR)

Make generous use of Pod's L<...> syntax to create hyperlinks to other parts of the current man page, or to other documents entirely -- whether elsewhere on the reader's computer, or somewhere on the internet, via URL.

PodのL<.>構文を利用して、現在のマニュアルページの他の部分へのハイパーリンクや、他の文書全体へのハイパーリンクを作成します。 読者のコンピュータ上のどこか、あるいはインターネット上のどこかに、URL経由で作成します。 (TBR)

Use L<...> to link to another section of the current man page when mentioning it, and make use of its page-and-section syntax to link to the most specific section of a separate page within Perl's documentation. Generally, the first time you refer to a specific function, program, or concept within a certain page or section, consider linking to its full documentation.

L<.>を使用して、現在のマニュアルページの別のセクションにリンクします。 また、そのページとセクションの構文を使用して、Perlの文書内の別のページの最も詳細なセクションにリンクします。 一般に、特定のページまたはセクション内の特定の機能、プログラム、または概念を初めて参照する場合は、その完全な文書へのリンクを検討してください。 (TBR)

Hyperlinks do not supersede other formatting required by this guide; Pod allows nested text formats, and you should use this feature as needed.

ハイパーリンクは、このガイドで必要とされる他のフォーマットに優先するものではありません。 Podでは、ネストされたテキストフォーマットを使用できます。 必要に応じてこの機能を使用してください。 (TBR)

Here is an example sentence that mentions Perl's say function, with a link to its documentation section within the perlfunc man page:

以下に、Perlのsay関数に言及した例文と、perlfuncmanページ内のその文書セクションへのリンクを示します。 (TBR)

    In version 5.10, Perl added support for the 
    L<C<say>|perlfunc/say FILEHANDLE LIST> function.

Note the use of the vertical pipe ("|") to separate how the link will appear to readers ("C<say>") from the full page-and-section specifier that the formatter links to.

垂直パイプ("")を使用して、フォーマッタがリンクしている完全なページとセクションの指定子とリンクが読者にどのように見えるか("C<say>")を分離していることに注意してください。 (TBR)

Tables and diagrams

Pod does not officially support tables. To best present tabular data, include the table as both HTML and plain-text representations--the latter as an indented code block. Use =begin / =end directives to target these tables at html and text Pod formatters, respectively. For example:

Podは公式には表をサポートしていません。 表形式のデータを最適に表示するには、表をHTMLとプレーンテキストの両方の表現(後者はインデントされたコードブロック)として含めます。 =begin/=endディレクティブを使用して、これらの表をそれぞれhtmltextPodフォーマッタでターゲットにします。 次に例を示します。 (TBR)

    =head2 Table of fruits

    =begin text

     Name           Shape           Color
     =====================================
     Apple          Round           Red
     Banana         Long            Yellow
     Pear           Pear-shaped     Green

    =end text

    =begin html

    <table>
    <tr><th>Name</th><th>Shape</th><th>Color</th></tr>
    <tr><td>Apple</td><td>Round</td><td>Red</td></tr>
    <tr><td>Banana</td><td>Long</td><td>Yellow</td></tr>
    <tr><td>Pear</td><td>Pear-shaped</td><td>Green</td></tr>
    </table>

    =end html

The same holds true for figures and graphical illustrations. Pod does not natively support inline graphics, but you can mix HTML <img> tags with monospaced text-art representations of those images' content.

図や図解についても同様である。 Podはもともとインライングラフィックをサポートしていないが、HTMLの<<<img>>>タグを、それらの画像の内容をモノスペースで表現したテキストアートと組み合わせることができる。 (TBR)

Due in part to these limitations, most Perl man pages use neither tables nor diagrams. Like any other tool in your documentation toolkit, however, you may consider their inclusion when they would improve an explanation's clarity without adding to its complexity.

これらの制限のために、ほとんどのPerlのマニュアルページでは表も図も使用していません。 ただし、文書ツールキットの他のツールと同様に、説明の複雑さを増すことなく説明の明確さを向上させる場合には、説明を含めることを検討してください。 (TBR)

Adding comments

Like any other kind of source code, Pod lets you insert comments visible only to other people reading the source directly, and ignored by the formatting programs that transform Pod into various human-friendly output formats (such as HTML or PDF).

他の種類のソースコードと同様に、Podでは、ソースを直接読んでいる他の人にしか見えないコメントを挿入することができ、Podをさまざまな人に使いやすい出力フォーマット(HTMLやPDFなど)に変換するフォーマットプログラムでは無視される。 (TBR)

To comment Pod text, use the =for and =begin / =end Pod directives, aiming them at a (notional) formatter called "comment". A couple of examples:

Podテキストにコメントを付けるには、=forおよび=begin/=endPodディレクティブを使用して、"comment"と呼ばれる(概念的な)フォーマッタをターゲットにします。 次に例を示します。 (TBR)

    =for comment Using "=for comment" like this is good for short,
    single-paragraph comments.

    =begin comment

    If you need to comment out more than one paragraph, use a
    =begin/=end block, like this.

    None of the text or markup in this whole example would be visible to
    someone reading the documentation through normal means, so it's
    great for leaving notes, explanations, or suggestions for your
    fellow documentation writers.

    =end comment

In the tradition of any good open-source project, you should make free but judicious use of comments to leave in-line "meta-documentation" as needed for other Perl documentation writers (including your future self).

優れたオープンソースプロジェクトの伝統では、コメントを自由に、しかし賢明に使用して、他のPerl文書作成者(将来の自分自身を含む)に必要なインライン「メタ文書」を残すようにすべきです。 (TBR)

Perlfunc has special rules

The perlfunc man page, an exhaustive reference of every Perl built-in function, has a handful of formatting rules not seen elsewhere in Perl's documentation.

すべてのPerl組み込み関数を網羅的に参照しているperlfuncのマニュアルページには、Perlの文書にはないフォーマットルールがいくつかあります。 (TBR)

Software used during Perl's build process (Pod::Functions) parses this page according to certain rules, in order to build separate man pages for each of Perl's functions, as well as achieve other indexing effects. As such, contributors to perlfunc must know about and adhere to its particular rules.

Perlのビルドプロセス(Pod::Functions)で使用されるソフトウェアは、特定のルールに従ってこのページを解析します。 これは、Perlの各関数に対して個別のmanページをビルドするためだけでなく、その他の索引付け効果を実現するためにも行われます。 そのため、perlfuncへのコントリビュータは、その特定のルールについて理解し、それに従う必要があります。 (TBR)

Most of the perfunc man page comprises a single list, found under the header "Alphabetical Listing of Perl Functions". Each function reference is an entry on that list, made of three parts, in order:

perfuncのマニュアルページのほとんどは、 "Alphabetical Listing of Perl Functions"という見出しの下にある単一のリストで構成されています。 各関数参照は、そのリストのエントリであり、次の順序で3つの部分から構成されています。 (TBR)

  1. A list of =item lines which each demonstrate, in template format, a way to call this function. One line should exist for every combination of arguments that the function accepts (including no arguments at all, if applicable).

    =item行のリスト示す=item行のリスト。 関数が受け入れる引数の組み合わせごとに1行が必要です(引数が存在しない場合は、引数はありません)。 (TBR)

    If modern best practices prefer certain ways to invoke the function over others, then those ways should lead the list.

    もし現代のベストプラクティスが、関数を呼び出すために他の方法よりも特定の方法を好むなら、それらの方法がリストの先頭に来るべきです。 (TBR)

    The first item of the list should be immediately followed by one or more X<...> terms listing index-worthy topics; if nothing else, then the name of the function, with no arguments.

    リストの最初の項目の直後に、インデックスに値するトピックをリストした1つ以上のX<.>項が続きます。 それ以外の場合は、引数のない関数の名前です。 (TBR)

  2. A =for line, directed at Pod::Functions, containing a one-line description of what the function does. This is written as a phrase, led with an imperative verb, with neither leading capitalization nor ending punctuation. Examples include "quote a list of words" and "change a filename".

    Pod::Functionsに向けられた=for行。 この行には、関数の動作に関する1行の説明が含まれています。 これは、命令動詞で始まるフレーズとして記述され、先頭の大文字と小文字も末尾の句読点もありません。 たとえば、"quote a list of words"や"change a filename"などです。 (TBR)

  3. The function's definition and reference material, including all explanatory text and code examples.

    関数の定義と参照資料(すべての説明テキストとコード例を含む)。 (TBR)

Complex functions that need their text divided into subsections (under the principles of "Apply section-breaks and examples generously") may do so by using sublists, with =item elements as header text.

サブセクションに分割されたテキストを必要とする複雑な関数("Apply section-breaks and examples generously" の原則に基づく)は、=item要素をヘッダテキストとして持つサブリストを使用することによって、サブセクションに分割することができます。 (TBR)

A fictional function "myfunc", which takes a list as an optional argument, might have an entry in perlfunc shaped like this:

オプションの引数としてリストを取る架空の関数"myfunc"は、perlfuncに次のようなエントリを持つ可能性があります。 (TBR)

    =item myfunc LIST
    X<myfunc>

    =item myfunc

    =for Pod::Functions demonstrate a function's perlfunc section 

    [ Main part of function definition goes here, with examples ]

    =over

    =item Legacy uses

    [ Examples of deprecated syntax still worth documenting ]

    =item Security considerations

    [ And so on... ]

    =back

TONE AND STYLE

Apply one of the four documentation modes

Aside from "meta" documentation such as perlhist or perlartistic, each of Perl's man pages should conform to one of the four documentation "modes" suggested by The Documentation System by Daniele Procida. These include tutorials, cookbooks, explainers, and references--terms that we define in further detail below.

perlhistperlartisticのような「メタ」文書とは別に、Perlの各マニュアルページは、 The Documentation System by Daniele Procidaが提案している4つの文書「モード」の1つに従うべきです。 これには、チュートリアル、料理本、解説、参考文献などがあります。 これらの用語については、後で詳しく説明します。 (TBR)

Each mode of documentation speaks to a different audience--not just people of different backgrounds and skill levels, but individual readers whose needs from language documentation can shift depending upon context. For example, a programmer with plenty of time to learn a new concept about Perl can ease into a tutorial about it, and later expand their knowledge further by studying an explainer. Later, that same programmer, wading knee-deep in live code and needing only to look up some function's exact syntax, will want to reach for a reference page instead.

文書の各モードは、異なる読者を対象としています。 異なるバックグラウンドやスキルレベルの人々だけでなく、言語文書からのニーズが状況に応じて変化する可能性のある個々の読者も対象としています。 例えば、Perlに関する新しい概念を学ぶ時間が十分にあるプログラマーは、Perlに関するチュートリアルに進んで、後で解説者を研究することによって知識をさらに広げることができます。 その後、その同じプログラマーが、生のコードに深く入り込み、関数の正確な構文を調べるだけで、代わりにリファレンスページを探したいと思うようになるでしょう。 (TBR)

Perl's documentation must strive to meet these different situational expectations by limiting each man page to a single mode. This helps writers ensure they provide readers with the documentation needed or expected, despite ever-evolving situations.

Perlの文書では、各マニュアルページを1つのモードに制限することによって、これらのさまざまな状況の期待に応えるように努力する必要があります。 これは、状況が常に変化しているにもかかわらず、ライターが必要な、あるいは期待される文書を確実に読者に提供するために役立ちます。 (TBR)

Tutorial

A tutorial man page focuses on learning, ideally by doing. It presents the reader with small, interesting examples that allow them to follow along themselves using their own Perl interpreter. The tutorial inspires comprehension by letting its readers immediately experience (and experiment on) the concept in question. Examples include perlxstut, perlpacktut, and perlretut.

チュートリアルのマニュアルページでは、learning、理想的にはdoingに焦点を当てています。 このページでは、読者が独自のPerlインタープリターを使用して理解できるようにする、小さくて興味深い例を紹介しています。 このチュートリアルでは、読者が問題の概念をすぐに体験(および実験)できるようにすることで、理解を促しています。 例としては、perlxstutperlpacktutperlretutなどがあります。 (TBR)

Tutorial man pages must strive for a welcoming and reassuring tone from their outset; they may very well be the first things that a newcomer to Perl reads, playing a significant role in whether they choose to stick around. Even an experienced programmer can benefit from the sense of courage imparted by a strong tutorial about a more advanced topic. After completing a tutorial, a reader should feel like they've been led from zero knowledge of its topic to having an invigorating spark of basic understanding, excited to learn more and experiment further.

チュートリアルのマニュアルページは、最初から歓迎と安心感を与えるように努力する必要があります。 これは、Perlの初心者が読む最初のページであり、彼らが存続するかどうかに重要な役割を果たしている可能性があります。 経験豊富なプログラマーであっても、より高度なトピックに関する強力なチュートリアルによってもたらされる勇気の感覚から利益を得ることができます。 チュートリアルを完了した読者は、そのトピックに関する0の知識から導かれたように感じ、基礎を理解し、より多くのことを学び、さらに実験することに興奮している必要があります。 (TBR)

Tutorials can certainly use real-world examples when that helps make for clear, relatable demonstrations, so long as they keep the focus on teaching--more practical problem-solving should be left to the realm of cookbooks (as described below). Tutorials also needn't concern themselves with explanations into why or how things work beneath the surface, or explorations of alternate syntaxes and solutions; these are better handled by explainers and reference pages.

チュートリアルでは、明確で関連性のあるデモンストレーションを行うのに役立つ実世界の例を使用することができます。 ただし、彼らが教えることに焦点を当てている場合に限ります--より実践的な問題解決は、クックブックの領域に任せるべきです(後述)。 また、チュートリアルでは、物事が水面下でなぜ、どのように動作するかについての説明や、代替構文やソリューションの探求に関心を持つ必要はありません。 これらは、説明者やリファレンスページでより適切に処理されます。 (TBR)

Cookbook

A cookbook man page focuses on results. Just like its name suggests, it presents succinct, step-by-step solutions to a variety of real-world problems around some topic. A cookbook's code examples serve less to enlighten and more to provide quick, paste-ready solutions that the reader can apply immediately to the situation facing them.

クックブックのmanページはresultsに焦点を当てています。 その名前が示すように、あるトピックに関するさまざまな実世界の問題に対して、簡潔でステップバイステップのソリューションを提供します。 クックブックのコード例は、啓蒙にはあまり役に立たず、読者が直面している状況にすぐに適用できる、すぐに貼り付け可能なソリューションを提供するために役立ちます。 (TBR)

A Perl cookbook demonstrates ways that all the tools and techniques explained elsewhere can work together in order to achieve practical results. Any explanation deeper than that belongs in explainers and reference pages, instead. (Certainly, a cookbook can cross-reference other man pages in order to satisfy the curiosity of readers who, with their immediate problems solved, wish to learn more.)

Perlのクックブックは、他の場所で説明されているすべてのツールやテクニックが協力して実用的な結果を達成する方法を示しています。 それより深い説明は、代わりにExplainersやリファレンスページにあります(確かに、クックブックは他のmanページを相互参照して、身近な問題を解決してもっと知りたい読者の好奇心を満たすことができます)。 (TBR)

The most prominent cookbook pages that ship with Perl itself are its many FAQ pages, in particular perlfaq4 and up, which provide short solutions to practical questions in question-and-answer style. perlunicook shows another example, containing a bevy of practical code snippets for a variety of internationally minded text manipulations.

Perl自体に同梱されている最も有名なクックブックページは、その多くのFAQページであり、特にperlfaq4以降では、実用的な問題に対する短いソリューションをQ&A形式で提供しています。 perlunicookは別の例を示しており、国際的な考えを持つさまざまなテキスト操作のための実用的なコードスニペットの束を含んでいます。 (TBR)

(An aside: The Documentation System calls this mode "how-to", but Perl's history of creative cuisine prefers the more kitchen-ready term that we employ here.)

(余談ですが、私<The Documentation System>はこのモードを"how-to"と呼んでいますが、Perlの創作料理の歴史では、ここで採用しているようなキッチンレディという言葉を好んでいます。 (TBR)

Reference

A reference page focuses on description. Austere, uniform, and succinct, reference pages--often arranged into a whole section of mutually similar subpages--lend themselves well to "random access" by a reader who knows precisely what knowledge they need, requiring only the minimum amount of information before returning to the task at hand.

リファレンスページはdescriptionに焦点を当てています。 厳格で統一された簡潔なリファレンスページ--相互に類似したサブページのセクション全体に配置されていることが多い--は、必要な知識を正確に知っている読者による「ランダムアクセス」に適しており、手元のタスクに戻る前に最小限の情報しか必要としません。 (TBR)

Perl's own best example of a reference work is perlfunc, the sprawling man page that details the operation of every function built into Perl, with each function's documentation presenting the same kinds of information in the same order as every other. For an example of a shorter reference on a single topic, look at perlreref.

Perl独自の最良の参考資料の例としては、perlfuncがあります。 perlfuncは、Perlに組み込まれているすべての関数の操作を詳細に記述したmanページで、各関数のマニュアルには同じ種類の情報が同じ順序で記載されています。 単一のトピックに関する短い参考資料の例としては、perlrerefを参照してください。 (TBR)

Module documentation--including that of all the modules listed in perlmodlib--also counts as reference. They follow precepts similar to those laid down by the perlpodstyle man page, such as opening with an example-laden "SYNOPSIS" section, or featuring a "METHODS" section that succinctly lists and defines an object-oriented module's public interface.

モジュール文書--perlmodlibにリストされているすべてのモジュールを含む--も参照としてカウントされます。 モジュール文書は、perlpodstyleのmanページに記載されているものと同様の指示に従っています。 例えば、例を含む"SYNOPSIS"セクションで開始したり、オブジェクト指向モジュールのパブリックインターフェイスを簡潔にリストし定義する"METHODS"セクションを特集したりします。 (TBR)

Explainer

Explainer pages focus on discussion. Each explainer dives as deep as needed into some Perl-relevant topic, taking all the time and space needed to give the reader a thorough understanding of it. Explainers mean to impart knowledge through study. They don't assume that the student has a Perl interpreter fired up and hungry for immediate examples (as with a tutorial), or specific Perl problems that they need quick answers for (which cookbooks and reference pages can help with).

Explainerページはdiscussionに焦点を当てています。 各Explainerは、Perlに関連するトピックについて必要なだけ深く掘り下げ、読者にそのトピックを完全に理解してもらうために必要な時間とスペースをすべて取り入れています。 Explainerとは、学習を通じて知識を伝えることを意味します。 Explainerは、学習者がPerlインタープリターを持っていて、すぐに役立つ例(チュートリアルなど)や、Perlに関する具体的な問題(どの料理本やリファレンスページが役立つか)を求めているとは想定していません。 (TBR)

Outside of its reference pages, most of Perl's manual belongs to this mode. This includes the majority of the man pages whose names start with "perl". A fine example is perlsyn, the Perl Syntax page, which explores the whys and wherefores of Perl's unique syntax in a wide-ranging discussion laden with many references to the language's history, culture, and driving philosophies.

リファレンスページ以外では、Perlのマニュアルのほとんどはこのモードに属しています。 これには、"perl"で始まる名前のマニュアルページの大部分が含まれています。 優れた例として、Perl Syntaxページであるperlsynがあります。 このページでは、Perlの歴史、文化、駆動哲学に関する多くの参考文献を集めた広範な議論の中で、Perl独自の構文のなぜなのか、なぜなのかを探っています。 (TBR)

Perl's explainer pages give authors a chance to explore Perl's penchant for TMTOWTDI, illustrating alternate and even obscure ways to use the language feature under discussion. However, as the remainder of this guide discusses, the ideal Perl documentation manages to deliver its message clearly and concisely, and not confuse mere wordiness for completeness.

Perlの解説ページでは、PerlのTMTOWTDIへの傾向を探る機会を提供しており、議論中の言語機能を使用する別の、あるいはあいまいな方法を説明しています。 しかし、このガイドの残りの部分で説明しているように、理想的なPerl文書は、そのメッセージを明確かつ簡潔に伝えることができ、単なる言葉づかいを完全さと混同することはありません。 (TBR)

Further notes on documentation modes

Keep in mind that the purpose of this categorization is not to dictate content--a very thorough explainer might contain short reference sections of its own, for example, or a reference page about a very complex function might resemble an explainer in places (e.g. open). Rather, it makes sure that the authors and contributors of any given man page agree on what sort of audience that page addresses.

このカテゴリー化の目的は内容を記述することではないことに注意してください--非常に詳細な解説者には、それ自体の短い参照セクションが含まれている場合や、非常に複雑な関数に関する参照ページが解説者に似ている場合があります(例:open)。 むしろ、あるmanページの著者と寄稿者が、そのページが扱う読者の種類について合意していることを確認します。 (TBR)

If a new or otherwise uncategorized man page presents itself as resistant to fitting into only one of the four modes, consider breaking it up into separate pages. That may mean creating a new "perl[...]" man page, or (in the case of module documentation) making new packages underneath that module's namespace that serve only to hold additional documentation. For instance, Example::Module's reference documentation might include a see-also link to Example::Module::Cookbook.

新しい、あるいはカテゴリ化されていないマニュアルページが、4つのモードのうちの1つだけに適合することに抵抗があると示す場合は、別のページに分割することを検討してください。 これは、新しい"perl[.]"マニュアルページを作成するか、(モジュール文書の場合)そのモジュールの名前空間の下に追加の文書を保持するだけの新しいパッケージを作成することを意味します。 例えば、Example::Moduleのリファレンス文書には、Example::Module::Cookbookへのsee-alsoリンクが含まれている場合があります。 (TBR)

Perl's several man pages about Unicode--comprising a short tutorial, a thorough explainer, a cookbook, and a FAQ--provide a fine example of spreading a complicated topic across several man pages with different and clearly indicated purposes.

PerlのUnicodeに関するいくつかのマニュアルページ(短いチュートリアル、徹底した解説、料理本、FAQから構成されています)は、複雑なトピックを、明確に示された異なる目的を持ついくつかのマニュアルページに広げていくための素晴らしい例を提供しています。 (TBR)

Assume readers' intelligence, but not their knowledge

Perl has grown a great deal from its humble beginnings as a tool for people already well versed in C programming and various Unix utilities. Today, a person learning Perl might come from any social or technological background, with a range of possible motivations stretching far beyond system administration.

Perlは、CプログラミングやさまざまなUnixユーティリティーに精通している人たちのためのツールとして、ささやかな始まりから大きく成長してきました。 今日では、Perlを学ぶ人は、社会や技術の背景を問わず、さまざまな動機がシステム管理をはるかに超えている可能性があります。 (TBR)

Perl's core documentation must recognize this by making as few assumptions as possible about the reader's prior knowledge. While you should assume that readers of Perl's documentation are smart, curious, and eager to learn, you should not confuse this for pre-existing knowledge about any other technology, or even programming in general--especially in tutorial or introductory material.

Perlのコア文書では、読者の事前知識についてできるだけ多くの前提を置くことなく、このことを認識する必要があります。 Perlの文書の読者は、頭が良く、好奇心が強く、学びたいと思っているはずですが、これを他の技術やプログラミング全般(特にチュートリアルや入門資料)に関する既存の知識と混同しないでください。 (TBR)

Keep Perl's documentation about Perl

Outside of pages tasked specifically with exploring Perl's relationship with other programming languages, the documentation should keep the focus on Perl. Avoid drawing analogies to other technologies that the reader may not have familiarity with.

特にPerlと他のプログラミング言語との関係を調べることを目的としたページ以外では、この文書はPerlに焦点を当てるべきです。 読者があまり知らない他の技術に類似したものを書くことは避けてください。 (TBR)

For example, when documenting one of Perl's built-in functions, write as if the reader is now learning about that function for the first time, in any programming language.

たとえば、Perlの組み込み関数の1つを記述する場合は、読者がその関数について、どのプログラミング言語でも初めて学習したかのように記述します。 (TBR)

Choosing to instead compare it to an equivalent or underlying C function will probably not illuminate much understanding in a contemporary reader. Worse, this can risk leaving readers unfamiliar with C feeling locked out from fully understanding of the topic--to say nothing of readers new to computer programming altogether.

その代わりに、それを同等の、あるいは基礎となるC関数と比較することを選択しても、現代の読者の理解にあまり光を当てることにはならないでしょう。 さらに悪いことに、Cに馴染みのない読者このトピックを完全に理解することから締め出されたように感じる可能性があります。 言うまでもなく、コンピュータープログラミングにまったく不慣れな読者はなおさらです。 (TBR)

If, however, that function's ties to its C roots can lead to deeper understanding with practical applications for a Perl programmer, you may mention that link after its more immediately useful documentation. Otherwise, omit this information entirely, leaving it for other documentation or external articles more concerned with examining Perl's underlying implementation details.

しかし、その関数とCのルートとの結びつきが、Perlプログラマーのための実用的なアプリケーションをより深く理解することにつながるのであれば、すぐに役立つ文書の後にそのリンクを挙げることができます。 そうでない場合は、この情報を完全に省略し、Perlの基礎となる実装の詳細を調べることに関心を持つ他の文書や外部の記事に残してください。 (TBR)

Deploy jargon when needed, but define it as well

Domain-specific jargon has its place, especially within documentation. However, if a man page makes use of jargon that a typical reader might not already know, then that page should make an effort to define the term in question early-on--either explicitly, or via cross reference.

ドメイン固有の専門用語には、特に文書内での役割があります。 ただし、一般的な読者がまだ知らない専門用語をmanページで使用している場合は、そのページで問題の用語を早期に(明示的に、または相互参照によって)定義するように努力する必要があります。 (TBR)

For example, Perl loves working with filehandles, and as such that word appears throughout its documentation. A new Perl programmer arriving at a man page for the first time is quite likely to have no idea what a "filehandle" is, though. Any Perl man page mentioning filehandles should, at the very least, hyperlink that term to an explanation elsewhere in Perl's documentation. If appropriate--for example, in the lead-in to open function's detailed reference--it can also include a very short in-place definition of the concept for the reader's convenience.

例えば、Perlはファイルハンドルを扱うのが好きなので、Perlの文書全体にその言葉が出てきます。 初めてmanページを手にしたPerlプログラマーは、「ファイルハンドル」とは何かを知らない可能性が非常に高くなります。 ファイルハンドルについて言及しているPerlのmanページは、少なくとも、その用語をPerlの文書のどこかにある説明にハイパーリンクする必要があります。 open function's detailed referenceへのリードインなど、適切な場合には、読者の便宜のために、この概念の非常に短い定義をその場で含めることもできます。 (TBR)

Use meaningful variable and symbol names in examples

When quickly sketching out examples, English-speaking programmers have a long tradition of using short nonsense words as placeholders for variables and other symbols--such as the venerable foo, bar, and baz. Example code found in a programming language's official, permanent documentation, however, can and should make an effort to provide a little more clarity through specificity.

簡単に例を説明すると、英語を話すプログラマは、変数やその他の記号(由緒あるfoobarbazなど)のプレースホルダとして短いナンセンスワードを使用する長い伝統を持っています。 しかし、プログラミング言語の公式で永続的な文書にあるサンプルコードは、特異性を通してもう少し明確にする努力をすることができますし、すべきです。 (TBR)

Whenever possible, code examples should give variables, classes, and other programmer-defined symbols names that clearly demonstrate their function and their relationship to one another. For example, if an example requires that one class show an "is-a" relationship with another, consider naming them something like Apple and Fruit, rather than Foo and Bar. Similarly, sample code creating an instance of that class would do better to name it $apple, rather than $baz.

可能な限り、コード例では、変数、クラス、その他のプログラマが定義したシンボルに、その機能と相互の関係を明確に示す名前を付ける必要があります。 たとえば、あるクラスが別のクラスと「is-a」関係を示す必要がある場合は、FooBarではなく、AppleFruitのような名前を付けることを検討してください。 同様に、そのクラスのインスタンスを作成するサンプルコードでは、$bazではなく$appleという名前を付ける方が適切です。 (TBR)

Even the simplest examples benefit from clear language using concrete words. Prefer a construct like for my $item (@items) { ... } over for my $blah (@blah) { ... }.

最も単純な例であっても、具体的な単語を使用した明確な言語の利点があります。 for my$blah(@blah){.}よりもfor my$item(@items){.}のような構文を優先してください。 (TBR)

Write in English, but not just for English-speakers

While this style guide does specify American English as the documentation's language for the sake of internal consistency, authors should avoid cultural or idiomatic references available only to English-speaking Americans (or any other specific culture or society). As much as possible, the language employed by Perl's core documentation should strive towards cultural universality, if not neutrality. Regional turns of phrase, examples drawing on popular-culture knowledge, and other rhetorical techniques of that nature should appear sparingly, if at all.

このスタイルガイドでは、内部一貫性のために文書の言語としてアメリカ英語を指定していますが、著者は、英語を話すアメリカ人(または他の特定の文化や社会)のみが利用できる文化やイディオムのリファレンスを避けるべきです。 可能な限り、Perlのコア文書で使用されている言語は、中立ではないとしても、文化の普遍性に向けて努力すべきです。 地域ごとの言い回し、大衆文化の知識を利用した例、その他の修辞技法は、あったとしても控えめに表示されるべきです。 (TBR)

Authors should feel free to let more freewheeling language flourish in "second-order" documentation about Perl, like books, blog entries, and magazine articles, published elsewhere and with a narrower readership in mind. But Perl's own docs should use language as accessible and welcoming to as wide an audience as possible.

著者は、書籍、ブログ記事、雑誌記事など、Perlに関する「二次」文書において、より自由な言語を自由に使用できるようにすべきです。 これらは他の場所で、より狭い閲読率を念頭に置いて出版されています。 しかし、Perl自身の文書では、できるだけ多くの読者に対してアクセス可能で歓迎される言語を使用すべきです。 (TBR)

Omit placeholder text or commentary

Placeholder text does not belong in the documentation that ships with Perl. No section header should be followed by text reading only "Watch this space", "To be included later", or the like. While Perl's source files may shift and alter as much as any other actively maintained technology, each released iteration of its technology should feel complete and self-contained, with no such future promises or other loose ends visible.

プレースホルダテキストは、Perlに付属の文書には含まれていません。 セクションヘッダーの後に、"Watch this space"や"To be included later"などと読むだけのテキストを置くべきではありません。 Perlのソースファイルは他の活発に維持されている技術と同じように変化し変化する可能性がありますが、その技術のリリースされた各イテレーションは完全で自己完結したものと感じられ、そのような将来の約束やその他のあいまいな目的は見えないはずです。 (TBR)

Take advantage of Perl's regular release cycle. Instead of cluttering the docs with flags promising more information later--the presence of which do not help readers at all today--the documentation's maintenance team should treat any known documentation absences as an issue to address like any other in the Perl project. Let Perl's contributors, testers, and release engineers address that need, and resist the temptation to insert apologies, which have all the utility in documentation as undeleted debug messages do in production code.

Perlの定期的なリリースサイクルを活用してください。 文書にフラグを付けて後で詳細情報を約束するような早口言語症を与えるのではなく(その存在は今日の読者にはまったく役に立たない)、文書の保守チームは、既知の文書の不在をPerlプロジェクトの他の問題と同じように対処すべき問題として扱うべきです。 Perlのコントリビュータ、テスター、リリースエンジニアにその必要性に対処させ、謝罪を挿入する誘惑に抵抗させましょう。 謝罪は、削除されないデバッグメッセージが実動コードで行うように、文書にもすべての利点があります。 (TBR)

Apply section-breaks and examples generously

No matter how accessible their tone, the sight of monolithic blocks of text in technical documentation can present a will-weakening challenge for the reader. Authors can improve this situation through breaking long passages up into subsections with short, meaningful headers.

彼らのトーンがどれほどアクセス可能であっても、技術文書の中にモノリシックなテキストのブロックがあることは、読者に意志を弱める挑戦を提示する可能性があります。 著者は、長い文章を短くて意味のあるヘッダーを持つサブセクションに分割することで、この状況を改善できます。 (TBR)

Since every section-header in Pod also acts as a potential end-point for a cross-reference (made via Pod's L<...> syntax), putting plenty of subsections in your documentation lets other man pages more precisely link to a particular topic. This creates hyperlinks directly to the most appropriate section rather than to the whole page in general, and helps create a more cohesive sense of a rich, consistent, and interrelated manual for readers.

Podのすべてのセクションヘッダは、相互参照(PodのL<.>構文を介して行われる)の潜在的なエンドポイントとしても機能するので、文書にたくさんのサブセクションを置くことで、他のmanページが特定のトピックにもっと正確にリンクすることができます。 これにより、一般的なページ全体ではなく、最も適切なセクションに直接ハイパーリンクが作成され、読者のために、リッチで一貫性のある相互に関連するマニュアルのよりまとまりのある感覚を作り出すのに役立ちます。 (TBR)

Among the four documentation modes, sections belong more naturally in tutorials and explainers. The step-by-step instructions of cookbooks, or the austere definitions of reference pages, usually have no room for them. But authors can always make exceptions for unusually complex concepts that require further breakdown for clarity's sake.

4つの文書モードの中で、セクションはより自然にチュートリアルと解説者に属しています。 クックブックのステップバイステップの説明や、リファレンスページの厳格な定義には、通常、それらのためのスペースがありません。 しかし、著者は、明確にするためにさらに詳細な分析を必要とする異常に複雑な概念については、常に例外を設けることができます。 (TBR)

Example code, on the other hand, can be a welcome addition to any mode of documentation. Code blocks help break up a man page visually, reassuring the reader that no matter how deep the textual explanation gets, they are never far from another practical example showing how it all comes together using a small, easy-to-read snippet of tested Perl code.

一方、サンプルコードは、文書のどのモードへの追加としても歓迎されます。 コードブロックは、マニュアルページを視覚的に分割するのに役立ち、テキストによる説明がどんなに深くなっても、テストされたPerlコードの小さくて読みやすいスニペットを使用してすべてがどのように組み合わされるかを示す別の実践的な例から遠くないことを読者に安心させます。 (TBR)

Lead with common cases and best practices

Perl famously gives programmers more than one way to do things. Like any other long-lived programming language, Perl has also built up a large, community-held notion of best practices, blessing some ways to do things as better than others, usually for the sake of more maintainable code.

Perlは、プログラマーに複数の方法を提供することで有名です。 他の長きにわたるプログラミング言語と同様に、Perlもまた、コミュニティが支持する大規模なベストプラクティスの概念を構築し、ある方法が他の方法よりも優れていることを祝福しています。 これは通常、コードをより保守しやすいものにするためです。 (TBR)

Show the better ways first

Whenever it needs to show the rules for a technique which Perl provides many avenues for, the documentation should always lead with best practices. And when discussing some part of the Perl toolkit with many applications, the docs should begin with a demonstration of its application to the most common cases.

Perlが多くの手段を提供する手法のルールを示す必要がある場合には、文書は常にベストプラクティスを示すべきです。 また、Perlツールキットの一部を多くのアプリケーションで説明する場合には、最も一般的なケースへの適用のデモンストレーションから始めるべきです。 (TBR)

The open function, for example, has myriad potential uses within Perl programs, but most of the time programmers--and especially those new to Perl--turn to this reference because they simply wish to open a file for reading or writing. For this reason, open's documentation begins there, and only descends into the function's more obscure uses after thoroughly documenting and demonstrating how it works in the common case. Furthermore, while engaging in this demonstration, the open documentation does not burden the reader right away with detailed explanations about calling open via any route other than the best-practice, three-argument style.

例えば、open関数はPerlプログラム内で無数の潜在的な用途を持っていますが、私<ほとんどの場合>プログラマー、特にPerlに慣れていないプログラマーは、単にファイルを開いて読み書きしたいだけなので、このリファレンスに目を向けます。 このため、openの文書はそこから始まり、一般的なケースでどのように機能するかを徹底的に文書化し、実証した後に、関数のよりあいまいな用途へと進んでいきます。 さらに、このデモンストレーションを行っている間、openの文書は、ベストプラクティスである3つの引数スタイル以外の方法でopenを呼び出すことについての詳細な説明をすぐに読者に負担させるものではありません。 (TBR)

Show the lesser ways when needed

Sometimes, thoroughness demands documentation of deprecated techniques. For example, a certain Perl function might have an alternate syntax now considered outmoded and no longer best-practice, but which a maintainer of a legacy project might quite reasonably encounter when exploring old code. In this case, these features deserve documentation, but couched in clarity that modern Perl avoids such structures, and does not recommend their use in new projects.

徹底させるために、廃止された手法の文書化が必要になるになることもあります。 例えば、あるPerl関数には現在時代遅れでベストプラクティスではないと考えられている代替構文がありますが、レガシープロジェクトのメンテナが古いコードを調査する際に遭遇する可能性があります。 この場合、これらの機能は文書化に値しますが、現代のPerlはそのような構造を避けており、新しいプロジェクトでの使用を推奨していないことを明確に説明しています。 (TBR)

Another way to look at this philosophy (and one borrowed from our friends on Python's documentation team) involves writing while sympathizing with a programmer new to Perl, who may feel uncertain about learning a complex concept. By leading that concept's main documentation with clear, positive examples, we can immediately give these readers a simple and true picture of how it works in Perl, and boost their own confidence to start making use of this new knowledge. Certainly we should include alternate routes and admonitions as reasonably required, but we needn't emphasize them. Trust the reader to understand the basics quickly, and to keep reading for a deeper understanding if they feel so driven.

この哲学を見るもう1つの方法(およびPythonの文書チームの borrowed from our friends)は、複雑な概念を学ぶことに不安を感じているPerl初心者のプログラマーに共感しながら書くことです。 その概念の主要な文書を明確で肯定的な例で導くことによって、Perlでどのように動作するかの単純で真実の図をすぐに読者に提供することができ、読者自身が自信を持ってこの新しい知識を活用し始めることができます。 もちろん、合理的に必要とされる代替ルートや注意事項を含める必要がありますが、強調する必要はありません。 読者が基本をすばやく理解し、読者が気になるようであれば、さらに深く理解するために本を読み続けてください。 (TBR)

Document Perl's present

Perl's documentation should stay focused on Perl's present behavior, with a nod to future directions.

Perlの文書は、Perlの現在の振る舞いに焦点を当て、将来の方向性にも注意を向けるべきです。 (TBR)

Recount the past only when necessary

When some Perl feature changes its behavior, documentation about that feature should change too, and just as definitively. The docs have no obligation to keep descriptions of past behavior hanging around, even if attaching clauses like "Prior to version 5.10, [...]".

一部のPerl機能の動作が変更された場合には、その機能に関する文書も変更されるはずです。 文書には、「Prior to version 5.10,[.]」のような節を付けても、過去の動作に関する記述を保持する義務はありません。 (TBR)

Since Perl's core documentation is part of Perl's source distribution, it enjoys the same benefits of versioning and version-control as the source code of Perl itself. Take advantage of this, and update the text boldly when needed. Perl's history remains safe, even when you delete or replace outdated information from the current version's docs.

Perlのコア文書はPerlのソースディストリビューションの一部であるため、Perl自体のソースコードと同じバージョン管理とバージョン管理の利点を享受できます。 この利点を活用し、必要に応じて大胆にテキストを更新してください。 現在のバージョンの文書から古い情報を削除したり置き換えたりしても、Perlの履歴は安全です。 (TBR)

Perl's docs can acknowledge or discuss former behavior when warranted, including notes that some feature appeared in the language as of some specific version number. Authors should consider applying principles similar to those for deprecated techniques, as described above: make the information present, but not prominent.

Perlの文書では、正当な理由があれば、以前の動作を認めたり議論したりすることができます。 その中には、ある特定のバージョン番号の時点で言語に何らかの機能が現れたという記述も含まれています。 著者は、廃止されたテクニックの場合と同様の原則を適用することを考慮すべきです。 as described above:情報を提示するが目立たないようにする。 (TBR)

Otherwise, keep the past in the past. A manual uncluttered with outdated instruction stays more succinct and relevant.

そうでなければは、過去を過去のままにします。 古くなった指示の詰まったマニュアルは、より簡潔で適切なものになります。 (TBR)

Describe the uncertain future with care

Perl features marked as "experimental"--those that generate warnings when used in code not invoking the experimental pragma--deserve documentation, but only in certain contexts, and even then with caveats. These features represent possible new directions for Perl, but they have unstable interfaces and uncertain future presence.

「実験的」(experimentalプラグマを呼び出さないコードで使用された場合に警告を生成する機能)としてマークされたPerlの機能は、文書化する価値がありますが、特定の状況でのみ、また警告が表示されます。 これらの機能は、Perlの新たな方向性を示す可能性がありますが、不安定なインターフェイスと不確実な将来の存在があります。 (TBR)

The documentation should take both implications of "experimental" literally. It should not discourage these features' use by programmers who wish to try out new features in projects that can risk their inherent instability; this experimentation can help Perl grow and improve. By the same token, the docs should downplay these features' use in just about every other context.

文書は、文字通り"実験的"という両方の意味を持つべきです。 プロジェクトで新しい機能を試したいプログラマが、本来の不安定性を危険にさらす可能性のあるこれらの機能を使用することを妨げるべきではありません。 この実験はPerlの成長と改善を助けることができます。 同様に、文書は、他のほとんどすべての状況でこれらの機能を使用することを軽視すべきです。 (TBR)

Introductory or overview material should omit coverage of experimental features altogether.

序文または概要の資料では、実験的特徴の網羅を完全に省略すべきである。 (TBR)

More thorough reference materials or explanatory articles can include experimental features, but needs to clearly mark them as such, and not treat them with the same prominence as Perl's stable features. Using unstable features seldom coincides with best practices, and documentation that puts best practices first should reflect this.

より詳細な参考資料や解説記事には、実験的な機能を含めることができますが、それを明確に示す必要があり、Perlの安定した機能と同じように目立たないように扱う必要はありません。 不安定な機能を使用することはベストプラクティスと一致することはほとんどなく、 puts best practices first という文書には、これを反映する必要があります。 (TBR)

The documentation speaks with one voice

Even though it comes from many hands and minds, criss-crossing through the many years of Perl's lifetime, the language's documentation should speak with a single, consistent voice. With few exceptions, the docs should avoid explicit first-person-singular statements, or similar self-reference to any individual's contributor's philosophies or experiences.

Perlの文書は、多くの人と心から、Perlの生涯の長い年月をかけて交差してきましたが、一貫した単一の声で記述する必要があります。 少数の例外を除いて、文書は、明確な一人称単一の記述や、個人の寄稿者の哲学や経験に対する同様の自己参照を避けるべきです。 (TBR)

Perl did begin life as a deeply personal expression by a single individual, and this famously carried through the first revisions of its documentation as well. Today, Perl's community understands that the language's continued development and support comes from many people working in concert, rather than any one person's vision or effort. Its documentation should not pretend otherwise.

Perlは一人の個人による非常に個人的な表現として誕生しましたが、このことは文書の最初の改訂版でもよく知られています。 今日、Perlのコミュニティは、言語の継続的な開発とサポートは、一人の人のビジョンや努力ではなく、協力して働く多くの人たちによってもたらされていることを理解しています。 Perlの文書は、そうでないふりをすべきではありません。 (TBR)

The documentation should, however, carry forward the best tradition that Larry Wall set forth in the language's earliest days: Write both economically and with a humble, subtle wit, resulting in a technical manual that mixes concision with a friendly approachability. It avoids the dryness that one might expect from technical documentation, while not leaning so hard into overt comedy as to distract and confuse from the nonetheless-technical topics at hand.

しかし、文書は、Larry Wallが言語の初期に述べた最高の伝統を継承する必要があります:経済的に、そして謙虚で繊細な機知を持って書くことで、その結果、簡潔さと親しみやすさを混ぜた技術マニュアルが作成されます。 それは、技術的な文書に期待されるようなドライネスを回避すると同時に、目の前の技術的なトピックから注意をそらしたり混乱させたりするような露骨なコメディーに熱心になることもありません。 (TBR)

Like the best written works, Perl's documentation has a soul. Get familiar with it as a reader to internalize its voice, and then find your own way to express it in your own contributions. Writing clearly, succinctly, and with knowledge of your audience's expectations will get you most of the way there, in the meantime.

最も優れた著作と同様に、Perlの文書にも魂があります。 読者としてPerlに慣れ親しんでその声を内部化し、自分自身の貢献の中でそれを表現する独自の方法を見つけてください。 明確に、簡潔に、そして読者の期待を理解した上で書くことで、その間の大部分を得ることができます。 (TBR)

Every line in the docs--whether English sentence or Perl statement--should serve the purpose of bringing understanding to the reader. Should a sentence exist mainly to make a wry joke that doesn't further the reader's knowledge of Perl, set it aside, and consider recasting it into a personal blog post or other article instead.

英文であろうとPerl文であろうと、文書のすべての行は、読者に理解をもたらす目的に役立つはずです。 Perlに関する読者の知識を深めることができないような下品なジョークを作るための文が主に存在する場合は、それを脇に置いて、個人的なブログ記事や他の記事に再投稿することを検討してください。 (TBR)

Write with a light heart, and a miserly hand.

軽い心と卑劣な手で書きなさい. (TBR)

INDEX OF PREFERRED TERMS

As noted above, this guide "inherits" all the preferred terms listed in the Chicago Manual of Style, 17th edition, and adds the following terms of particular interest to Perl documentation.

As noted above このガイドは、Chicago Manual of Style,17 th editionにリストされているすべての優先用語を「継承」し、Perl文書に特に関心のある次の用語を追加しています。 (TBR)

built-in function

Not "builtin".

"builtin"ではありません。 (TBR)

Darwin

See macOS.

Mac OSを参照。 (TBR)

macOS

Use this term for Apple's operating system instead of "Mac OS X" or variants thereof.

この用語は、「Mac OS X」またはその変種ではなく、Appleのオペレーティングシステムに使用してください。 (TBR)

This term is also preferable to "Darwin", unless one needs to refer to macOS's Unix layer specifically.

この用語は、特にmacOSのUnix層を参照する必要がない限り、"Darwin"よりも好ましい。 (TBR)

man page

One unit of Unix-style documentation. Not "manpage". Preferable to "manual page".

Unixスタイルの文書の1単位。 "manpage"ではなく、"manual page"よりも望ましい。 (TBR)

Perl; perl

The name of the programming language is Perl, with a leading capital "P", and the remainder in lowercase. (Never "PERL".)

プログラミング言語の名前はPerlです。 先頭の大文字は"P"、残りは小文字です("PERL"は使用しません)。 (TBR)

The interpreter program that reads and executes Perl code is named "perl", in lowercase and in monospace (as with any other command name).

Perlコードを読み取って実行するインタープリタープログラムは、小文字とモノスペースで「perl」と名付けられます(他のコマンド名と同様)。 (TBR)

Generally, unless you are specifically writing about the command-line perl program (as, for example, perlrun does), use "Perl" instead.

一般ラインのperlプログラムについて特に記述していない限り(たとえば、perlrunのように)、通常は「Perl」を使用します。 (TBR)

Perl 5

Documentation need not follow Perl's name with a "5", or any other number, except during discussions of Perl's history, future plans, or explicit comparisons between major Perl versions.

Perlの歴史、将来の計画、主要なPerlバージョン間の明示的な比較を議論する場合を除き、文書はPerlの名前の後に「5」や他の数字を続ける必要はありません。 (TBR)

Before 2019, specifying "Perl 5" was sometimes needed to distinguish the language from Perl 6. With the latter's renaming to "Raku", this practice became unnecessary.

2019以前は、Perl 6と言語を区別するために「Perl 5」を指定する必要がありましたが、Perl 6が「楽」に名称変更されたため、この方法は不要になりました。 (TBR)

Perl 6

See Raku.

Raku を参照してください。

Perl 5 Porters, the; porters, the; p5p

The full name of the team responsible for Perl's ongoing maintenance and development is "the Perl 5 Porters", and this sobriquet should be spelled out in the first mention within any one document. It may thereafter call the team "the porters" or "p5p".

Perlの継続的な保守と開発を担当するチームのフルネームは"Perl 5 Porters"です。 この名前は、どの文書でも最初に記述されるべきです。 その後、チームを"the porters"または"p5p"と呼ぶことができます。 (TBR)

Not "Perl5 Porters".

"Perl5 Porter"ではありません。 (TBR)

program

The most general descriptor for a stand-alone work made out of executable Perl code. Synonymous with, and preferable to, "script".

実行可能なPerlコードで作成されたスタンドアロン作業の最も一般的な記述子。 "script"と同義であり、"script"よりも望ましい。 (TBR)

Raku

Perl's "sister language", whose homepage is https://raku.org.

Perlの「姉妹言語」で、ホームページは https://raku.org です。

Previously known as "Perl 6". In 2019, its design team renamed the language to better reflect its identity as a project independent from Perl. As such, Perl's documentation should always refer to this language as "Raku" and not "Perl 6".

以前は「Perl 6」として知られていました。 2019年に、Perlの設計チームは、Perlから独立したプロジェクトとしてのアイデンティティをよりよく反映するために、この言語の名前を変更しました。 そのため、Perlの文書では、この言語を常に「Raku」と呼ぶべきであり、「Perl 6」と呼ぶべきではありません。 (TBR)

script

See program.

program を参照してください。

semicolon

Perl code's frequently overlooked punctuation mark. Not "semi-colon".

見過ごされることが多いPerlコードの約物。 「セミコロン」ではありません。 (TBR)

Unix

Not "UNIX", "*nix", or "Un*x". Applicable to both the original operating system from the 1970s as well as all its conceptual descendants. You may simply write "Unix" and not "a Unix-like operating system" when referring to a Unix-like operating system.

"UNIX"、"*nix"、"Un*x"ではありません。 1970年代のオリジナルのオペレーティングシステムとそのすべての概念的な子孫の両方に適用できます。 Unixライクなオペレーティングシステムを参照する場合は、"Unix"とだけ記述し、"Unixライクなオペレーティングシステム"とは記述できません。 (TBR)

SEE ALSO

作者

This guide was initially drafted by Jason McIntosh (jmac@jmac.org), under a grant from The Perl Foundation.

このガイドは当初、JJason McIntosh (jmac@jmac.org) が The Perl Foundation の 助成を受けて作成しました。