cvs: peardoc /en/chapters pear2cs.xml

http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/pear2cs.xml?r1=1.3&r2=1.4&diff_format=u
Index: peardoc/en/chapters/pear2cs.xml
diff -u peardoc/en/chapters/pear2cs.xml:1.3 peardoc/en/chapters/pear2cs.xml:1.4
--- peardoc/en/chapters/pear2cs.xml:1.3	Mon Nov 26 22:29:17 2007
+++ peardoc/en/chapters/pear2cs.xml	Mon Nov 26 22:53:51 2007
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8" ?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
  <chapter id="pear2cs">
   <chapterinfo>
    <date>2007-11-26</date>
@@ -54,87 +54,86 @@
    <title>Introduction</title>
    <para>
     PEAR 1.x is very successful at managing the universe of PEAR-installable
-    code.
-    The new Pyrus installer is designed to expand that universe to include
-    code that
-    can also be easily embedded in non-PEAR applications and that runs
-    identically
-    when simply unzipped and when installed.  The PEAR2 repository must adhere
-    to
-    different coding conventions than the PEAR repository to make this
-    possible.
-
+    code. The new Pyrus installer is designed to expand that universe to include
+    code that can also be easily embedded in non-PEAR applications and that runs
+    identically when simply unzipped and when installed. The PEAR2 repository
+    must adhere to different coding conventions than the PEAR repository to
+    make this possible.
     This document itemizes all the changes to existing rules and coding
     standards.
    </para>
 
    <para>
-    <functionname>require_once</functionname> introduces a rigidity to package structure that limits the
-    possible uses of a PEAR package.
+    <methodname>require_once</methodname> introduces a rigidity to package
+    structure that limits the possible uses of a PEAR package.
     Some of the problems:
 
     <itemizedlist>
      <listitem>
       <simpara>
-     <functionname>require_once</functionname> 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)
+       <methodname>require_once</methodname> 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.
+      <literal>include_path</literal> is required in order to use a package.
+      This makes it difficult to bundle a PEAR package within another
+      application with its own <literal>include_path</literal>, 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 <functionname>require_once</functionname> is mixed with conditional <functionname>require_once</functionname>, this
-     can result in code that is uncacheable by opcode caches such as APC,
-     which will be bundled with PHP 6.
+       When top-level <methodname>require_once</methodname> is mixed with
+       conditional <methodname>require_once</methodname>, 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 <functionname>require_once</functionname> requires that include_path already be set up to
-     the correct value, making it impossible to use a package without proper
-     include_path
+       Relative <methodname>require_once</methodname> requires that
+       <literal>include_path</literal> already be set up to the correct value,
+       making it impossible to use a package without proper
+       <literal>include_path</literal>.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
 
    <para>
-    Some of the benefits of <functionname>require_once</functionname>:
+    Some of the benefits of <methodname>require_once</methodname>:
     <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())
+       You know right away if a file is missing, with a Fatal Error: missing
+       file X (this is mitigated by using <methodname>__autoload()</methodname>
+       with <methodname>PEAR2_Autoload()</methodname>).
       </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())
+       End-users don't need to know what files are within a package to use it
+       (also mitigated by using <methodname>__autoload()</methodname> with
+       <methodname>PEAR2_Autoload()</methodname>).
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
 
    <para>
-    The removal of <functionname>require_once</functionname> necessitates another method for loading
+    The removal of <methodname>require_once</methodname> necessitates another method for loading
     internal dependencies, both files within a package and external files.
     This proposal introduces 2 possible methods for doing this:
     <itemizedlist>
      <listitem>
       <para>
-      use __autoload() in conjunction with PEAR2's custom autoload solution
+      use <methodname>__autoload()</methodname> 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">
@@ -152,10 +151,10 @@
    <para>
     In all cases, the bonus of loading needed files is shifted to the end
     user.  However, for beginning users, the only required step is to
-    load PEAR2/Autoload.php, which will be always bundled with new packages,
+    load <filename>PEAR2/Autoload.php</filename>, which will be always bundled with new packages,
     but only extracted if used as unzip-and-go (pyrus would simply install
     the dependency on PEAR2, which would contain the needed base files
-    PEAR2_Exception and PEAR2_Autoload).
+    <classname>PEAR2_Exception</classname> and <classname>PEAR2_Autoload</classname>).
     <programlisting role="php">
      <![CDATA[
 <?php
@@ -164,8 +163,9 @@
 ?>
      ]]>
     </programlisting>
-    PEAR2/Autoload.php automatically sets up include_path if it does not
-    contain the correct value, and also automatically declares __autoload() if
+    <filename>PEAR2/Autoload.php</filename> automatically sets up include_path if it does not
+    contain the correct value, and also automatically declares
+    <methodname>__autoload()</methodname> if
     the user has not defined it.
    </para>
   </sect1>
@@ -204,10 +204,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.
+     As such, underscores are no longer required of any classes if there is a namespace.
+     Class <classname>PEAR2_HTTP_Request</classname> instead becomes
+     <classname>PEAR2::HTTP::Request</classname>.
 
-     Package names, however, will use underscores, making PEAR2_HTTP_Request the package name.
+     Package names, however, will use underscores, making
+     <classname>PEAR2_HTTP_Request</classname> the package name.
     </para>
      <sect3 id="pear2cs.rules.namespace.requirement">
       <title>Requirement</title>