cvs: peardoc / manual.xml.in /en/chapters pear2cs.xml

cweiske		Mon Nov 26 22:19:08 2007 UTC

  Modified files:              
    /peardoc	manual.xml.in 
    /peardoc/en/chapters	pear2cs.xml 
  Log:
  Fixed pear2 coding standards
  added pear2cs to manual
  
  
http://cvs.php.net/viewvc.cgi/peardoc/manual.xml.in?r1=1.47&r2=1.48&diff_format=u
Index: peardoc/manual.xml.in
diff -u peardoc/manual.xml.in:1.47 peardoc/manual.xml.in:1.48
--- peardoc/manual.xml.in:1.47	Wed Mar 14 23:52:19 2007
+++ peardoc/manual.xml.in	Mon Nov 26 22:19:07 2007
@@ -36,6 +36,7 @@
    &chapters.installation;
    &chapters.support;
    &chapters.standards;
+   &chapters.pear2cs;
    &chapters.contributing;
    &chapters.faq;
    &chapters.constitution;
http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/pear2cs.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/chapters/pear2cs.xml
diff -u peardoc/en/chapters/pear2cs.xml:1.1 peardoc/en/chapters/pear2cs.xml:1.2
--- peardoc/en/chapters/pear2cs.xml:1.1	Mon Nov 26 22:07:23 2007
+++ peardoc/en/chapters/pear2cs.xml	Mon Nov 26 22:19:07 2007
@@ -1,41 +1,53 @@
 <?xml version="1.0" encoding="utf-8" ?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
  <chapter id="pear2cs">
   <chapterinfo>
    <date>2007-11-26</date>
   </chapterinfo>
   <title>PEAR2 Coding Standards</title>
   <subtitle>Coding Standards to be used in PEAR2</subtitle>
-  <simpara>
+  <para>
    <itemizedlist>
     <listitem>
+     <simpara>
      This document describes the coding standards and coding conventions for the
      new PEAR2 repository.
+     </simpara>
     </listitem>
     <listitem>
+     <simpara>
      These coding standards will expire on March 1, 2008, and must be reviewed
      and renewed by the PEAR Group in
      order to continue
+     </simpara>
     </listitem>
     <listitem>
+     <simpara>
      Packages that wish to be accepted into the PEAR2 repository must conform to
      these standards
+     </simpara>
     </listitem>
     <listitem>
+     <simpara>
      The minimum PHP version supported will be the earliest version that
      supports namespaces,
      most likely PHP version 5.3.0.  This RFC will be updated as soon as the
      exact version is
      known.
+     </simpara>
     </listitem>
     <listitem>
+     <simpara>
      No Exceptions to this rule
+     </simpara>
     </listitem>
     <listitem>
+     <simpara>
      package.xml 2.0 or newer is required for all packages
+     </simpara>
     </listitem>
    </itemizedlist>
-  </simpara>
+  </para>
 
 
   <sect1 id="pear2cs.introduction">
@@ -63,28 +75,36 @@
 
     <itemizedlist>
      <listitem>
+      <simpara>
      require_once can introduce up to a 10% performance penalty on
      high-volume sites using multi-processor web servers due to increased
      latency.  However, most users would experience at most 2% performance
      penalty on single-processor systems (as measured by Yahoo! engineer
      Gopal Vijayaraghavan)
+      </simpara>
      </listitem>
      <listitem>
+      <simpara>
      include_path is required in order to use a package.  This makes it
      difficult to bundle a PEAR package within another application with its
      own include_path, to create a single file containing needed classes, to
      move a PEAR package to a phar archive without extensive source code
      modification.
+      </simpara>
      </listitem>
      <listitem>
+      <simpara>
      when top-level require_once is mixed with conditional require_once, this
      can result in code that is uncacheable by opcode caches such as APC,
      which will be bundled with PHP 6.
+      </simpara>
      </listitem>
      <listitem>
+      <simpara>
      relative require_once requires that include_path already be set up to
      the correct value, making it impossible to use a package without proper
      include_path
+      </simpara>
      </listitem>
     </itemizedlist>
    </para>
@@ -93,12 +113,16 @@
     Some of the benefits of require_once:
     <itemizedlist>
      <listitem>
+      <simpara>
       you know right away if a file is missing, with a Fatal Error: missing
       file X (this is mitigated by using __autoload() with PEAR2_Autoload())
+      </simpara>
      </listitem>
      <listitem>
+      <simpara>
       end-users don't need to know what files are within a package to use it.
       (also mitigated by using __autoload() with PEAR2_Autoload())
+      </simpara>
      </listitem>
     </itemizedlist>
    </para>
@@ -109,14 +133,18 @@
     This proposal introduces 2 possible methods for doing this:
     <itemizedlist>
      <listitem>
+      <para>
       use __autoload() in conjunction with PEAR2's custom autoload solution
       (found
       <ulink
        url="http://svn.pear.php.net/wsvn/PEARSVN/Autoload/trunk/src/Autoload.php?op=file">
        here</ulink> in svn)
+      </para>
      </listitem>
      <listitem>
+      <simpara>
       construct a customized solution for loading needed files
+      </simpara>
      </listitem>
     </itemizedlist>
    </para>
@@ -143,14 +171,17 @@
   </sect1>
 
   <sect1 id="pear2cs.rules">
+   <title>Rules</title>
    <para>
     We will describe the list of rules that form the standards
    </para>
 
    <sect2 id="pear2cs.rules.namespace">
     <title>Namespace prefix</title>
-     All classes and functions must have a namespace of at the minimum PEAR2.  An example:
 
+    <para>
+     All classes and functions must have a namespace of at the minimum PEAR2.  An example:
+    </para>
      <programlisting role="php">
      <![CDATA[
        <?php
@@ -159,9 +190,11 @@
        ?>
      ]]>
      </programlisting>
-
-     Classes may use longer namespaces, for instance an HTTP_Request class may instead choose to use this declarative syntax:
-
+    <para>
+     Classes may use longer namespaces, for instance an
+     <classname>HTTP_Request</classname> class may instead
+     choose to use this declarative syntax:
+    </para>
      <programlisting role="php">
      <![CDATA[
        <?php
@@ -170,12 +203,12 @@
        ?>
      ]]>
      </programlisting>
-
+    <para>
      As such, underscores are no longer required of any classes if there is a namespace.  Class PEAR2_HTTP_Request
      instead becomes PEAR2::HTTP::Request.
 
      Package names, however, will use underscores, making PEAR2_HTTP_Request the package name.
-
+    </para>
      <sect3 id="pear2cs.rules.namespace.requirement">
       <title>Requirement</title>
       <simpara>No Exceptions to this rule</simpara>