Overview | Zend Framework Documentation Standard Programmer's Reference Guide | Recommendations
# Documentation File Formatting # XML Tags Each manual file must include the following XML declarations at the top of the file: <?xml version="1.0" encoding="UTF-8"?> <!-- Reviewed: no --> XML files from translated languages must also include a revision tag containing the revision of the corresponding English-language file the translation was based on. <?xml version="1.0" encoding="UTF-8"?> <!-- EN-Revision: 14978 --> <!-- Reviewed: no --> # Maximum Line Length 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. # Indentation Indentation should consist of 4 spaces. Tabs are not allowed. Tags which are at the same level must have the same indentation. <sect1> </sect1> <sect1> </sect1> Tags which are one level under the previous tag must be indented with 4 additional spaces. <sect1> <sect2> </sect2> </sect1> Multiple block tags within the same line are not allowed; multiple inline tags are allowed, however. <!-- NOT ALLOWED: --> <sect1><sect2> </sect2></sect1> <!-- ALLOWED --> <para> <classname>Zend_Magic</classname> does not exist. <classname>Zend_Acl</classname> does. </para> # Line Termination Line termination follows the Unix text file convention. Lines must end with a single linefeed (LF) character. Linefeed characters are represented as ordinal 10, or hexadecimal 0x0A. Note: Do not use carriage returns (CR) as is the convention in Apple OS's (0x0D) or the carriage return - linefeed combination (CRLF) as is standard for the Windows OS (0x0D, 0x0A). # Empty tags Empty tags are not allowed; all tags must contain text or child tags. <!-- NOT ALLOWED --> <para> Some text. <link></link> </para> <para> </para> # Usage of whitespace within documents # Whitespace within tags 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> Opening inline tags should have no whitespace immediately following them. <!-- 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> Closing inline tags must not be preceded by any whitespace. <!-- NOT ALLOWED --> This is the class <classname>Zend_Class </classname> <!-- OK --> This is the class <classname>Zend_Class</classname> # Multiple line breaks Multiple line breaks within or between tags are not allowed. <!-- 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> # Separation between tags Tags at the same level must be separated by an empty line to improve readability. <!-- NOT ALLOWED --> <para> Some text... </para> <para> More text... </para> <!-- OK --> <para> Some text... </para> <para> More text... </para> The first child tag should open directly below its parent, with no empty line between them; the last child tag should close directly before the closing tag of its parent. <!-- NOT ALLOWED --> <sect1> <sect2> </sect2> <sect2> </sect2> <sect2> </sect2> </sect1> <!-- OK --> <sect1> <sect2> </sect2> <sect2> </sect2> <sect2> </sect2> </sect1> # Program Listings 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. Note: Never use short tags Short tags (e.g., "<?", "<?=") should never be used within programlisting or the narrative of a document. # Notes on specific inline tags # 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. # Notes on specific block tags # title The <title> tag is not allowed to hold other tags. <!-- NOT ALLOWED --> <title>Using <classname>Zend_Class</classname></title> <!-- OK --> <title>Using Zend_Class</title>
Overview | Zend Framework Documentation Standard Programmer's Reference Guide | Recommendations