[DOCUMENTATION] German:

- sync up to r15224

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

documentation/manual/de/manual.xml.in

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: 15157 -->
+<!-- EN-Revision: 15216 -->
 +<!-- Reviewed: no -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
     "@DOCBOOK_DTD@"
@@ -507,7 +507,9 @@
         <xi:include href="module_specs/Zend_Tool_Project.xml" />
         <xi:include href="module_specs/Zend_Tool_Project-CreateProject.xml" />
         <xi:include href="module_specs/Zend_Tool_Project-Providers.xml" />
+        <!--
         <xi:include href="module_specs/Zend_Tool_Project-Internals.xml" />
+        -->
     </chapter>
 
     <chapter id="zend.translate">

documentation/manual/de/module_specs/Zend_Tool_Framework-Architecture.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: 15103 -->
+<!-- EN-Revision: 15223 -->
 <!-- Reviewed: no -->
 <sect1 id="zend.tool.framework.architecture">
     <title>Architecture</title>
@@ -111,39 +111,6 @@ abstract class Zend_Tool_Framework_Provider_Abstract
 }
 ]]></programlisting>
 
-        <para>
-            As an example, if a developer wants to add the capability of showing
-            the version of a datafile that his 3rd party component is working
-            from, there is only one class the developer would need to implement.
-            Assuming the component is called <code>My_Component</code>, he would
-            create a class named <code>My_Component_HelloProvider</code> in a
-            file named <code>HelloProvider.php</code> somewhere on the
-            <code>include_path</code>.  This class would implement
-            <classname>Zend_Tool_Framework_Provider_Interface</classname>, and the body of
-            this file would only have to look like the following:
-        </para>
-
-        <programlisting role="php"><![CDATA[
-class My_Component_HelloProvider
-    implements Zend_Tool_Framework_Provider_Interface
-{
-    public function say()
-    {
-        echo 'Hello from my provider!';
-    }
-}
-]]></programlisting>
-
-        <para>
-            Given that code above, and assuming the developer wishes to access
-            this functionality through the console client, the call would look
-            like this:
-        </para>
-
-        <programlisting role="sh"><![CDATA[
-% zf say hello
-Hello from my provider!
-]]></programlisting>
     </sect2>
 
     <sect2 id="zend.tool.framework.architecture.loaders">
@@ -255,7 +222,7 @@ interface Zend_Tool_Framework_Manifest_Interface
         </para>
 
         <programlisting role="php"><![CDATA[
-class Zend_Tool_Framework_Manifest_Metadata
+class Zend_Tool_Framework_Manifest_Basic
 {
 
     protected $_type        = 'Global';
@@ -403,28 +370,32 @@ abstract class Zend_Tool_Framework_Client_Abstract
     /**
      * This method should be implemented by the client implementation to
      * construct and set custom loaders, request and response objects.
+     *
+     * (not required, but suggested)
      */
-    abstract protected function _init();
+    protected function _preInit();
 
     /**
      * This method should be implemented by the client implementation to parse
      * out and setup the request objects action, provider and parameter
      * information.
      */
-    abstract protected function _preHandle();
+    abstract protected function _preDispatch();
 
     /**
      * This method should be implemented by the client implementation to take
      * the output of the response object and return it (in an client specific
      * way) back to the Tooling Client.
+     *
+     * (not required, but suggested)
      */
-    abstract protected function _postHandle();
+    abstract protected function _postDispatch();
 }
 ]]></programlisting>
 
         <para>
-            As you can see, there are 3 methods needed to fulfill the needs of a
-            client, the initialization, prehandling and post handling.  For a
+            As you can see, there is 1 method required to fulfill the needs of a
+            client (two othres suggested), the initialization, prehandling and post handling.  For a
             more in depth study of how the command line client works, please see
             <ulink url="http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Tool/Framework/Client/Console.php">source code</ulink>.
         </para>

documentation/manual/de/module_specs/Zend_Tool_Framework-CliTool.xml

@@ -1,8 +1,280 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: 14978 -->
+<!-- EN-Revision: 15223 -->
 <!-- Reviewed: no -->
 <sect1 id="zend.tool.framework.clitool">
     <title>Verwenden des CLI Tools</title>
