documentation/manual/en/ref/documentation-standard.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <appendix id="doc-standard">
   4     <title>Zend Framework Documentation Standard</title>
   5
   6     <sect1 id="doc-standard.overview">
   7         <title>Overview</title>
   8
   9         <sect2 id="doc-standard.overview.scope">
  10             <title>Scope</title>
  11
  12             <para>
  13                 This document provides guidelines for creation of the end-user
  14                 documentation found within Zend Framework. It is intended as a
  15                 guide to Zend Framework contributors, who must write
  16                 documentation as part of component contributions, as well as to
  17                 documentation translators. The standards contained herein are
  18                 intended to ease translation of documentation, minimize
  19                 visual and stylistic differences between different documentation
  20                 files, and make finding changes in documentation easier with
  21                 <command>diff</command> tools.
  22             </para>
  23
  24             <para>
  25                 You may adopt and/or modify these standards in accordance with the terms of our
  26                 <ulink url="http://framework.zend.com/license">license</ulink>.
  27             </para>
  28
  29             <para>
  30                 Topics covered in Zend Framework's documentation standards include documentation
  31                 file formatting and recommendations for documentation quality.
  32             </para>
  33         </sect2>
  34     </sect1>
  35
  36     <sect1 id="doc-standard.file-formatting">
  37         <title>Documentation File Formatting</title>
  38
  39         <sect2 id="doc-standard.file-formatting.xml-tags">
  40             <title>XML Tags</title>
  41
  42             <para>
  43                 Each manual file must include the following <acronym>XML</acronym> declarations at
  44                 the top of the file:
  45             </para>
  46
  47             <programlisting language="xml"><![CDATA[
  48 <?xml version="1.0" encoding="UTF-8"?>
  49 <!-- Reviewed: no -->
  50 ]]></programlisting>
  51
  52             <para>
  53                 <acronym>XML</acronym> files from translated languages must also include a revision
  54                 tag containing the revision of the corresponding English-language file the
  55                 translation was based on.
  56             </para>
  57
  58             <programlisting language="xml"><![CDATA[
  59 <?xml version="1.0" encoding="UTF-8"?>
  60 <!-- EN-Revision: 14978 -->
  61 <!-- Reviewed: no -->
  62 ]]></programlisting>
  63         </sect2>
  64
  65         <sect2 id="doc-standard.file-formatting.max-line-length">
  66             <title>Maximum Line Length</title>
  67
  68             <para>
  69                 The maximum line length, including tags, attributes, and indentation, is not to
  70                 exceed 100 characters. There is only one exception to this rule: attribute and value
  71                 pairs are allowed to exceed the 100 chars as they are not allowed to be separated.
  72             </para>
  73         </sect2>
  74
  75         <sect2 id="doc-standard.file-formatting.indentation">
  76             <title>Indentation</title>
  77
  78             <para>Indentation should consist of 4 spaces. Tabs are not allowed.</para>
  79             <para>Tags which are at the same level must have the same indentation.</para>
  80
  81             <programlisting language="xml"><![CDATA[
  82 <sect1>
  83 </sect1>
  84
  85 <sect1>
  86 </sect1>
  87 ]]></programlisting>
  88
  89             <para>
  90                 Tags which are one level under the previous tag must be indented with 4 additional
  91                 spaces.
  92             </para>
  93
  94             <programlisting language="xml"><![CDATA[
  95 <sect1>
  96     <sect2>
  97     </sect2>
  98 </sect1>
  99 ]]></programlisting>
 100
 101             <para>
 102                 Multiple block tags within the same line are not allowed; multiple inline tags are
 103                 allowed, however.
 104             </para>
 105
 106             <programlisting language="xml"><![CDATA[
 107 <!-- NOT ALLOWED: -->
 108 <sect1><sect2>
 109 </sect2></sect1>
 110
 111 <!-- ALLOWED -->
 112 <para>
 113     <classname>Zend_Magic</classname> does not exist. <classname>Zend_Acl</classname> does.
 114 </para>
 115 ]]></programlisting>
 116         </sect2>
 117
 118         <sect2 id="doc-standard.file-formatting.line-termination">
 119             <title>Line Termination</title>
 120
 121             <para>
 122                 Line termination follows the Unix text file convention. Lines must end with a
 123                 single linefeed (LF) character. Linefeed characters are represented as ordinal 10,
 124                 or hexadecimal 0x0A.
 125             </para>
 126
 127             <para>
 128                 Note: Do not use carriage returns (<acronym>CR</acronym>) as is the convention in
 129                 Apple OS's (0x0D) or the carriage return - linefeed combination
 130                 (<acronym>CRLF</acronym>) as is standard for the Windows OS (0x0D, 0x0A).
 131             </para>
 132         </sect2>
 133
 134         <sect2 id="doc-standard.file-formatting.empty-tags">
 135             <title>Empty tags</title>
 136
 137             <para>
 138                 Empty tags are not allowed; all tags must contain text or child tags.
 139             </para>
 140
 141             <programlisting language="xml"><![CDATA[
 142 <!-- NOT ALLOWED -->
 143 <para>
 144     Some text. <link></link>
 145 </para>
 146
 147 <para>
 148 </para>
 149 ]]></programlisting>
 150         </sect2>
 151
 152         <sect2 id="doc-standard.file-formatting.whitespace">
 153             <title>Usage of whitespace within documents</title>
 154
 155             <sect3 id="doc-standard.file-formatting.whitespace.trailing">
 156                 <title>Whitespace within tags</title>
 157
 158                 <para>
 159                     Opening block tags should have no whitespace immediately following them other
 160                     than line breaks (and indentation on the following line).
 161                 </para>
 162
 163                 <programlisting language="xml"><![CDATA[
 164 <!-- NOT ALLOWED -->
 165 <sect1>WHITESPACE
 166 </sect1>
 167 ]]></programlisting>
 168
 169                 <para>
 170                     Opening inline tags should have no whitespace immediately following them.
 171                 </para>
 172
 173                 <programlisting language="xml"><![CDATA[
 174 <!-- NOT ALLOWED -->
 175 This is the class <classname> Zend_Class</classname>.
 176
 177 <!-- OK -->
 178 This is the class <classname>Zend_Class</classname>.
 179 ]]></programlisting>
 180
 181                 <para>
 182                     Closing block tags may be preceded by whitespace equivalent to the current
 183                     indentation level, but no more than that amount.
 184                 </para>
 185
 186                 <programlisting language="xml"><![CDATA[
 187 <!-- NOT ALLOWED -->
 188     <sect1>
 189      </sect1>
 190
 191 <!-- OK -->
 192     <sect1>
 193     </sect1>
 194 ]]></programlisting>
 195
 196                 <para>
 197                     Closing inline tags must not be preceded by any whitespace.
 198                 </para>
 199
 200                 <programlisting language="xml"><![CDATA[
 201 <!-- NOT ALLOWED -->
 202 This is the class <classname>Zend_Class </classname>
 203
 204 <!-- OK -->
 205 This is the class <classname>Zend_Class</classname>
 206 ]]></programlisting>
 207             </sect3>
 208
 209             <sect3 id="doc-standard.file-formatting.whitespace.multiple-line-breaks">
 210                 <title>Multiple line breaks</title>
 211
 212                 <para>
 213                     Multiple line breaks within or between tags are not allowed.
 214                 </para>
 215
 216                 <programlisting language="xml"><![CDATA[
 217 <!-- NOT ALLOWED -->
 218 <para>
 219     Some text...
 220
 221     ... and more text
 222 </para>
 223
 224
 225 <para>
 226     Another paragraph.
 227 </para>
 228
 229 <!-- OK -->
 230 <para>
 231     Some text...
 232     ... and more text
 233 </para>
 234
 235 <para>
 236     Another paragraph.
 237 </para>
 238 ]]></programlisting>
 239             </sect3>
 240
 241             <sect3 id="doc-standard.file-formatting.whitespace.tag-separation">
 242                 <title>Separation between tags</title>
 243
 244                 <para>
 245                     Tags at the same level must be separated by an empty line to improve
 246                     readability.
 247                 </para>
 248
 249                 <programlisting language="xml"><![CDATA[
 250 <!-- NOT ALLOWED -->
 251 <para>
 252     Some text...
 253 </para>
 254 <para>
 255     More text...
 256 </para>
 257
 258 <!-- OK -->
 259 <para>
 260     Some text...
 261 </para>
 262
 263 <para>
 264     More text...
 265 </para>
 266 ]]></programlisting>
 267
 268                 <para>
 269                     The first child tag should open directly below its parent, with no empty line
 270                     between them; the last child tag should close directly before the closing tag of
 271                     its parent.
 272                 </para>
 273
 274                 <programlisting language="xml"><![CDATA[
 275 <!-- NOT ALLOWED -->
 276 <sect1>
 277
 278     <sect2>
 279     </sect2>
 280
 281     <sect2>
 282     </sect2>
 283
 284     <sect2>
 285     </sect2>
 286
 287 </sect1>
 288
 289 <!-- OK -->
 290 <sect1>
 291     <sect2>
 292     </sect2>
 293
 294     <sect2>
 295     </sect2>
 296
 297     <sect2>
 298     </sect2>
 299 </sect1>
 300 ]]></programlisting>
 301             </sect3>
 302         </sect2>
 303
 304         <sect2 id="doc-standard.file-formatting.program-listing">
 305             <title>Program Listings</title>
 306
 307             <para>
 308                 The opening <emphasis>&lt;programlisting&gt;</emphasis> tag must indicate the
 309                 appropriate "language" attribute and be indented at the same level as its sibling
 310                 blocks.
 311             </para>
 312
 313             <programlisting language="xml"><![CDATA[
 314 <para>Sibling paragraph.</para>
 315
 316 <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
 317 ]]></programlisting>
 318
 319             <para>
 320                 <acronym>CDATA</acronym> should be used around all program listings.
 321             </para>
 322
 323             <para>
 324                 <emphasis>&lt;programlisting&gt;</emphasis> sections must not add linebreaks or
 325                 whitespace at the beginning or end of the section, as these are then represented in
 326                 the final output.
 327             </para>
 328
 329             <programlisting language="xml"><![CDATA[
 330 <!-- NOT ALLOWED -->
 331 <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
 332
 333 $render = "xxx";
 334
 335 ]]]]>&gt;<![CDATA[</programlisting>
 336
 337 <!-- OK -->
 338 <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
 339 $render = "xxx";
 340 ]]]]>&gt;<![CDATA[</programlisting>
 341 ]]></programlisting>
 342
 343             <para>
 344                 Ending <acronym>CDATA</acronym> and <emphasis>&lt;programlisting&gt;</emphasis>
 345                 tags should be on the same line, without any indentation.
 346             </para>
 347
 348             <programlisting language="xml"><![CDATA[
 349 <!-- NOT ALLOWED -->
 350     <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
 351 $render = "xxx";
 352 ]]]]>&gt;<![CDATA[
 353     </programlisting>
 354
 355 <!-- NOT ALLOWED -->
 356     <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
 357 $render = "xxx";
 358     ]]]]>&gt;<![CDATA[</programlisting>
 359
 360 <!-- OK -->
 361     <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
 362 $render = "xxx";
 363 ]]]]>&gt;<![CDATA[</programlisting>
 364 ]]></programlisting>
 365
 366             <para>
 367                 The <emphasis>&lt;programlisting&gt;</emphasis> tag should contain the "language"
 368                 attribute with a value appropriate to the contents of the program listing. Typical
 369                 values include "css", "html", "ini", "javascript", "php", "text", and "xml".
 370             </para>
 371
 372             <programlisting language="xml"><![CDATA[
 373 <!-- PHP -->
 374 <programlisting language="php">]]>&lt;<![CDATA[![CDATA[
 375
 376 <!-- Javascript -->
 377 <programlisting language="javascript">]]>&lt;<![CDATA[![CDATA[
 378
 379 <!-- XML -->
 380 <programlisting language="xml">]]>&lt;<![CDATA[![CDATA[
 381 ]]></programlisting>
 382
 383             <para>
 384                 For program listings containing only <acronym>PHP</acronym> code,
 385                 <acronym>PHP</acronym> tags (e.g., "&lt;?php", "?&gt;") are not required, and
 386                 should not be used. They simply clutter the narrative, and are implied by the use
 387                 of the <emphasis>&lt;programlisting&gt;</emphasis> tag.
 388             </para>
 389
 390             <programlisting language="xml"><![CDATA[
 391 <!-- NOT ALLOWED -->
 392 <programlisting language="php"]]>&lt;<![CDATA[![CDATA[<?php
 393     // ...
 394 ?>]]]]>&gt;<![CDATA[</programlisting>
 395
 396 <programlisting language="php"]]>&lt;<![CDATA[![CDATA[
 397 <?php
 398     // ...
 399 ?>
 400 ]]]]>&gt;<![CDATA[</programlisting>
 401 ]]></programlisting>
 402
 403             <para>
 404                 Line lengths within program listings should follow the <link
 405                     linkend="coding-standard.php-file-formatting.max-line-length">coding standards
 406                 recommendations</link>.
 407             </para>
 408
 409             <para>
 410                 Refrain from using <methodname>require_once()</methodname>,
 411                 <methodname>require()</methodname>, <methodname>include_once()</methodname>, and
 412                 <methodname>include()</methodname> calls within <acronym>PHP</acronym> listings.
 413                 They simply clutter the narrative, and are largely obviated when using an
 414                 autoloader. Use them only when they are essential to the example.
 415             </para>
 416
 417             <note>
 418                 <title>Never use short tags</title>
 419
 420                 <para>
 421                     Short tags (e.g., "&lt;?", "&lt;?=") should never be used within
 422                     <emphasis>programlisting</emphasis> or the narrative of a document.
 423                 </para>
 424             </note>
 425         </sect2>
 426
 427         <sect2 id="doc-standard.file-formatting.inline-tags">
 428             <title>Notes on specific inline tags</title>
 429
 430             <sect3 id="doc-standard.file-formatting.inline-tags.classname">
 431                 <title>classname</title>
 432
 433                 <para>
 434                     The tag <emphasis>&lt;classname&gt;</emphasis> must be used each time a class
 435                     name is represented by itself; it should not be used when combined with a
 436                     method name, variable name, or constant, and no other content is allowed within
 437                     the tag.
 438                 </para>
 439
 440                 <programlisting language="xml"><![CDATA[
 441 <para>
 442     The class <classname>Zend_Class</classname>.
 443 </para>
 444 ]]></programlisting>
 445             </sect3>
 446
 447             <sect3 id="doc-standard.file-formatting.inline-tags.varname">
 448                 <title>varname</title>
 449
 450                 <para>
 451                     Variables must be wrapped in the <emphasis>&lt;varname&gt;</emphasis> tag.
 452                     Variables must be written using the "$" sigil. No other content is allowed
 453                     within this tag, unless a class name is used, which indicates a class variable.
 454                 </para>
 455
 456                 <programlisting language="xml"><![CDATA[
 457 <para>
 458     The variable <varname>$var</varname> and the class variable
 459     <varname>Zend_Class::$var</varname>.
 460 </para>
 461 ]]></programlisting>
 462             </sect3>
 463
 464             <sect3 id="doc-standard.file-formatting.inline-tags.methodname">
 465                 <title>methodname</title>
 466
 467                 <para>
 468                     Methods must be wrapped in the <emphasis>&lt;methodname&gt;</emphasis> tag.
 469                     Methods must either include the full method signature or at the least a pair of
 470                     closing parentheses (e.g., "()"). No other content is allowed within this tag,
 471                     unless a class name is used, which indicates a class method.
 472                 </para>
 473
 474                 <programlisting language="xml"><![CDATA[
 475 <para>
 476     The method <methodname>foo()</methodname> and the class method
 477     <methodname>Zend_Class::foo()</methodname>. A method with a full signature:
 478     <methodname>foo($bar, $baz)</methodname>
 479 </para>
 480 ]]></programlisting>
 481             </sect3>
 482
 483             <sect3 id="doc-standard.file-formatting.inline-tags.constant">
 484                 <title>constant</title>
 485
 486                 <para>
 487                     Use the <emphasis>&lt;constant&gt;</emphasis> tag when denoting constants.
 488                     Constants must be written in <acronym>UPPERCASE</acronym>. No other content is
 489                     allowed within this tag, unless a class name is used, which indicates a class
 490                     constant.
 491                 </para>
 492
 493                 <programlisting language="xml"><![CDATA[
 494 <para>
 495     The constant <constant>FOO</constant> and the class constant
 496     <constant>Zend_Class::FOO</constant>.
 497 </para>
 498 ]]></programlisting>
 499             </sect3>
 500
 501             <sect3 id="doc-standard.file-formatting.inline-tags.filename">
 502                 <title>filename</title>
 503
 504                 <para>
 505                     Filenames and paths must be wrapped in the
 506                     <emphasis>&lt;filename&gt;</emphasis> tag. No other content is allowed in this
 507                     tag.
 508                 </para>
 509
 510                 <programlisting language="xml"><![CDATA[
 511 <para>
 512     The filename <filename>application/Bootstrap.php</filename>.
 513 </para>
 514 ]]></programlisting>
 515             </sect3>
 516
 517             <sect3 id="doc-standard.file-formatting.inline-tags.command">
 518                 <title>command</title>
 519
 520                 <para>
 521                     Commands, shell scripts, and program calls must be wrapped in the
 522                     <emphasis>&lt;command&gt;</emphasis> tag. If the command includes arguments,
 523                     these should also be included within the tag.
 524                 </para>
 525
 526                 <programlisting language="xml"><![CDATA[
 527 <para>
 528     Execute <command>zf.sh create project</command>.
 529 </para>
 530 ]]></programlisting>
 531             </sect3>
 532
 533             <sect3 id="doc-standard.file-formatting.inline-tags.code">
 534                 <title>code</title>
 535
 536                 <para>
 537                     Usage of the <emphasis>&lt;code&gt;</emphasis> tag is discouraged, in favor of
 538                     the other inline tasks discussed previously.
 539                 </para>
 540             </sect3>
 541         </sect2>
 542
 543         <sect2 id="doc-standard.file-formatting.block-tags">
 544             <title>Notes on specific block tags</title>
 545
 546             <sect3 id="doc-standard.file-formatting.block-tags.title">
 547                 <title>title</title>
 548
 549                 <para>
 550                     The <emphasis>&lt;title&gt;</emphasis> tag is not allowed to hold other tags.
 551                 </para>
 552
 553                 <programlisting language="xml"><![CDATA[
 554 <!-- NOT ALLOWED -->
 555 <title>Using <classname>Zend_Class</classname></title>
 556
 557 <!-- OK -->
 558 <title>Using Zend_Class</title>
 559 ]]></programlisting>
 560             </sect3>
 561         </sect2>
 562     </sect1>
 563
 564     <sect1 id="doc-standard.recommendations">
 565         <title>Recommendations</title>
 566
 567         <sect2 id="doc-standard.recommendations.editors">
 568             <title>Use editors without autoformatting</title>
 569
 570             <para>
 571                 For editing the documentation, typically you should not use formal
 572                 <acronym>XML</acronym> editors. Such editors normally autoformat existing documents
 573                 to fit their own standards and/or do not strictly follow the docbook standard. As
 574                 examples, we have seen them erase the <acronym>CDATA</acronym> tags, change 4 space
 575                 separation to tabs or 2 spaces, etc.
 576             </para>
 577
 578             <para>
 579                 The style guidelines were written in large part to assist translators in recognizing
 580                 the lines that have changed using normal <command>diff</command> tools.
 581                 Autoformatting makes this process more difficult.
 582             </para>
 583         </sect2>
 584
 585         <sect2 id="doc-standard.recommendations.images">
 586             <title>Use Images</title>
 587
 588             <para>
 589                 Good images and diagrams can improve readability and comprehension. Use them
 590                 whenever they will assist in these goals. Images should be placed in the
 591                 <filename>documentation/manual/en/figures/</filename> directory, and be named after
 592                 the section identifier in which they occur.
 593             </para>
 594         </sect2>
 595
 596         <sect2 id="doc-standard.recommendations.examples">
 597             <title>Use Case Examples</title>
 598
 599             <para>
 600                 Look for good use cases submitted by the community, especially those posted in
 601                 proposal comments or on one of the mailing lists. Examples often illustrate usage
 602                 far better than the narrative does.
 603             </para>
 604
 605             <para>
 606                 When writing your examples for inclusion in the manual, follow
 607                 all coding standards and documentation standards.
 608             </para>
 609         </sect2>
 610
 611         <sect2 id="doc-standard.recommendations.phpdoc">
 612             <title>Avoid Replicating phpdoc Contents</title>
 613
 614             <para>
 615                 The manual is intended to be a reference guide for end-user usage. Replicating
 616                 the phpdoc documentation for internal-use components and classes is not wanted, and
 617                 the narrative should be focussed on usage, not the internal workings. In any case,
 618                 at this time, we would like the documentation teams to focus on translating the
 619                 English manual, not the phpdoc comments.
 620             </para>
 621         </sect2>
 622
 623         <sect2 id="doc-standard.recommendations.links">
 624             <title>Use Links</title>
 625
 626             <para>
 627                 Link to other sections of the manual or to external sources
 628                 instead of recreating documentation.
 629             </para>
 630
 631             <para>
 632                 Linking to other sections of the manual may be done using either the
 633                 <emphasis>&lt;xref&gt;</emphasis> tag (which will substitute the section title for
 634                 the link text) or the <emphasis>&lt;link&gt;</emphasis> tag (to which you must
 635                 provide link text).
 636             </para>
 637
 638             <programlisting language="xml"><![CDATA[
 639 <para>
 640     "Xref" links to a section: <xref
 641         linkend="doc-standard.recommendations.links" />.
 642 </para>
 643
 644 <para>
 645     "Link" links to a section, using descriptive text: <link
 646         linkend="doc-standard.recommendations.links">documentation on
 647         links</link>.
 648 </para>
 649 ]]></programlisting>
 650
 651             <para>
 652                 To link to an external resource, use <emphasis>&lt;ulink&gt;</emphasis>:
 653             </para>
 654
 655             <programlisting language="xml"><![CDATA[
 656 <para>
 657     The <ulink url="http://framework.zend.com/">Zend Framework site</ulink>.
 658 </para>
 659 ]]></programlisting>
 660         </sect2>
 661     </sect1>
 662 </appendix>