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:

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

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

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

Tags which are one level under the previous tag must be indented with 4 additional spaces.

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

Multiple block tags within the same line are not allowed; multiple inline tags are allowed, however.

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

1. <!-- NOT ALLOWED -->
2. <para>
3. Some text. <link></link>
4. </para>
6. <para>
7. </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).

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

Opening inline tags should have no whitespace immediately following them.

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

Closing inline tags must not be preceded by any whitespace.

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

# Multiple line breaks

Multiple line breaks within or between tags are not allowed.

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

# Separation between tags

Tags at the same level must be separated by an empty line to improve readability.

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

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

# Program Listings

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>
3. <programlisting language="php"><![CDATA[
4. </span</div>

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[
4. $render = "xxx";
6. ]]></programlisting>
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>
7. <!-- NOT ALLOWED -->
8. <programlisting language="php"><![CDATA[
9. $render = "xxx";
10. ]]></programlisting>
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[
4. <!-- Javascript -->
5. <programlisting language="javascript"><![CDATA[
7. <!-- XML -->
8. <programlisting language="xml"><![CDATA[
9. </span</div>

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

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

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.

# Notes on specific block tags

# title

The <title> tag is not allowed to hold other tags.

1. <!-- NOT ALLOWED -->
2. <title>Using <classname>Zend_Class</classname></title>
4. <!-- OK -->
5. <title>Using Zend_Class</title>

Overview | Zend Framework Documentation Standard Programmer's Reference Guide | Recommendations