-    <para></para>
-    <!-- @todo -->
+
+    <para>
+        The CLI, or command line tool (internally known as the console tool), is
+        currently the primary interface for dispatching <code>Zend_Tool</code>
+        requests.  With the CLI tool, developers can issue tooling requests
+        inside a the "command line windows", also commonly known as a "terminal"
+        window.  This environment is predominant in the *nix environment, but
+        also has a common implementation in windows with the
+        <code>cmd.exe</code>, console2 and also with the Cygwin project.
+    </para>
+
+    <sect2 id="zend.tool.framework.clitool.setup-general">
+        <title>Setting up the CLI tool</title>
+
+        <para>
+            To issue tooling requests via the command line client, you first
+            need to setup the client so that your system can handle the "zf"
+            command.  The command line client, for all intents and purposes, is
+            the <code>.sh</code> or <code>.bat</code> file that is provided with
+            your Zend Framework distribution.  In trunk, it can be found here:
+            <ulink url="http://framework.zend.com/svn/framework/standard/trunk/bin/">http://framework.zend.com/svn/framework/standard/trunk/bin/</ulink>
+        </para>
+
+        <para>
+            As you can see, there are 3 files in the <code>bin/</code>
+            directory: a <code>zf.php</code>, <code>zf.sh</code>, and
+            <code>zf.bat</code>.  The <code>zf.sh</code> and the
+            <code>zf.bat</code> are the operating system specific client
+            wrappers: <code>zf.sh</code> for the *nix environment, and zf.bat
+            for the Win32 environment.  These client wrappers are responsible
+            for finding the proper <code>php.exe</code>, finding the
+            <code>zf.php</code>, and passing on the client request.  The
+            <code>zf.php</code> is the responsible for handling understanding
+            your environment, constructing the proper include_path, and passing
+            what is provided on the command line to the proper library component
+            for dispatching.
+        </para>
+
+        <para>
+            Ultimately, you want to ensure two things to make everything work
+            regardless of the operating system you are on:
+        </para>
+
+        <orderedlist>
+            <listitem>
+                <para>
+                    <code>zf.sh/zf.bat</code> is reachable from your system
+                    path.  This is the ability to call <code>zf</code> from
+                    anywhere on your command line, regardless of what your
+                    current working directory is.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    ZendFramework/library is in your <code>include_path</code>.
+                </para>
+            </listitem>
+        </orderedlist>
+
+        <para>
+            <emphasis>Note:</emphasis> while the above are the most ideal
+            requirements, you can simply download Zend Framework and expect it
+            to work as <code>./path/to/zf.php</code> some command.
+        </para>
+
+    </sect2>
+
+    <sect2 id="zend.tool.framework.clitool.setup-starnix">
+        <title>Setting up the CLI tool on Unix-like Systems</title>
+
+        <para>
+            The most common setup in the *nix environment, is to copy the
+            <code>zf.sh</code> and <code>zf.php</code> into the same directory
+            as your PHP binary.  This can generally be found in one of the
+            following places:
+        </para>
+
+        <programlisting role="text"><![CDATA[
+/usr/bin
+/usr/local/bin
+/usr/local/ZendServer/bin/
+/Applications/ZendServer/bin/
+]]></programlisting>
+
+        <para>
+            To find out the location of your PHP binary, you can execute 'which
+            php' on the command line.  This will return the location of the php
+            binary you will be using to run php scripts in this environment.
+        </para>
+
+        <para>
+            The next order of business is to ensure that the Zend Framework
+            library is setup correctly inside of the system PHP
+            <code>include_path</code>.  To find out where your
+            <code>include_path</code> is located, you can execute 'php -i' and
+            look for the <code>include_path</code> variable, or more succinctly,
+            execute 'php -i | grep include_path'.  Once you have found where
+            your <code>include_path</code> is located (this will generally be
+            something like /usr/lib/php, /usr/share/php, /usr/local/lib/php, or
+            similar), ensure that the contents of the library/ directory are put
+            inside your <code>include_path</code> specified directory.
+        </para>
+
+        <para>
+            Once you have done those two things, you should be able to issue a
+            command and get back the proper response like this:
+        </para>
+
+        <para>
+            <inlinegraphic scale="100" align="center" valign="middle"
+                fileref="figures/zend.tool.framework.cliversionunix.png" format="PNG" />
+        </para>
+
+        <para>
+            If you do not see this type of output, go back and check your setup
+            to ensure you have all of the necessary peices in the proper place.
+        </para>
+
+        <para>
+            There are a couple of alternative setups you might want to employ
+            depending on your servers configuration, your level of access, or
+            for other reasons.
+        </para>
+
+        <para>
+            <emphasis>ALTERNATIVE SETUP</emphasis> involves keeping the Zend
+            Framework download together as is, and creating a link from a PATH
+            location to the <code>zf.sh</code>.  What this means is you can
+            place the contents of the ZendFramework download into a location
+            such as <code>/usr/local/share/ZendFramework</code>, or more locally
+            like <code>/home/username/lib/ZendFramework</code>, and creating a
+            symbolic link to the <code>zf.sh</code>.
+        </para>
+
+        <para>
+            Assuming you want to put the link inside <code>/usr/local/bin</code>
+            (this could also work for placing the link inside
+            <code>/home/username/bin/</code> for example) you would issue a
+            command similar to this: </para>
+
+        <programlisting role="sh"><![CDATA[
+ln -s /usr/local/share/ZendFramework/bin/zf.sh /usr/local/bin/zf
+
+# OR (for example)
+ln -s /home/username/lib/ZendFramework/bin/zf.sh /home/username/bin/zf
+]]></programlisting>
+
+        <para>
+            This will create a link which you should be able to access globally
+            on the command line.
+        </para>
+
+    </sect2>
+
+    <sect2 id="zend.tool.framework.clitool.setup-windows">
+        <title>Setting up the CLI tool on Windows</title>
+
+        <para>
+            The most common setup in the Windows Win32 environment, is to copy
+            the <code>zf.sh</code> and <code>zf.php</code> into the same
+            directory as your PHP binary.  This can generally be found in one of
+            the following places:
+        </para>
+
+        <programlisting role="text"><![CDATA[
+C:\PHP
+C:\Program Files\ZendServer\bin\
+C:\WAMP\PHP\bin
+]]></programlisting>
+
+        <para>
+            You should be able to run <code>php.exe</code> on the command line.
+            If you are not able to, first check the documentation that came with
+            your PHP distribution, or ensure that the path to php.exe is in your
+            windows PATH environment variable.
+        </para>
+
+        <para>
+            The next order of business is to ensure that the Zend Framework
+            library is setup correctly inside of the system PHP
+            <code>include_path</code>.  To find out where your
+            <code>include_path</code> is located, you can type 'php -i' and look
+            for the <code>include_path</code> variable, or more succinctly
+            execute 'php -i | grep include_path' if you have Cygwin setup with
+            grep available.  Once you have found where your
+            <code>include_path</code> is located (this will generally be
+            something like <code>C:\PHP\pear</code>, <code>C:\PHP\share</code>,
+            <code>C:\Program Files\ZendServer\share</code> or similar), ensure
+            that the contents of the library/ directory are put inside your
+            <code>include_path</code> specified directory.
+        </para>
+
+        <para>
+            Once you have done those two things, you should be able to issue a
+            command and get back the proper response like this:
+        </para>
+
+        <para>
+            <inlinegraphic scale="100" align="center" valign="middle"
+                fileref="figures/zend.tool.framework.cliversionwin32.png" format="PNG" />
+        </para>
+
+        <para>
+            If you do not see this type of output, go back and check your setup
+            to ensure you have all of the necessary pieces in the proper place.
+        </para>
+
+        <para>
+            There are a couple of alternative setups you might want to employ
+            depending on your server's configuration, your level of access, or
+            for other reasons.
+        </para>
+
+        <para>
+            <emphasis>ALTERNATIVE SETUP</emphasis> involves keeping the Zend
+            Framework download together as is, and altering both your system
+            PATH as well as the <code>php.ini</code> file.  In your user's
+            environment, make sure to add
+            <code>C:\Path\To\ZendFramework\bin</code>, so that your
+            <code>zf.bat</code> file is executable.  Also, alter the
+            <code>php.ini</code> file to ensure that
+            <code>C:\Path\To\ZendFramework\library</code> is in your
+            <code>include_path</code>.
+        </para>
+
+    </sect2>
+
+    <sect2 id="zend.tool.framework.clitool.setup-othernotes">
+        <title>Other Setup Considerations</title>
+
+        <para>
+            If for some reason you do not want the Zend Framework library inside
+            your <code>include_path</code>, there is another option.  There are
+            two special environment variables that <code>zf.php</code> will
+            utilize to determine the location of your Zend Framework
+            installation.
+        </para>
+
+        <para>
+            The first is <code>ZEND_TOOL_INCLUDE_PATH_PREPEND</code>, which will
+            prepend the value of this environment variable to the system
+            (<code>php.ini</code>) <code>include_path</code> before loading the
+            client.
+        </para>
+
+        <para>
+            Alternatively, you might want to use
+            <code>ZEND_TOOL_INCLUDE_PATH</code> to completely
+            <emphasis>replace</emphasis> the system <code>include_path</code>
+            for one that makes sense specifically for the <code>zf</code>
+            command line tool.
+        </para>
+    </sect2>
+
+    <sect2 id="zend.tool.framework.clitool.continuing">
+        <title>Where To Go Next?</title>
+
+        <para>
+            At this point, your should be setup to start initiating some more
+            "interesting" commands.  To get going, you can issue the <code>zf
+                --help</code> command to see what is available to you.
+        </para>
+
+        <para>
+            <inlinegraphic scale="100" align="center" valign="middle"
+                fileref="figures/zend.tool.framework.clihelp.png" format="PNG" />
+        </para>
+
+        <para>
+            Continue on to the <code>Zend_Tool_Project</code> "Create Project"
+            section to understand how to use the <code>zf</code> script for
+            project creation.
+        </para>
+    </sect2>
 </sect1>

