[DOCUMENTATION] English: manual fixes

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@19782 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/tutorials/autoloading-design.xml

@@ -7,29 +7,31 @@
         <title>Class Naming Conventions</title>
 
         <para>
-            To understand autoloading in Zend Framework, first you need to understand the relationship
-            between class names and class files.
+            To understand autoloading in Zend Framework, first you need to understand the
+            relationship between class names and class files.
         </para>
 
         <para>
             Zend Framework has borrowed an idea from <ulink url="http://pear.php.net/">PEAR</ulink>,
-            whereby class names have a 1:1 relationship with the filesystem. Simply put, the underscore
-            character ("_") is replaced by a directory separator in order to resolve the path to the
-            file, and then the suffix ".php" is added. For example, the class "Foo_Bar_Baz" would
-            correspond to "Foo/Bar/Baz.php" on the filesystem. The assumption is also that the classes
-            may be resolved via PHP's <constant>include_path</constant> setting, which allows both
-            <methodname>include</methodname> and <methodname>require</methodname> to find the filename
-            via a relative path lookup on the <constant>include_path</constant>.
+            whereby class names have a 1:1 relationship with the filesystem. Simply put, the
+            underscore character ("_") is replaced by a directory separator in order to resolve
+            the path to the file, and then the suffix "<filename>.php</filename>" is added. For
+            example, the class "<classname>Foo_Bar_Baz</classname>" would correspond to
+            "<filename>Foo/Bar/Baz.php</filename>" on the filesystem. The assumption is also
+            that the classes may be resolved via <acronym>PHP</acronym>'s
+            <property>include_path</property> setting, which allows both
+            <methodname>include()</methodname> and <methodname>require()</methodname> to find
+            the filename via a relative path lookup on the <property>include_path</property>.
         </para>
 
         <para>
-            Additionally, per PEAR as well as the <ulink
+            Additionally, per <acronym>PEAR</acronym> as well as the <ulink
                 url="http://php.net/userlandnaming.tips">PHP project</ulink>, we use and recommend
             using a vendor or project prefix for your code. What this means is that all classes you
             write will share a common class prefix; for example, all code in Zend Framework has the
             prefix "Zend_". This naming convention helps prevent naming collisions. Within Zend
             Framework, we often refer to this as the "namespace" prefix; be careful not to confuse
-            it with PHP's native namespace implementation.
+            it with <acronym>PHP</acronym>'s native namespace implementation.
         </para>
 
         <para>
@@ -43,57 +45,59 @@
 
         <para>
             Zend Framework's autoloading support, provided primarily via
-            <classname>Zend_Loader_Autoloader</classname>, has the following goals and design elements:
+            <classname>Zend_Loader_Autoloader</classname>, has the following goals and design
+            elements:
         </para>
 
         <itemizedlist>
             <listitem>
                 <para>
-                    <emphasis role="strong">Provide namespace matching.</emphasis> If the class
+                    <emphasis>Provide namespace matching</emphasis>. If the class
                     namespace prefix is not in a list of registered namespaces, return false
-                    immediately. This allows for more optimistic matching, as well as fallback to other
-                    autoloaders.
+                    immediately. This allows for more optimistic matching, as well as fallback to
+                    other autoloaders.
                 </para>
             </listitem>
 
             <listitem>
                 <para>
-                    <emphasis role="strong">Allow the autoloader to act as a fallback
-                        autoloader.</emphasis> In the case where a team may be widely distributed, or
-                    using an undetermined set of namespace prefixes, the autoloader should still be
-                    configurable such that it will attempt to match any namespace prefix. It will be
-                    noted, however, that this practice is not recommended, as it can lead to unnecessary
-                    lookups.
+                    <emphasis>Allow the autoloader to act as a fallback autoloader</emphasis>.
+                    In the case where a team may be widely distributed, or using an undetermined
+                    set of namespace prefixes, the autoloader should still be configurable such
+                    that it will attempt to match any namespace prefix. It will be noted,
+                    however, that this practice is not recommended, as it can lead to
+                    unnecessary lookups.
                 </para>
             </listitem>
 
             <listitem>
                 <para>
-                    <emphasis role="strong">Allow toggling error suppression.</emphasis> We feel -- and
-                    the greater PHP community does as well -- that error suppression is a bad idea. It's
-                    expensive, and it masks very real application problems. So, by default, it should be
-                    off. However, if a developer <emphasis>insists</emphasis> that it be on, we allow
-                    toggling it on.
+                    <emphasis>Allow toggling error suppression</emphasis>. We feel -- and the
+                    greater <acronym>PHP</acronym> community does as well -- that error suppression
+                    is a bad idea. It's expensive, and it masks very real application problems.
+                    So, by default, it should be off. However, if a developer
+                    <emphasis>insists</emphasis> that it be on, we allow toggling it on.
                 </para>
             </listitem>
 
             <listitem>
                 <para>
