From 06f945f27840b53e57795dadbc38e76f7e11ab1c Mon Sep 17 00:00:00 2001 From: Horus3 Date: Mon, 24 Feb 2014 16:42:14 +0100 Subject: init --- .../core/en/doc-standard.file-formatting.html | 599 +++++++++++++++++++++ 1 file changed, 599 insertions(+) create mode 100644 zend/documentation/manual/core/en/doc-standard.file-formatting.html (limited to 'zend/documentation/manual/core/en/doc-standard.file-formatting.html') diff --git a/zend/documentation/manual/core/en/doc-standard.file-formatting.html b/zend/documentation/manual/core/en/doc-standard.file-formatting.html new file mode 100644 index 0000000..b395748 --- /dev/null +++ b/zend/documentation/manual/core/en/doc-standard.file-formatting.html @@ -0,0 +1,599 @@ + + + + + Documentation File Formatting - Zend Framework Manual + + + + + + + + +
+ + + + + + + + +
+ Overview + +
Zend Framework Documentation Standard
+ Programmer's Reference Guide
+ 		+ +
+
+

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. +
  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. +
  2. <!-- EN-Revision: 14978 -->
    3. +
  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. +
  2. </sect1>
    3. +
  3.  
    4. +
  4. <sect1>
    5. +
  5. </sect1>
+ + +

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

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

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

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

+ Opening inline tags should have no whitespace immediately following them. +

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

+ Closing inline tags must not be preceded by any whitespace. +

+ +
  1. <!-- NOT ALLOWED -->
    2. +
  2. This is the class <classname>Zend_Class </classname>
    3. +
  3.  
    4. +
  4. <!-- OK -->
    5. +
  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. +
  2. <para>
    3. +
  3.     Some text...
    4. +
  4.  
    5. +
  5.     ... and more text
    6. +
  6. </para>
    7. +
  7.  
    8. +
  8.  
    9. +
  9. <para>
    10. +
  10.     Another paragraph.
    11. +
  11. </para>
    12. +
  12.  
    13. +
  13. <!-- OK -->
    14. +
  14. <para>
    15. +
  15.     Some text...
    16. +
  16.     ... and more text
    17. +
  17. </para>
    18. +
  18.  
    19. +
  19. <para>
    20. +
  20.     Another paragraph.
    21. +
  21. </para>
+ +
+ +

Separation between tags

+ + +

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

+ +
  1. <!-- NOT ALLOWED -->
    2. +
  2. <para>
    3. +
  3.     Some text...
    4. +
  4. </para>
    5. +
  5. <para>
    6. +
  6.     More text...
    7. +
  7. </para>
    8. +
  8.  
    9. +
  9. <!-- OK -->
    10. +
  10. <para>
    11. +
  11.     Some text...
    12. +
  12. </para>
    13. +
  13.  
    14. +
  14. <para>
    15. +
  15.     More text...
    16. +
  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. +
  2. <sect1>
    3. +
  3.  
    4. +
  4.     <sect2>
    5. +
  5.     </sect2>
    6. +
  6.  
    7. +
  7.     <sect2>
    8. +
  8.     </sect2>
    9. +
  9.  
    10. +
  10.     <sect2>
    11. +
  11.     </sect2>
    12. +
  12.  
    13. +
  13. </sect1>
    14. +
  14.  
    15. +
  15. <!-- OK -->
    16. +
  16. <sect1>
    17. +
  17.     <sect2>
    18. +
  18.     </sect2>
    19. +
  19.  
    20. +
  20.     <sect2>
    21. +
  21.     </sect2>
    22. +
  22.  
    23. +
  23.     <sect2>
    24. +
  24.     </sect2>
    25. +
  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>
    2. +
  2.  
    3. +
  3. <programlisting language="php"><![CDATA[
    4. +
+ + +

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

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

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

+ 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. +
  2. <programlisting language="php"<![CDATA[<?php
    3. +
  3.     // ...
    4. +
  4. ?>]]></programlisting>
    5. +
  5.  
    6. +
  6. <programlisting language="php"<![CDATA[
    7. +
  7. <?php
    8. +
  8.     // ...
    9. +
  9. ?>
    10. +
  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. +
  2.     The class <classname>Zend_Class</classname>.
    3. +
  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. +
  2.     The variable <varname>$var</varname> and the class variable
    3. +
  3.     <varname>Zend_Class::$var</varname>.
    4. +
  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. +
  2.     The method <methodname>foo()</methodname> and the class method
    3. +
  3.     <methodname>Zend_Class::foo()</methodname>. A method with a full signature:
    4. +
  4.     <methodname>foo($bar, $baz)</methodname>
    5. +
  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. +
  2.     The constant <constant>FOO</constant> and the class constant
    3. +
  3.     <constant>Zend_Class::FOO</constant>.
    4. +
  4. </para>
+ +
+ +

filename

+ + +

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

+ +
  1. <para>
    2. +
  2.     The filename <filename>application/Bootstrap.php</filename>.
    3. +
  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. +
  2.     Execute <command>zf.sh create project</command>.
    3. +
  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. +
  2. <title>Using <classname>Zend_Class</classname></title>
    3. +
  3.  
    4. +
  4. <!-- OK -->
    5. +
  5. <title>Using Zend_Class</title>
+ +
+
+
+
+ + + + + + + + + +
+ Overview + +
Zend Framework Documentation Standard
+ Programmer's Reference Guide
+ 		+ +
+		 + +
+ + \ No newline at end of file -- cgit v1.2.3