documentation/manual/de/module_specs/Zend_Tool_Framework-SystemProviders.xml

@@ -1,8 +1,50 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: 14978 -->
+<!-- EN-Revision: 15220 -->
 <!-- Reviewed: no -->
 <sect1 id="zend.tool.framework.system-providers">
     <title>Mitgelieferte System Provider</title>
-    <para></para>
-    <!-- @todo -->
+
+    <para>
+        In addition to the more useful project based providers that come shipped
+        with <code>Zend_Tool_Project</code>, there are also some more basic, but
+        interesting providers that come built into
+        <code>Zend_Tool_Framework</code>.  Some of these exist for the purpose
+        of providing a means via the command line to extract information, such
+        as the version, while others are intended to aid the developer when
+        creating additional providers.
+    </para>
+
+    <sect2 id="zend.tool.framework.system-providers.version">
+        <title>The Version Provider</title>
+
+        <para>
+            The Version provider is included so that you may determine which
+            version of the framework that the <code>zf</code> or
+            <code>Zend_Tool</code> is currently set to work with.
+        </para>
+
+        <para>
+            Through the command line, simply run <code>zf show version</code>.
+        </para>
+
+    </sect2>
+
+    <sect2 id="zend.tool.framework.system-providers.manifest">
+        <title>The Manifest Provider</title>
+
+        <para>
+            The Manifest provider is included so that you may determine what
+            kind of "manifest" information is available during the
+            <code>Zend_Tool</code> runtime.  Manifest data is information that
+            is attached to specific objects during <code>Zend_Tool</code>'s
+            runtime.  Inside the manifest you will find the console specific
+            namings that you are expected to use when calling certain commands.
+            Data found in the manifest can be used by any provider or client on
+            an as-needed basis.
+        </para>
+
+        <para>
+            Through the command line, simply run <code>zf show manifest</code>.
+        </para>
+    </sect2>
 </sect1>

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