-                    <emphasis role="strong">Allow specifying custom callbacks for
-                        autoloading.</emphasis> Some developers don't want to use
-                    <methodname>Zend_Loader::loadClass()</methodname> for autoloading, but still want to
-                    make use of ZF's mechanisms. <classname>Zend_Loader_Autoloader</classname> allows
-                    specyfing an alternate callback for autoloading.
+                    <emphasis>Allow specifying custom callbacks for autoloading</emphasis>.
+                    Some developers don't want to use
+                    <methodname>Zend_Loader::loadClass()</methodname> for autoloading, but still
+                    want to make use of Zend Framework's mechanisms.
+                    <classname>Zend_Loader_Autoloader</classname> allows specyfing an alternate
+                    callback for autoloading.
                 </para>
             </listitem>
 
             <listitem>
                 <para>
-                    <emphasis role="strong">Allow manipulation of the SPL autoload callback
-                        chain.</emphasis> The purpose of this is to allow specifying additional
-                    autoloaders -- for instance, resource loaders for classes that don't have a 1:1
-                    mapping to the filesystem -- to be registered before or after the primary ZF
-                    autoloader.
+                    <emphasis>Allow manipulation of the <acronym>SPL</acronym> autoload
+                    callback chain</emphasis>. The purpose of this is to allow specifying
+                    additional autoloaders -- for instance, resource loaders for classes
+                    that don't have a 1:1 mapping to the filesystem -- to be registered before
+                    or after the primary Zend Framework autoloader.
                 </para>
             </listitem>
         </itemizedlist>

documentation/manual/en/tutorials/autoloading-intro.xml

@@ -5,9 +5,9 @@
 
     <para>
         Autoloading is a mechanism that eliminates the need to manually require dependencies within
-        your PHP code. Per <ulink url="http://php.net/autoload">the PHP autoload manual</ulink>,
-        once an autoloader has been defined, it "is automatically called in case you are trying to use
-        a class/interface which hasn't been defined yet."
+        your <acronym>PHP</acronym> code. Per <ulink url="http://php.net/autoload">the PHP
+        autoload manual</ulink>, once an autoloader has been defined, it "is automatically called
+        in case you are trying to use a class or an interface which hasn't been defined yet."
     </para>
 
     <para>

documentation/manual/en/tutorials/autoloading-resources.xml

