repo_zf1/documentation/manual/ja/ref/documentation-standard.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<appendix id="doc-standard">
    <title>Zend Framework ドキュメント標準(一部日本語)</title>

    <sect1 id="doc-standard.overview">
        <title>概要</title>

        <sect2 id="doc-standard.overview.scope">
            <title>スコープ</title>

            <para>
                <!-- TODO : to be translated -->
                This document provides guidelines for creation of the end-user
                documentation found within Zend Framework. It is intended as a
                guide to Zend Framework contributors, who must write
                documentation as part of component contributions, as well as to
                documentation translators. The standards contained herein are
                intended to ease translation of documentation, minimize
                visual and stylistic differences between different documentation
                files, and make finding changes in documentation easier with
                <command>diff</command> tools.
            </para>

            <para>
                You may adopt and/or modify these standards in accordance with the terms of our
                <ulink url="http://framework.zend.com/license">license</ulink>.
            </para>

            <para>
                Topics covered in Zend Framework's documentation standards include documentation
                file formatting and recommendations for documentation quality.
            </para>
        </sect2>
    </sect1>

    <sect1 id="doc-standard.file-formatting">
        <title>ドキュメントファイル形式</title>

        <sect2 id="doc-standard.file-formatting.xml-tags">
            <title>XML タグ</title>

            <para>
                各マニュアルのファイル先頭に、下記の <acronym>XML</acronym> 宣言がなければなりません。
            </para>

            <programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
]]></programlisting>

            <para>
                翻訳した言語の <acronym>XML</acronym> ファイルには、
                対応する翻訳元の英語ファイルのリビジョンに等しいリビジョン・タグもなければなりません。
            </para>

            <programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 14978 -->
<!-- Reviewed: no -->
]]></programlisting>
        </sect2>

        <sect2 id="doc-standard.file-formatting.max-line-length">
            <title>行の最大長</title>

            <!-- TODO : to be translated -->
            <para>
                The maximum line length, including tags, attributes, and indentation, is not to
                exceed 100 characters. There is only one exception to this rule: attribute and value
                pairs are allowed to exceed the 100 chars as they are not allowed to be separated.
            </para>
        </sect2>

        <sect2 id="doc-standard.file-formatting.indentation">
            <title>インデント</title>

            <para>インデントは、空白文字４つで構成されなければなりません。タブは許されません。</para>

            <para>同じレベルにあるタグは、同じインデントを持たなければなりません。</para>

            <programlisting language="xml"><![CDATA[
<sect1>
</sect1>

<sect1>
</sect1>
]]></programlisting>

            <para>
                前のタグの１つ下のレベルのタグは、さらに4つの空白文字でインデントされなければなりません。
            </para>

            <programlisting language="xml"><![CDATA[
<sect1>
    <sect2>
    </sect2>
</sect1>
]]></programlisting>

            <para>
                複数のブロック・タグは、同一行の中では許されません。
                しかしながら、インライン・タグは複数許されます。
            </para>

            <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED: -->
<sect1><sect2>
</sect2></sect1>

<!-- ALLOWED -->
<para>
    <classname>Zend_Magic</classname> does not exist. <classname>Zend_Acl</classname> does.
</para>
]]></programlisting>
        </sect2>

        <sect2 id="doc-standard.file-formatting.line-termination">
            <title>行の終端</title>

            <para>
                行の終端は、Unixテキスト・ファイル規約に従います。
                行は、単一のラインフィード（LF）文字で終わらなければなりません。
                ラインフィード文字は、序数10または16進の0x0Aとして表現されます。
            </para>

            <para>
                注意：
                Apple OS で規約となっているキャリッジ・リターン (<acronym>CR</acronym>;0x0D)
                または、Windows OS で標準となっているキャリッジ・リターンと
                ラインフィード (<acronym>CRLF</acronym>) の組合せ (0x0D, 0x0A)
                を使用してはいけません。
            </para>
        </sect2>

        <sect2 id="doc-standard.file-formatting.empty-tags">
            <title>空のタグ</title>

            <para>
                空のタグは認められません。タグは全てテキストまたは子供タグを含まなければいけません。
            </para>

            <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
<para>
    Some text. <link></link>
</para>

<para>
</para>
]]></programlisting>
        </sect2>

        <sect2 id="doc-standard.file-formatting.whitespace">
            <title>ドキュメント内での空白の利用</title>

            <sect3 id="doc-standard.file-formatting.whitespace.trailing">
                <title>タグ内での空白</title>

                <!-- TODO : to be translated -->
                <para>
                    Opening block tags should have no whitespace immediately following them other
                    than line breaks (and indentation on the following line).
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
<sect1>WHITESPACE
</sect1>
]]></programlisting>

                <para>
                    開始のインライン・タグの直後に空白文字を置いてはいけません。
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
This is the class <classname> Zend_Class</classname>.

<!-- OK -->
This is the class <classname>Zend_Class</classname>.
]]></programlisting>

                <!-- TODO : to be translated -->
                <para>
                    Closing block tags may be preceded by whitespace equivalent to the current
                    indentation level, but no more than that amount.
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
    <sect1>
     </sect1>

<!-- OK -->
    <sect1>
    </sect1>
]]></programlisting>

                <para>
                    終わりのインライン・タグの前に空白文字を置いてはいけません。
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
This is the class <classname>Zend_Class </classname>

<!-- OK -->
This is the class <classname>Zend_Class</classname>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.whitespace.multiple-line-breaks">
                <title>複数行の切断</title>

                <para>
                    複数行内での、またはタグの間での切断は認められません。
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
<para>
    Some text...

    ... and more text
</para>


<para>
    Another paragraph.
</para>

<!-- OK -->
<para>
    Some text...
    ... and more text
</para>

<para>
    Another paragraph.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.whitespace.tag-separation">
                <title>タグの間の分離</title>

                <para>
                    読みやすくするために、同じレベルのタグは空行で分離しなければいけません。
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
<para>
    Some text...
</para>
<para>
    More text...
</para>

<!-- OK -->
<para>
    Some text...
</para>

<para>
    More text...
</para>
]]></programlisting>

                <para>
                    最初の子タグは、空行を置かずに親タグの直下に開かなければいけません。
                    最後の子タグは、親タグが閉じる直前で閉じなければいけません。
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
<sect1>

    <sect2>
    </sect2>

    <sect2>
    </sect2>

    <sect2>
    </sect2>

</sect1>

<!-- OK -->
<sect1>
    <sect2>
    </sect2>

    <sect2>
    </sect2>

    <sect2>
    </sect2>
</sect1>
]]></programlisting>
            </sect3>
        </sect2>

        <sect2 id="doc-standard.file-formatting.program-listing">
            <title>プログラム・リスティング</title>

            <!-- TODO : to be translated -->
            <para>
                The opening <emphasis>&lt;programlisting&gt;</emphasis> tag must indicate the
                appropriate "language" attribute and be indented at the same level as its sibling
                blocks.
            </para>

            <programlisting language="xml"><![CDATA[
<para>Sibling paragraph.</para>

<programlisting language="php">]]>&lt;<![CDATA[![CDATA[
]]></programlisting>

            <para>
                <acronym>CDATA</acronym> should be used around all program listings.
            </para>

            <para>
                <emphasis>&lt;programlisting&gt;</emphasis> sections must not add linebreaks or
                whitespace at the beginning or end of the section, as these are then represented in
                the final output.
            </para>

            <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
<programlisting language="php">]]>&lt;<![CDATA[![CDATA[

$render = "xxx";

]]]]>&gt;<![CDATA[</programlisting>

<!-- OK -->
<programlisting language="php">]]>&lt;<![CDATA[![CDATA[
$render = "xxx";
]]]]>&gt;<![CDATA[</programlisting>
]]></programlisting>

            <para>
                Ending <acronym>CDATA</acronym> and <emphasis>&lt;programlisting&gt;</emphasis>
                tags should be on the same line, without any indentation.
            </para>

            <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
    <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