@@ -1,8 +1,128 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: 14978 -->
+<!-- EN-Revision: 15220 -->
 <!-- Reviewed: no -->
 <sect1 id="zend.tool.framework.writing-providers">
     <title>Erstellen von Providern für die Verwendung mit Zend_Tool_Framework</title>
-    <para></para>
-    <!-- @todo -->
+
+    <para>
+        In general, a provider, on its own, is nothing more than the shell for a
+        developer to bundle up some capabilities they wish to dispatch with the
+        command line (or other) clients.  It is an analogue to what a
+        "controller" is inside of your MVC application.
+    </para>
+
+    <sect2 id="zend.tool.framework.writing-providers.basic">
+        <title>Basic Instructions for Creating Providers</title>
+
+        <para>
+            As an example, if a developer wants to add the capability of showing
+            the version of a datafile that his 3rd party component is working
+            from, there is only one class the developer would need to implement.
+            Assuming the component is called <code>My_Component</code>, he would
+            create a class named <code>My_Component_HelloProvider</code> in a
+            file named <code>HelloProvider.php</code> somewhere on the
+            <code>include_path</code>.  This class would implement
+            <classname>Zend_Tool_Framework_Provider_Interface</classname>, and the body of
+            this file would only have to look like the following:
+        </para>
+
+        <programlisting role="php"><![CDATA[
+class My_Component_HelloProvider
+    implements Zend_Tool_Framework_Provider_Interface
+{
+    public function say()
+    {
+        echo 'Hello from my provider!';
+    }
+}
+]]></programlisting>
+
+        <para>
+            Given that code above, and assuming the developer wishes to access
+            this functionality through the console client, the call would look
+            like this:
+        </para>
+
+        <programlisting role="sh"><![CDATA[
+% zf say hello
+Hello from my provider!
+]]></programlisting>
+    </sect2>
+
+    <sect2 id="zend.tool.framework.writing-providers.advanced">
+        <title>Advanced Development Information</title>
+
+        <para>
+            The above "Hello World" example is great for simple commands, but
+            what about something more advanced?  As your scripting and tooling
+            needs grow, you might find that you need the ability to accept
+            variables.  Much like function signatures have parameters, your
+            tooling requests can also accept parameters.
+        </para>
+
+        <para>
+            Just as each tooling request can be isolated to a method within a
+            class, the parameters of a tooling request can also be isolated in a
+            very well known place.  Parameters of the action methods of a
+            provider can include the same parameters you want your client to
+            utilize when calling that provider and action combination.  For
+            example, if you wanted to accept a name in the above example, you
+            would probably do this in OO code:
+        </para>
+
+        <programlisting role="php"><![CDATA[
+class My_Component_HelloProvider
+    implements Zend_Tool_Framework_Provider_Interface
+{
+    public function say($name = 'Ralph')
+    {
+        echo 'Hello' . $name . ', from my provider!';
+    }
+}
+]]></programlisting>
+
+        <para>
+            The above example can then be called via the command line <code>zf
+                say hello Joe</code>.  "Joe" will be supplied to the provider as
+            a parameter of the method call.  Also note, as you see that the
+            parameter is optional, that means it is also optional on the command
+            line, so that <code>zf say hello</code> will still work, and default
+            to the name "Ralph".
+        </para>
+
+        <para>
+            Another interesting feature you might wish to implement is
+            <emphasis>pretendability</emphasis>.  Pretendabilty is the ability
+            for your provider to "pretend" as if it is doing the requested
+            action and provider combination and give the user as much
+            information about what it <emphasis>would</emphasis> do without
+            actually doing it.  This might be an important notion when doing
+            heavy database or filesystem modifications that the user might not
+            otherwise want to do.
+        </para>
+
+        <para>
+            Pretendability is easy to implement.  There are two parts to this
+            feature: 1) marking the provider as having the ability to "pretend",
+            and 2) checking the request to ensure the current request was indeed
+            asked to be "pretended".  This feature is demonstrated in the code
+            sample below.
+        </para>
+
+        <programlisting role="php"><![CDATA[
+class My_Component_HelloProvider
+    extends    Zend_Tool_Framework_Provider_Abstract
+    implements Zend_Tool_Framework_Provider_Pretendable
+{
+    public function say($name = 'Ralph')
+    {
+        if ($this->_registry->getRequest()->isPretend()) {
+            echo 'I would say hello to ' . $name . '.';
+        } else {
+            echo 'Hello' . $name . ', from my provider!';
+        }
+    }
+}
+]]></programlisting>
+    </sect2>
 </sect1>