@@ -32,7 +32,7 @@ $loader = new Zend_Application_Module_Autoloader(array(
 
     <para>
         Once you have the loader in place, you then need to inform it of the various resource types
-        it's aware of. These resource types are simply subtree/prefix pairs.
+        it's aware of. These resource types are simply pairs of subtree and prefix.
     </para>
 
     <para>
@@ -68,8 +68,9 @@ $loader = new Zend_Loader_Autoloader_Resource(array(
         which the resource type may be found, and the component prefix to use for the resource type.
         In the above tree, we have three resource types: form (in the subdirectory "forms", with a
         component prefix of "Form"), model (in the subdirectory "models", with a component prefix of
-        "Model"), and dbtable (in the subdirectory "models/DbTable, with a component prefix of
-        "Model_DbTable"). We'd define them as follows:
+        "Model"), and dbtable (in the subdirectory "<filename>models/DbTable</filename>",
+        with a component prefix of "<classname>Model_DbTable</classname>"). We'd define them as
+        follows:
     </para>
 
     <programlisting language="php"><![CDATA[
@@ -91,10 +92,11 @@ $guestbook = new Foo_Model_Guestbook();
         <title>Module Resource Autoloading</title>
 
         <para>
-            Zend Framework's MVC layer encourages the use of "modules", which are self-contained
-            applications within your site. Modules typically have a number of resource types by
-            default, and Zend Framework even <link linkend="project-structure.filesystem">recommends
-                a standard directory layout for modules</link>. Resource autoloaders are therefore
+            Zend Framework's <acronym>MVC</acronym> layer encourages the use of "modules", which
+            are self-contained applications within your site. Modules typically have a number of
+            resource types by default, and Zend Framework even
+            <link linkend="project-structure.filesystem">recommends a standard directory layout
+                for modules</link>. Resource autoloaders are therefore
             quite useful in this paradigm -- so useful that they are enabled by default when you
             create a bootstrap class for your module that extends
             <classname>Zend_Application_Module_Bootstrap</classname>. For more information, read

documentation/manual/en/tutorials/autoloading-usage.xml

@@ -11,9 +11,9 @@
 
     <para>
         In the simplest case, you would simply require the class, and then instantiate it. Since
-        <classname>Zend_Loader_Autoloader</classname> is a singleton (due to the fact that the SPL
-        autoloader is a single resource), we use <methodname>getInstance()</methodname> to retrieve
-        an instance.
+        <classname>Zend_Loader_Autoloader</classname> is a singleton (due to the fact that the
+        <acronym>SPL</acronym> autoloader is a single resource), we use
+        <methodname>getInstance()</methodname> to retrieve an instance.
     </para>
 
     <programlisting language="php"><![CDATA[
@@ -23,7 +23,7 @@ Zend_Loader_Autoloader::getInstance();
 
     <para>
         By default, this will allow loading any classes with the class namespace prefixes of "Zend_"
-        or "ZendX_", as long as they are on your <constant>include_path</constant>.
+        or "ZendX_", as long as they are on your <property>include_path</property>.
     </para>
 
     <para>
@@ -61,22 +61,22 @@ $loader->setFallbackAutoloader(true);
             Internally, <classname>Zend_Loader_Autoloader</classname> uses
             <methodname>Zend_Loader::loadClass()</methodname> to load classes. That method uses
             <methodname>include()</methodname> to attempt to load the given class file.
-            <methodname>include()</methodname> will return a boolean <constant>false</constant>
-            if not successful -- but also issues a PHP warning. This latter fact can lead to some
-            issues:
+            <methodname>include()</methodname> will return a boolean <constant>FALSE</constant>
+            if not successful -- but also issues a <acronym>PHP</acronym> warning. This latter
+            fact can lead to some issues:
         </para>
 
         <itemizedlist>
             <listitem>
                 <para>
-                    If <constant>display_errors</constant> is enabled, the warning will be included
+                    If <property>display_errors</property> is enabled, the warning will be included
                     in output.
                 </para>
             </listitem>
 
             <listitem>
                 <para>
-                    Depending on the <constant>error_reporting</constant> level you have chosen, it
+                    Depending on the <property>error_reporting</property> level you have chosen, it
                     could also clutter your logs.
                 </para>
             </listitem>
@@ -85,7 +85,7 @@ $loader->setFallbackAutoloader(true);
         <para>
             You can suppress the error messages (the <classname>Zend_Loader_Autoloader</classname>
             documentation details this), but note that the suppression is only relevant when
-            <constant>display_errors</constant> is enabled; the error log will always display the
+            <property>display_errors</property> is enabled; the error log will always display the
             messages. For these reasons, we recommend always configuring the namespace prefixes the
             autoloader should be aware of
         </para>
@@ -95,20 +95,21 @@ $loader->setFallbackAutoloader(true);
         <title>Namespace Prefixes vs PHP Namespaces</title>
 
         <para>
-            At the time this is written, PHP 5.3 has been released. With that version, PHP now has
-            official namespace support.
+            At the time this is written, <acronym>PHP</acronym> 5.3 has been released. With that
+            version, <acronym>PHP</acronym> now has official namespace support.
         </para>
 
         <para>
-            However, Zend Framework predates PHP 5.3, and thus namespaces. Within Zend Framework,
-            when we refer to "namespaces", we are referring to a practice whereby classes are
-            prefixed with a vender "namespace". As an example, all Zend Framework class names are
-            prefixed with "Zend_" -- that is our vendor "namespace".
+            However, Zend Framework predates <acronym>PHP</acronym> 5.3, and thus namespaces.
+            Within Zend Framework, when we refer to "namespaces", we are referring to a practice
+            whereby classes are prefixed with a vender "namespace". As an example, all Zend
+            Framework class names are prefixed with "Zend_" -- that is our vendor "namespace".
         </para>
 
         <para>
-            Zend Framework plans to offer native PHP namespace support to the autoloader in future
-            revisions, and its own library will utilize namespaces starting with version 2.0.0.
+            Zend Framework plans to offer native <acronym>PHP</acronym> namespace support to the
+            autoloader in future revisions, and its own library will utilize namespaces starting
+            with version 2.0.0.
         </para>
     </note>
 
@@ -117,8 +118,8 @@ $loader->setFallbackAutoloader(true);
         from a third-party library you are also using -- you can manage it with
         <classname>Zend_Loader_Autoloader</classname>'s <methodname>pushAutoloader()</methodname>
         and <methodname>unshiftAutoloader()</methodname> methods. These methods will append or
-        prepend, respectively, autoloaders to a chain that is called prior to executing ZF's
-        internal autoloading mechanism. This approach offers the following benefits:
+        prepend, respectively, autoloaders to a chain that is called prior to executing Zend
+        Framework's internal autoloading mechanism. This approach offers the following benefits:
     </para>
 
     <itemizedlist>
@@ -134,7 +135,7 @@ $loader->setFallbackAutoloader(true);
 
         <listitem>
             <para>
-                If you need to manipulate <methodname>spl_autoload</methodname>'s registry, any
+                If you need to manipulate <methodname>spl_autoload()</methodname>'s registry, any
                 autoloaders that are callbacks pointing to instance methods can pose issues, as
                 <methodname>spl_autoload_functions()</methodname> does not return the exact same
                 callbacks. <classname>Zend_Loader_Autoloader</classname> has no such limitation.
@@ -143,7 +144,7 @@ $loader->setFallbackAutoloader(true);
     </itemizedlist>
 
     <para>
-        Autoloaders managed this way may be any valid PHP callback.
+        Autoloaders managed this way may be any valid <acronym>PHP</acronym> callback.
     </para>
 
     <programlisting language="php"><![CDATA[