ドキュメントファイル形式

XML タグ

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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->

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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 14978 -->
<!-- Reviewed: no -->

行の最大長

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.

インデント

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

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

<sect1>
</sect1>

<sect1>
</sect1>

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

<sect1>
    <sect2>
    </sect2>
</sect1>

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

<!-- NOT ALLOWED: -->
<sect1><sect2>
</sect2></sect1>

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

行の終端

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

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

空のタグ

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

<!-- NOT ALLOWED -->
<para>
    Some text. <link></link>
</para>

<para>
</para>

ドキュメント内での空白の利用

タグ内での空白

Opening block tags should have no whitespace immediately following them other than line breaks (and indentation on the following line).

<!-- NOT ALLOWED -->
<sect1>WHITESPACE
</sect1>

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

<!-- NOT ALLOWED -->
This is the class <classname> Zend_Class</classname>.

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

Closing block tags may be preceded by whitespace equivalent to the current indentation level, but no more than that amount.

<!-- NOT ALLOWED -->
    <sect1>
     </sect1>

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

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

<!-- NOT ALLOWED -->
This is the class <classname>Zend_Class </classname>

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

複数行の切断

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

<!-- 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>

タグの間の分離

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

<!-- NOT ALLOWED -->
<para>
    Some text...
</para>
<para>
    More text...
</para>

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

<para>
    More text...
</para>

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

<!-- NOT ALLOWED -->
<sect1>

    <sect2>
    </sect2>

    <sect2>
    </sect2>

    <sect2>
    </sect2>

</sect1>

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

    <sect2>
    </sect2>

    <sect2>
    </sect2>
</sect1>

プログラム・リスティング

The opening <programlisting> tag must indicate the appropriate "language" attribute and be indented at the same level as its sibling blocks.

<para>Sibling paragraph.</para>

<programlisting language="php"><![CDATA[

CDATA should be used around all program listings.

<programlisting> sections must not add linebreaks or whitespace at the beginning or end of the section, as these are then represented in the final output.

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

$render = "xxx";

]]></programlisting>

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

Ending CDATA and <programlisting> tags should be on the same line, without any indentation.

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

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

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

The <programlisting> 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".

<!-- PHP -->
<programlisting language="php"><![CDATA[

<!-- Javascript -->
<programlisting language="javascript"><![CDATA[

<!-- XML -->
<programlisting language="xml"><![CDATA[

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

<!-- NOT ALLOWED -->
<programlisting language="php"<![CDATA[<?php
    // ...
?>]]></programlisting>

<programlisting language="php"<![CDATA[
<?php
    // ...
?>
]]></programlisting>

Line lengths within program listings should follow the coding standards recommendations.

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

ショートタグを決して使わないで下さい

Short tags (e.g., "<?", "<?=") should never be used within programlisting or the narrative of a document.

特殊なインラインタグの注意

classname

The tag <classname> 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>
    The class <classname>Zend_Class</classname>.
</para>

varname

Variables must be wrapped in the <varname> 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>
    The variable <varname>$var</varname> and the class variable
    <varname>Zend_Class::$var</varname>.
</para>

methodname

Methods must be wrapped in the <methodname> 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>
    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>

constant

Use the <constant> tag when denoting constants. Constants must be written in UPPERCASE. No other content is allowed within this tag, unless a class name is used, which indicates a class constant.

<para>
    The constant <constant>FOO</constant> and the class constant
    <constant>Zend_Class::FOO</constant>.
</para>

filename

Filenames and paths must be wrapped in the <filename> tag. No other content is allowed in this tag.

<para>
    The filename <filename>application/Bootstrap.php</filename>.
</para>

command

Commands, shell scripts, and program calls must be wrapped in the <command> tag. If the command includes arguments, these should also be included within the tag.

<para>
    Execute <command>zf.sh create project</command>.
</para>

code

Usage of the <code> tag is discouraged, in favor of the other inline tasks discussed previously.

特殊なブロックタグの注意

title

<title> タグで他のタグを保持してはいけません。

<!-- NOT ALLOWED -->
<title>Using <classname>Zend_Class</classname></title>

<!-- OK -->
<title>Using Zend_Class</title>