Emphasised the need to disable Zend_Controller output buffering when using the Zend_Cache Capture and Page frontends

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

documentation/manual/en/module_specs/Zend_Cache-Backends.xml

@@ -573,6 +573,22 @@ $cache = Zend_Cache::factory('Core', 'Zend_Cache_Backend_ZendServer_Disk',
             involvement of <acronym>PHP</acronym> or Zend Framework at all.
         </para>
 
+        <note>
+                <para>
+                    <classname>Zend_Cache_Frontend_Capture</classname> operates
+                    by registering a callback function to be called
+                    when the output buffering it uses is cleaned. In order for this to operate
+                    correctly, it must be the final output buffer in the request. To guarantee
+                    this, the output buffering used by the Dispatcher MUST be disabled by
+                    calling <classname>Zend_Controller_Front</classname>'s
+                    <methodname>setParam()</methodname> method, for example,
+                    <command>$front->setParam('disableOutputBuffering', true);</command> or adding
+                    "resources.frontcontroller.params.disableOutputBuffering = true"
+                    to your bootstrap configuration file (assumed <acronym>INI</acronym>) if using
+                    <classname>Zend_Application</classname>.
+                </para>
+            </note>
+
         <para>
             The benefits of this cache include a large throughput increase since
             all subsequent requests return the static file and don't need any

documentation/manual/en/module_specs/Zend_Cache-Frontends.xml

@@ -661,7 +661,7 @@ $result = $cache->foobar2('1', '2');
                     This frontend operates by registering a callback function to be called
                     when the output buffering it uses is cleaned. In order for this to operate
                     correctly, it must be the final output buffer in the request. To guarantee
-                    this, the output buffering used by the Dispatcher needs to be disabled by
+                    this, the output buffering used by the Dispatcher MUST be disabled by
                     calling <classname>Zend_Controller_Front</classname>'s
                     <methodname>setParam()</methodname> method, for example,
                     <command>$front->setParam('disableOutputBuffering', true);</command> or adding
@@ -989,6 +989,44 @@ if ($someTest) {
 ]]></programlisting>
         </sect3>
     </sect2>
+
+    <sect2 id="zend.cache.frontends.capture">
+        <title>Zend_Cache_Frontend_Capture</title>
+
+        <sect3 id="zend.cache.frontends.capture.introduction">
+            <title>Introduction</title>
+
+            <para>
+                <classname>Zend_Cache_Frontend_Capture</classname> is like
+                <classname>Zend_Cache_Frontend_Output</classname> but designed for a complete page.
+                It's impossible to use <classname>Zend_Cache_Frontend_Capture</classname> for caching
+                only a single block. This class is specifically designed to operate in concert
+                only with the <classname>Zend_Cache_Backend_Static</classname> backend to
+                assist in caching entire pages of HTML/XML or other content to a physical static
+                file on the local filesystem.
+            </para>
+
+            <para>
+                Please refer to the documentation on <classname>Zend_Cache_Backend_Static</classname>
+                for all use cases pertaining to this class.
+            </para>
+
+            <note>
+                <para>
+                    This frontend operates by registering a callback function to be called
+                    when the output buffering it uses is cleaned. In order for this to operate
+                    correctly, it must be the final output buffer in the request. To guarantee
+                    this, the output buffering used by the Dispatcher MUST be disabled by
+                    calling <classname>Zend_Controller_Front</classname>'s
+                    <methodname>setParam()</methodname> method, for example,
+                    <command>$front->setParam('disableOutputBuffering', true);</command> or adding
+                    "resources.frontcontroller.params.disableOutputBuffering = true"
+                    to your bootstrap configuration file (assumed <acronym>INI</acronym>) if using
+                    <classname>Zend_Application</classname>.
+                </para>
+            </note>
+        </sect3>
+     </sect2>
 </sect1>
 <!--
 vim:se ts=4 sw=4 et: