ZF-6501 - Extended Zend_Tool Writing Providers section by adding a section describes the rules how IncludePathLoader finds your own providers and names them plus an example on how to use a Manifest.

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

documentation/manual/en/module_specs/Zend_Tool_Framework-WritingProviders.xml

@@ -10,37 +10,81 @@
         "controller" is inside of your <acronym>MVC</acronym> application.
     </para>
 
-    <sect2 id="zend.tool.framework.writing-providers.manifest">
-        <title>Exposing Your Providers with a Manifest</title>
+    <sect2 id="zend.tool.framework.writing-providers.loading">
+        <title>How Zend Tool finds your Providers</title>
 
         <para>
-            Before writing your own providers you need to create a manifest, which
-            returns instances of your providers to allow Zend Tool to detect
-            them. A Provider Manifest is an implementation of the
-            <interface>Zend_Tool_Framework_Manifest_ProviderManifestable</interface>
-            and requires the <code>getProviders()</code> method to return
-            an array of instantiated providers. In anticipation of our first
-            own provider <classname>My_Component_HelloProvider</classname>
-            we will create the following manifest:
+            By default Zend Tool uses the IncludePathLoader to find all
+            the providers that you can run. It recursivly iterates all
+            include path directories and opens all files that end
+            with "Manifest.php" or "Provider.php".  All classes in these
+            files are inspected if they implement either
+            <classname>Zend_Tool_Framework_Provider_Interface</classname>
+            or <classname>Zend_Tool_Framework_Manifest_ProviderManifestable</classname>.
+            Instances of the provider interface make up for the real functionality
+            and all their public methods are accessible as provider actions.
+            The ProviderManifestable interface however requires the implementation of a method
+            <methodname>getProviders()</methodname> which returns an array of
+            instantiated provider interface instances.
         </para>
 
-        <programlisting language="php"><![CDATA[
-class My_Component_Manifest implements Zend_Tool_Framework_Manifest_ProviderManifestable
-{
-    public function getProviders()
+        <para>
+            The following naming rules apply on how you can access the providers
+            that were found by the IncludePathLoader:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                The last part of your classname split by underscore is used
+                for the provider name, e.g. "My_Provider_Hello" leads to your
+                provider being accessible by the name "hello".
+            </listitem>
+            <listitem>
+                If your provider has a method <methodname>getCode()</methodname>
+                it will be used instead of the previous method to determine
+                the name.
+            </listitem>
+            <listitem>
+                If your provider has "Provider" as prefix, e.g. it is called
+                <classname>My_HelloProvider</classname> it will be stripped
+                from the name so that the provider will be called "hello".
+            </listitem>
+        </itemizedlist>
+
+        <note>
+            <para>The IncludePathLoader does not follow symlinks, that means
+            you cannot link provider functionality into your include paths,
+            they have to be physically present in the include paths.</para>
+        </note>
+
+        <example id="zend.tool.framework.writing-providers.loading.example">
+            <title>Exposing Your Providers with a Manifest</title>
+
+            <para>
+                You can expose your providers to Zend Tool by offering a manifest
+                with a special filename ending with "Manifest.php".
+                A Provider Manifest is an implementation of the
+                <interface>Zend_Tool_Framework_Manifest_ProviderManifestable</interface>
+                and requires the <code>getProviders()</code> method to return
+                an array of instantiated providers. In anticipation of our first
+                own provider <classname>My_Component_HelloProvider</classname>
+                we will create the following manifest:
+            </para>
+
+            <programlisting language="php"><![CDATA[
+    class My_Component_Manifest implements Zend_Tool_Framework_Manifest_ProviderManifestable
     {
-        return array(
-            new My_Component_HelloProvider()
-        );
+        public function getProviders()
+        {
+            return array(
+                new My_Component_HelloProvider()
+            );
+        }
     }
-}
-]]>
-        </programlisting>
+    ]]>
+            </programlisting>
 
-        <para>
-            A provider manifest class always has to end with the Term "Manifest" otherwise
-            Zend_Tool cannot autodetect it while searching through your include path.
-        </para>
+        </example>
     </sect2>
 
     <sect2 id="zend.tool.framework.writing-providers.basic">