ZF Zend Framework

Behind the Site

Programmer's Reference Guide

概要
Zend Framework ドキュメント標準(一部日本語)
プログラマ向けリファレンスガイド

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

XML タグ

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

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

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

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!-- EN-Revision: 14978 -->
  3. <!-- 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.

インデント

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

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

  1. <sect1>
  2. </sect1>
  3.  
  4. <sect1>
  5. </sect1>

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

  1. <sect1>
  2.     <sect2>
  3.     </sect2>
  4. </sect1>

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

  1. <!-- NOT ALLOWED: -->
  2. <sect1><sect2>
  3. </sect2></sect1>
  4.  
  5. <!-- ALLOWED -->
  6. <para>
  7.     <classname>Zend_Magic</classname> does not exist. <classname>Zend_Acl</classname> does.
  8. </para>

行の終端

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

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

空のタグ

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

  1. <!-- NOT ALLOWED -->
  2. <para>
  3.     Some text. <link></link>
  4. </para>
  5.  
  6. <para>
  7. </para>

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

タグ内での空白

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

  1. <!-- NOT ALLOWED -->
  2. <sect1>WHITESPACE
  3. </sect1>

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

  1. <!-- NOT ALLOWED -->
  2. This is the class <classname> Zend_Class</classname>.
  3.  
  4. <!-- OK -->
  5. 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.

  1. <!-- NOT ALLOWED -->
  2.     <sect1>
  3.      </sect1>
  4.  
  5. <!-- OK -->
  6.     <sect1>
  7.     </sect1>

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

  1. <!-- NOT ALLOWED -->
  2. This is the class <classname>Zend_Class </classname>
  3.  
  4. <!-- OK -->
  5. This is the class <classname>Zend_Class</classname>

複数行の切断

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

  1. <!-- NOT ALLOWED -->
  2. <para>
  3.     Some text...
  4.  
  5.     ... and more text
  6. </para>
  7.  
  8.  
  9. <para>
  10.     Another paragraph.
  11. </para>
  12.  
  13. <!-- OK -->
  14. <para>
  15.     Some text...
  16.     ... and more text
  17. </para>
  18.  
  19. <para>
  20.     Another paragraph.
  21. </para>

タグの間の分離

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

  1. <!-- NOT ALLOWED -->
  2. <para>
  3.     Some text...
  4. </para>
  5. <para>
  6.     More text...
  7. </para>
  8.  
  9. <!-- OK -->
  10. <para>
  11.     Some text...
  12. </para>
  13.  
  14. <para>
  15.     More text...
  16. </para>

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

  1. <!-- NOT ALLOWED -->
  2. <sect1>
  3.  
  4.     <sect2>
  5.     </sect2>
  6.  
  7.     <sect2>
  8.     </sect2>
  9.  
  10.     <sect2>
  11.     </sect2>
  12.  
  13. </sect1>
  14.  
  15. <!-- OK -->
  16. <sect1>
  17.     <sect2>
  18.     </sect2>
  19.  
  20.     <sect2>
  21.     </sect2>
  22.  
  23.     <sect2>
  24.     </sect2>
  25. </sect1>

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

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

  1. <para>Sibling paragraph.</para>
  2.  
  3. <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.

  1. <!-- NOT ALLOWED -->
  2. <programlisting language="php"><![CDATA[
  3.  
  4. $render = "xxx";
  5.  
  6. ]]></programlisting>
  7.  
  8. <!-- OK -->
  9. <programlisting language="php"><![CDATA[
  10. $render = "xxx";
  11. ]]></programlisting>

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

  1. <!-- NOT ALLOWED -->
  2.     <programlisting language="php"><![CDATA[
  3. $render = "xxx";
  4. ]]>
  5.     </programlisting>
  6.  
  7. <!-- NOT ALLOWED -->
  8.     <programlisting language="php"><![CDATA[
  9. $render = "xxx";
  10.     ]]></programlisting>
  11.  
  12. <!-- OK -->
  13.     <programlisting language="php"><![CDATA[
  14. $render = "xxx";
  15. ]]></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".

  1. <!-- PHP -->
  2. <programlisting language="php"><![CDATA[
  3.  
  4. <!-- Javascript -->
  5. <programlisting language="javascript"><![CDATA[
  6.  
  7. <!-- XML -->
  8. <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.

  1. <!-- NOT ALLOWED -->
  2. <programlisting language="php"<![CDATA[<?php
  3.     // ...
  4. ?>]]></programlisting>
  5.  
  6. <programlisting language="php"<![CDATA[
  7. <?php
  8.     // ...
  9. ?>
  10. ]]></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.

  1. <para>
  2.     The class <classname>Zend_Class</classname>.
  3. </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.

  1. <para>
  2.     The variable <varname>$var</varname> and the class variable
  3.     <varname>Zend_Class::$var</varname>.
  4. </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.

  1. <para>
  2.     The method <methodname>foo()</methodname> and the class method
  3.     <methodname>Zend_Class::foo()</methodname>. A method with a full signature:
  4.     <methodname>foo($bar, $baz)</methodname>
  5. </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.

  1. <para>
  2.     The constant <constant>FOO</constant> and the class constant
  3.     <constant>Zend_Class::FOO</constant>.
  4. </para>

filename

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

  1. <para>
  2.     The filename <filename>application/Bootstrap.php</filename>.
  3. </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.

  1. <para>
  2.     Execute <command>zf.sh create project</command>.
  3. </para>

code

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

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

title

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

  1. <!-- NOT ALLOWED -->
  2. <title>Using <classname>Zend_Class</classname></title>
  3.  
  4. <!-- OK -->
  5. <title>Using Zend_Class</title>
概要
Zend Framework ドキュメント標準(一部日本語)
プログラマ向けリファレンスガイド
blog comments powered by Disqus

Select a Version

Languages Available

Components

Search the Manual

    • Navigation