Documentation File Formatting

XML Tags

Each manual file must include the following XML declarations at
the top of the file:

<?xmlversion="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.

<?xmlversion="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>

<programlistinglanguage="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 -->

<programlistinglanguage="php"><![CDATA[

$render = "xxx";

]]></programlisting>

<!-- OK -->

<programlistinglanguage="php"><![CDATA[

$render = "xxx";

]]></programlisting>

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

<!-- NOT ALLOWED -->

<programlistinglanguage="php"><![CDATA[

$render = "xxx";

]]>

</programlisting>

<!-- NOT ALLOWED -->

<programlistinglanguage="php"><![CDATA[

$render = "xxx";

]]></programlisting>

<!-- OK -->

<programlistinglanguage="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 -->

<programlistinglanguage="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.

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.