$render = "xxx";
]]]]>&gt;<![CDATA[
    </programlisting>

<!-- NOT ALLOWED -->
    <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
$render = "xxx";
    ]]]]>&gt;<![CDATA[</programlisting>

<!-- OK -->
    <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
$render = "xxx";
]]]]>&gt;<![CDATA[</programlisting>
]]></programlisting>

            <para>
                The <emphasis>&lt;programlisting&gt;</emphasis> tag should contain the "language"
                attribute with a value appropriate to the contents of the program listing. Typical
                values include "css", "html", "ini", "javascript", "php", "text", and "xml".
            </para>

            <programlisting language="xml"><![CDATA[
<!-- PHP -->
<programlisting language="php">]]>&lt;<![CDATA[![CDATA[

<!-- Javascript -->
<programlisting language="javascript">]]>&lt;<![CDATA[![CDATA[

<!-- XML -->
<programlisting language="xml">]]>&lt;<![CDATA[![CDATA[
]]></programlisting>

            <para>
                For program listings containing only <acronym>PHP</acronym> code,
                <acronym>PHP</acronym> tags (e.g., "&lt;?php", "?&gt;") are not required, and
                should not be used. They simply clutter the narrative, and are implied by the use
                of the <emphasis>&lt;programlisting&gt;</emphasis> tag.
            </para>

            <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
<programlisting language="php"]]>&lt;<![CDATA[![CDATA[<?php
    // ...
?>]]]]>&gt;<![CDATA[</programlisting>

<programlisting language="php"]]>&lt;<![CDATA[![CDATA[
<?php
    // ...
?>
]]]]>&gt;<![CDATA[</programlisting>
]]></programlisting>

            <para>
                Line lengths within program listings should follow the <link
                    linkend="coding-standard.php-file-formatting.max-line-length">coding standards
                recommendations</link>.
            </para>

            <para>
                Refrain from using <methodname>require_once()</methodname>,
                <methodname>require()</methodname>, <methodname>include_once()</methodname>, and
                <methodname>include()</methodname> calls within <acronym>PHP</acronym> listings.
                They simply clutter the narrative, and are largely obviated when using an
                autoloader. Use them only when they are essential to the example.
            </para>

            <note>
                <title>ショートタグを決して使わないで下さい</title>

                <para>
                    Short tags (e.g., "&lt;?", "&lt;?=") should never be used within
                    <emphasis>programlisting</emphasis> or the narrative of a document.
                </para>
            </note>
        </sect2>

        <sect2 id="doc-standard.file-formatting.inline-tags">
            <title>特殊なインラインタグの注意</title>

            <sect3 id="doc-standard.file-formatting.inline-tags.classname">
                <title>classname</title>

                <para>
                    The tag <emphasis>&lt;classname&gt;</emphasis> must be used each time a class
                    name is represented by itself; it should not be used when combined with a
                    method name, variable name, or constant, and no other content is allowed within
                    the tag.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    The class <classname>Zend_Class</classname>.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.varname">
                <title>varname</title>

                <para>
                    Variables must be wrapped in the <emphasis>&lt;varname&gt;</emphasis> tag.
                    Variables must be written using the "$" sigil. No other content is allowed
                    within this tag, unless a class name is used, which indicates a class variable.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    The variable <varname>$var</varname> and the class variable
    <varname>Zend_Class::$var</varname>.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.methodname">
                <title>methodname</title>

                <para>
                    Methods must be wrapped in the <emphasis>&lt;methodname&gt;</emphasis> tag.
                    Methods must either include the full method signature or at the least a pair of
                    closing parentheses (e.g., "()"). No other content is allowed within this tag,
                    unless a class name is used, which indicates a class method.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    The method <methodname>foo()</methodname> and the class method
    <methodname>Zend_Class::foo()</methodname>. A method with a full signature:
    <methodname>foo($bar, $baz)</methodname>
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.constant">
                <title>constant</title>

                <para>
                    Use the <emphasis>&lt;constant&gt;</emphasis> tag when denoting constants.
                    Constants must be written in <acronym>UPPERCASE</acronym>. No other content is
                    allowed within this tag, unless a class name is used, which indicates a class
                    constant.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    The constant <constant>FOO</constant> and the class constant
    <constant>Zend_Class::FOO</constant>.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.filename">
                <title>filename</title>

                <para>
                    Filenames and paths must be wrapped in the
                    <emphasis>&lt;filename&gt;</emphasis> tag. No other content is allowed in this
                    tag.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    The filename <filename>application/Bootstrap.php</filename>.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.command">
                <title>command</title>

                <para>
                    Commands, shell scripts, and program calls must be wrapped in the
                    <emphasis>&lt;command&gt;</emphasis> tag. If the command includes arguments,
                    these should also be included within the tag.
                </para>

                <programlisting language="xml"><![CDATA[
<para>
    Execute <command>zf.sh create project</command>.
</para>
]]></programlisting>
            </sect3>

            <sect3 id="doc-standard.file-formatting.inline-tags.code">
                <title>code</title>

                <para>
                    Usage of the <emphasis>&lt;code&gt;</emphasis> tag is discouraged, in favor of
                    the other inline tasks discussed previously.
                </para>
            </sect3>
        </sect2>

        <sect2 id="doc-standard.file-formatting.block-tags">
            <title>特殊なブロックタグの注意</title>

            <sect3 id="doc-standard.file-formatting.block-tags.title">
                <title>title</title>

                <para>
                    <emphasis>&lt;title&gt;</emphasis> タグで他のタグを保持してはいけません。
                </para>

                <programlisting language="xml"><![CDATA[
<!-- NOT ALLOWED -->
<title>Using <classname>Zend_Class</classname></title>

<!-- OK -->
<title>Using Zend_Class</title>
]]></programlisting>
            </sect3>
        </sect2>
    </sect1>

    <sect1 id="doc-standard.recommendations">
        <title>推奨事項</title>

        <sect2 id="doc-standard.recommendations.editors">
            <title>自動でフォーマットしないエディタを使ってください</title>

            <para>
                ドキュメンテーションを編集するために、
                一般的に、正式な<acronym>XML</acronym>エディタを使用するべきではありません。
                そのようなエディタは、通常、それらの独自の標準に合わせるために、
                既存のドキュメントを自動的にフォーマットします。
                および／または、docbook 標準に厳密には従いません。
                例えば、それらは<acronym>CDATA</acronym>タグを消したり、
                ４スペースの間隔をタブや２スペースに変えたりすることを経験しています。
            </para>

            <para>
                スタイル・ガイドラインは、通常の<command>diff</command>ツールを用いて
                変更した行を翻訳者が確認できるようにするために主に書かれました。
                自動フォーマットは、この処理をより難しくします。
            </para>
        </sect2>

        <sect2 id="doc-standard.recommendations.images">
            <title>イメージを使ってください</title>

            <!-- TODO : to be translated -->
            <para>
                Good images and diagrams can improve readability and comprehension. Use them
                whenever they will assist in these goals. Images should be placed in the
                <filename>documentation/manual/en/figures/</filename> directory, and be named after
                the section identifier in which they occur.
            </para>
        </sect2>

        <sect2 id="doc-standard.recommendations.examples">
            <title>ケースの例を使ってください</title>

            <para>
                Look for good use cases submitted by the community, especially those posted in
                proposal comments or on one of the mailing lists. Examples often illustrate usage
                far better than the narrative does.
            </para>

            <para>
                When writing your examples for inclusion in the manual, follow
                all coding standards and documentation standards.
            </para>
        </sect2>

        <sect2 id="doc-standard.recommendations.phpdoc">
            <title>phpdocの内容を繰り返すことを避けてください</title>

            <para>
                The manual is intended to be a reference guide for end-user usage. Replicating
                the phpdoc documentation for internal-use components and classes is not wanted, and
                the narrative should be focussed on usage, not the internal workings. In any case,
                at this time, we would like the documentation teams to focus on translating the
                English manual, not the phpdoc comments.
            </para>
        </sect2>

        <sect2 id="doc-standard.recommendations.links">
            <title>リンクを使ってください</title>

            <para>
                ドキュメントを繰り返す代わりに、
                マニュアルの他のセクションや外部のソースにリンクしてください。
            </para>

            <para>
                マニュアルの他のセクションへのリンクを
                <emphasis>&lt;link&gt;</emphasis>タグ（リンクのテキストを用意しなければいけません）
                を使って実施できるでしょう。
            </para>

            <programlisting language="xml"><![CDATA[
<para>
    "Link" links to a section, using descriptive text: <link
        linkend="doc-standard.recommendations.links">documentation on
        links</link>.
</para>
]]></programlisting>

            <para>
                外部リソースにリンクするには、<emphasis>&lt;ulink&gt;</emphasis>を使ってください。
            </para>

            <programlisting language="xml"><![CDATA[
<para>
    The <ulink url="http://framework.zend.com/">Zend Framework site</ulink>.
</para>
]]></programlisting>
        </sect2>
    </sect1>
</appendix>