cvs: smarty /docs/en/programmers/caching caching-cacheable.xml caching-groups.xml caching-multiple-caches.xml caching-setting-up.xml

http://cvs.php.net/viewvc.cgi/smarty/docs/en/programmers/caching/caching-cacheable.xml?r1=1.9&r2=1.10&diff_format=u
Index: smarty/docs/en/programmers/caching/caching-cacheable.xml
diff -u smarty/docs/en/programmers/caching/caching-cacheable.xml:1.9 smarty/docs/en/programmers/caching/caching-cacheable.xml:1.10
--- smarty/docs/en/programmers/caching/caching-cacheable.xml:1.9	Fri Feb 17 22:18:05 2006
+++ smarty/docs/en/programmers/caching/caching-cacheable.xml	Wed Sep 27 00:54:40 2006
@@ -1,25 +1,26 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
  <sect1 id="caching.cacheable">
   <title>Controlling Cacheability of Plugins' Output</title>
   <para>
    Since Smarty-2.6.0 plugins the cacheability of plugins can be
-   declared when registering them. The third parameter to <link
-   linkend="api.register.block">register_block()</link>, <link
-   linkend="api.register.compiler.function">register_compiler_function()
-   </link> and <link
-   linkend="api.register.function">register_function()</link> is
-   called <parameter>$cacheable</parameter> and defaults to true which
+   declared when registering them. The third parameter to
+   <link linkend="api.register.block"><varname>register_block()</varname></link>,
+   <link linkend="api.register.compiler.function">
+   <varname>register_compiler_function()</varname></link> and <link
+   linkend="api.register.function"><varname>register_function()</varname></link>
+    is called <parameter>$cacheable</parameter> and defaults to &true; which
    is also the behaviour of plugins in Smarty versions before 2.6.0
   </para>
   <para>
-   When registering a plugin with $cacheable=false the plugin is
-   called everytime the page is displayed, even if the page comes
+   When registering a plugin with <literal>$cacheable=false</literal> the plugin
+   is called everytime the page is displayed, even if the page comes
    from the cache. The plugin function behaves a little like an
-   <link linkend="plugins.inserts">insert</link> function.
+   <link linkend="plugins.inserts"><varname>{insert}</varname></link> function.
   </para>
   <para>
-   In contrast to <link linkend="plugins.inserts">insert</link>
+   In contrast to <link linkend="plugins.inserts"><varname>{insert}</varname>
+   </link>
    the attributes to the plugins are not cached by default. They can be
    declared to be cached with the fourth parameter
    <parameter>$cache_attrs</parameter>. <parameter>$cache_attrs</parameter>
@@ -33,8 +34,6 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-require('Smarty.class.php');
-$smarty = new Smarty;
 $smarty->caching = true;
 
 function remaining_seconds($params, &$smarty) {
@@ -58,7 +57,7 @@
 ]]>
    </programlisting>
    <para>
-    where index.tpl is:
+    where <filename>index.tpl</filename> is:
    </para>
    <programlisting>
 <![CDATA[
@@ -66,8 +65,8 @@
 ]]>
    </programlisting>
    <para>
-    The number of seconds till the endtime of $obj is reached changes on
-    each display of the page, even if the page is cached. Since the
+    The number of seconds till the endtime of <literal>$obj</literal> is reached
+    changes on each display of the page, even if the page is cached. Since the
     endtime attribute is cached the object only has to be pulled from the
     database when page is written to the cache but not on subsequent requests
     of the page.
@@ -81,9 +80,7 @@
 index.php:
 
 <?php
-require('Smarty.class.php');
-$smarty = new Smarty;
-$smarty->caching = true;
+$smarty->caching = 1;
 
 function smarty_block_dynamic($param, $content, &$smarty) {
     return $content;
@@ -95,15 +92,15 @@
 ]]>
    </programlisting>
    <para>
-    where index.tpl is:
+    where <filename>index.tpl</filename> is:
    </para>
    <programlisting>
 <![CDATA[
-Page created: {"0"|date_format:"%D %H:%M:%S"}
+Page created: {'0'|date_format:'%D %H:%M:%S'}
 
 {dynamic}
 
-Now is: {"0"|date_format:"%D %H:%M:%S"}
+Now is: {'0'|date_format:'%D %H:%M:%S'}
 
 ... do other stuff ...
 
@@ -114,9 +111,9 @@
 
   <para>
    When reloading the page you will notice that both dates differ. One
-   is "dynamic" one is "static". You can do everything between
-   {dynamic}...{/dynamic} and be sure it will not be cached like the rest
-   of the page.
+   is <quote>dynamic</quote> one is <quote>static</quote>. You can do everything
+    between <literal>{dynamic}...{/dynamic}</literal> and be sure it will not
+    be cached like the rest of the page.
   </para>
 
  </sect1>
http://cvs.php.net/viewvc.cgi/smarty/docs/en/programmers/caching/caching-groups.xml?r1=1.6&r2=1.7&diff_format=u
Index: smarty/docs/en/programmers/caching/caching-groups.xml
diff -u smarty/docs/en/programmers/caching/caching-groups.xml:1.6 smarty/docs/en/programmers/caching/caching-groups.xml:1.7
--- smarty/docs/en/programmers/caching/caching-groups.xml:1.6	Sat Feb 18 11:53:24 2006
+++ smarty/docs/en/programmers/caching/caching-groups.xml	Wed Sep 27 00:54:40 2006
@@ -1,39 +1,65 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
    <sect1 id="caching.groups">
     <title>Cache Groups</title>
      <para>
-      You can do more elaborate grouping by setting up $cache_id groups. This is
-      accomplished by separating each sub-group with a vertical bar "|" in the
-      $cache_id value. You can have as many sub-groups as you like.
+      You can do more elaborate grouping by setting up
+      <parameter>$cache_id</parameter> groups. This is
+      accomplished by separating each sub-group with a vertical bar
+      <literal>|</literal> in the <parameter>$cache_id</parameter> value.
+      You can have as many sub-groups as you like.
      </para>
-     <para>
+
+     <itemizedlist>
+     <listitem><para>
       You can think of cache groups like a directory hierarchy. For instance, a
-      cache group of "a|b|c" could be thought of as the directory structure
-      "/a/b/c/". <link linkend="api.clear.cache">clear_cache</link>(null,"a|b|c") 
+      cache group of <literal>'a|b|c'</literal> could be thought of as the
+      directory structure <literal>'/a/b/c/'</literal>.
+      </para></listitem>
+
+      <listitem><para>
+      <literal>clear_cache(null,'a|b|c')</literal>
       would be like removing the files
-      "/a/b/c/*". clear_cache(null,"a|b") would be like removing the files
-      "/a/b/*". If you specify a <link linkend="variable.compile.id">$compile_id</link> such as
-      clear_cache(null,"a|b","foo") it is treated as an appended cache group
-      "/a/b/c/foo/". If you specify a template name such as
-      clear_cache("foo.tpl","a|b|c") then Smarty will attempt to remove
-      "/a/b/c/foo.tpl". You CANNOT remove a specified template name under
-      multiple cache groups such as "/a/b/*/foo.tpl", the cache grouping works
+      <literal>'/a/b/c/*'</literal>. <literal>clear_cache(null,'a|b')</literal>
+      would be like removing the files <literal>'/a/b/*'</literal>.
+      </para></listitem>
+
+      <listitem><para>
+      If you specify a
+      <link linkend="variable.compile.id"><parameter>$compile_id</parameter></link>
+      such as <literal>clear_cache(null,'a|b','foo')</literal> it is treated as
+      an appended cache group <literal>'/a/b/c/foo/'</literal>.
+      </para></listitem>
+
+      <listitem><para>
+      If you specify a template name such as
+      <literal>clear_cache('foo.tpl','a|b|c')</literal> then Smarty will attempt
+      to remove <literal>'/a/b/c/foo.tpl'</literal>.
+      </para></listitem>
+
+      <listitem><para>
+      You CANNOT remove a specified template name under
+      multiple cache groups such as <literal>'/a/b/*/foo.tpl'</literal>, the
+      cache grouping works
       left-to-right ONLY. You will need to group your templates under a single
       cache group heirarchy to be able to clear them as a group.
-     </para>
+     </para></listitem>
+     </itemizedlist>
+
      <para>
       Cache grouping should not be confused with your template directory
       heirarchy, the cache grouping has no knowledge of how your templates are
       structured. So for example, if you have a template structure like
-      "themes/blue/index.tpl" and you want to be able to clear all the cache
-      files for the "blue" theme, you will need to create a cache group
+      <filename>themes/blue/index.tpl</filename> and you want to be able to
+      clear all the cache files for the <quote>blue</quote> theme, you will need
+      to create a cache group
       structure that mimics your template file structure, such as
-      display("themes/blue/index.tpl","themes|blue"), then clear them with
-      clear_cache(null,"themes|blue").
+      <literal>display('themes/blue/index.tpl','themes|blue')</literal>, then
+      clear them with
+      <literal>clear_cache(null,'themes|blue')</literal>.
      </para>
      <example>
-      <title>cache_id groups</title>
+      <title>$cache_id groups</title>
       <programlisting role="php">
 <![CDATA[
 <?php
@@ -58,7 +84,7 @@
 ]]>
       </programlisting>
      </example>
-    
+
     </sect1>
 
 <!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/smarty/docs/en/programmers/caching/caching-multiple-caches.xml?r1=1.4&r2=1.5&diff_format=u
Index: smarty/docs/en/programmers/caching/caching-multiple-caches.xml
diff -u smarty/docs/en/programmers/caching/caching-multiple-caches.xml:1.4 smarty/docs/en/programmers/caching/caching-multiple-caches.xml:1.5
--- smarty/docs/en/programmers/caching/caching-multiple-caches.xml:1.4	Sat Feb 18 13:18:16 2006
+++ smarty/docs/en/programmers/caching/caching-multiple-caches.xml	Wed Sep 27 00:54:40 2006
@@ -1,70 +1,74 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
    <sect1 id="caching.multiple.caches">
     <title>Multiple Caches Per Page</title>
     <para>
      You can have multiple cache files for a single call to
-     <link linkend="api.display">display()</link>
-     or <link linkend="api.fetch">fetch()</link>.
-     Let's say that a call to display('index.tpl') may have several
-     different output contents depending on some condition, and you want
-     separate caches for each one. You can do this by passing a $cache_id as the
-     second parameter to the function call.
+     <link linkend="api.display"><varname>display()</varname></link>
+     or <link linkend="api.fetch"><varname>fetch()</varname></link>.
+     Let's say that a call to <literal>display('index.tpl')</literal> may have
+     several different output contents depending on some condition, and you want
+     separate caches for each one. You can do this by passing a
+     <parameter>$cache_id</parameter> as the second parameter to the
+     function call.
     </para>
     <example>
-     <title>passing a $cache_id to display()</title>
+     <title>Passing a $cache_id to display()</title>
      <programlisting role="php">
 <![CDATA[
 <?php
 require('Smarty.class.php');
 $smarty = new Smarty;
 
-$smarty->caching = true;
+$smarty->caching = 1;
 
 $my_cache_id = $_GET['article_id'];
 
-$smarty->display('index.tpl',$my_cache_id);
+$smarty->display('index.tpl', $my_cache_id);
 ?>
 ]]>
      </programlisting>
     </example>
     <para>
-     Above, we are passing the variable $my_cache_id to
-     <link linkend="api.display">display()</link>
-     as the
-     cache_id. For each unique value of $my_cache_id, a separate cache will be
-     generated for index.tpl. In this example, "article_id" was passed in the
-     URL and is used as the cache_id.
+     Above, we are passing the variable <literal>$my_cache_id</literal> to
+     <link linkend="api.display"><varname>display()</varname></link>
+     as the <parameter>$cache_id</parameter>. For each unique value of
+     <literal>$my_cache_id</literal>, a separate cache will be
+     generated for <filename>index.tpl</filename>. In this example,
+     <literal>article_id</literal> was passed in the
+     URL and is used as the <parameter>$cache_id</parameter>.
     </para>
     <note>
      <title>Technical Note</title>
      <para>
       Be very cautious when passing values from a client (web browser) into
-      Smarty (or any PHP application.) Although the above example of using the
+      Smarty or any PHP application. Although the above example of using the
       article_id from the URL looks handy, it could have bad consequences. The
-      cache_id is used to create a directory on the file system, so if the user
+      <parameter>$cache_id</parameter> is used to create a directory on the file
+      system, so if the user
       decided to pass an extremely large value for article_id, or write a script
-      that sends random article_ids at a rapid pace, this could possibly cause
+      that sends random article_id's at a rapid pace, this could possibly cause
       problems at the server level. Be sure to sanitize any data passed in before
       using it. In this instance, maybe you know the article_id has a length of
-      10 characters and is made up of alpha-numerics only, and must be a valid
+      ten characters and is made up of alpha-numerics only, and must be a valid
       article_id in the database. Check for this!
      </para>
     </note>
     <para>
-     Be sure to pass the same cache_id as the
-     second parameter to <link linkend="api.is.cached">is_cached()</link> and
-     <link linkend="api.clear.cache">clear_cache()</link>.
+     Be sure to pass the same <parameter>$cache_id</parameter> as the
+     second parameter to
+     <link linkend="api.is.cached"><varname>is_cached()</varname></link> and
+     <link linkend="api.clear.cache"><varname>clear_cache()</varname></link>.
     </para>
     <example>
-     <title>passing a cache_id to is_cached()</title>
+     <title>Passing a cache_id to is_cached()</title>
      <programlisting role="php">
 <![CDATA[
 <?php
 require('Smarty.class.php');
 $smarty = new Smarty;
 
-$smarty->caching = true;
+$smarty->caching = 1;
 
 $my_cache_id = $_GET['article_id'];
 
@@ -80,35 +84,36 @@
      </programlisting>
     </example>
     <para>
-     You can clear all caches for a particular cache_id by passing null as the
+     You can clear all caches for a particular <parameter>$cache_id</parameter>
+     by passing &null; as the
      first parameter to
-     <link linkend="api.clear.cache">clear_cache()</link>.
+     <link linkend="api.clear.cache"><varname>clear_cache()</varname></link>.
     </para>
     <example>
-     <title>clearing all caches for a particular cache_id</title>
+     <title>Clearing all caches for a particular $cache_id</title>
      <programlisting role="php">
 <![CDATA[
 <?php
 require('Smarty.class.php');
 $smarty = new Smarty;
 
-$smarty->caching = true;
+$smarty->caching = 1;
 
-// clear all caches with "sports" as the cache_id
-$smarty->clear_cache(null,"sports");
+// clear all caches with "sports" as the $cache_id
+$smarty->clear_cache(null,'sports');
 
-$smarty->display('index.tpl',"sports");
+$smarty->display('index.tpl','sports');
 ?>
 ]]>
      </programlisting>
     </example>
     <para>
-     In this manner, you can "group" your caches together by giving them the
-     same cache_id.
+     In this manner, you can <quote>group</quote> your caches together by giving
+     them the same <parameter>$cache_id</parameter>.
     </para>
-    
+
    </sect1>
-   
+
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
http://cvs.php.net/viewvc.cgi/smarty/docs/en/programmers/caching/caching-setting-up.xml?r1=1.7&r2=1.8&diff_format=u
Index: smarty/docs/en/programmers/caching/caching-setting-up.xml
diff -u smarty/docs/en/programmers/caching/caching-setting-up.xml:1.7 smarty/docs/en/programmers/caching/caching-setting-up.xml:1.8
--- smarty/docs/en/programmers/caching/caching-setting-up.xml:1.7	Thu May  4 19:22:07 2006
+++ smarty/docs/en/programmers/caching/caching-setting-up.xml	Wed Sep 27 00:54:40 2006
@@ -1,13 +1,14 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
   <sect1 id="caching.setting.up">
    <title>Setting Up Caching</title>
    <para>
     The first thing to do is enable caching by setting <link
-    linkend="variable.caching">$caching</link> = 1 (or 2).
+    linkend="variable.caching">
+    <parameter>$caching</parameter></link><literal> = 1 (or 2)</literal>.
    </para>
    <example>
-    <title>enabling caching</title>
+    <title>Enabling caching</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -22,34 +23,37 @@
     </programlisting>
    </example>
    <para>
-    With caching enabled, the function call to display('index.tpl') will render
+    With caching enabled, the function call to
+    <literal>display('index.tpl')</literal> will render
     the template as usual, but also saves a copy of its output to a file (a
-    cached copy) in the <link linkend="variable.cache.dir">$cache_dir</link>.
-    Upon the next call to display('index.tpl'), the cached copy will be used
-    instead of rendering the template again.
+    cached copy) in the
+    <link linkend="variable.cache.dir"><parameter>$cache_dir</parameter></link>.
+    On the next call to <literal>display('index.tpl')</literal>, the cached copy
+    will be used instead of rendering the template again.
    </para>
    <note>
     <title>Technical Note</title>
     <para>
      The files in the
-     <link linkend="variable.cache.dir">$cache_dir</link>
+     <link linkend="variable.cache.dir"><parameter>$cache_dir</parameter></link>
      are named similar to the template name.
-     Although they end in the ".php" extention, they are not intended to be
-     directly executable. Do not edit these files!
+     Although they end in the <filename>.php</filename> extention, they are not
+     intended to be directly executable. Do not edit these files!
     </para>
    </note>
    <para>
     Each cached page has a limited lifetime determined by <link
-    linkend="variable.cache.lifetime">$cache_lifetime</link>. The default value
-    is 3600 seconds, or 1 hour. After that time expires, the cache is
-    regenerated. It is possible to give individual caches their own expiration
-    time by setting
-    <link linkend="variable.caching">$caching</link> = 2.
+    linkend="variable.cache.lifetime"><parameter>$cache_lifetime</parameter></link>.
+    The default value is 3600 seconds ie an hour. After that time expires, the
+    cache is regenerated. It is possible to give individual caches their own
+    expiration time by setting
+    <link linkend="variable.caching"><parameter>$caching</parameter></link><literal>=2</literal>.
     See <link
-    linkend="variable.cache.lifetime">$cache_lifetime</link> for more details.
+    linkend="variable.cache.lifetime"><parameter>$cache_lifetime</parameter></link>
+    for more details.
    </para>
    <example>
-    <title>setting $cache_lifetime per cache</title>
+    <title>Setting $cache_lifetime per cache</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -77,16 +81,17 @@
     </programlisting>
    </example>
    <para>
-    If <link linkend="variable.compile.check">$compile_check</link> is enabled,
+    If <link linkend="variable.compile.check">
+    <parameter>$compile_check</parameter></link> is enabled,
     every template file and config file that is involved with the cache file is
     checked for modification. If any of the files have been modified since the
     cache was generated, the cache is immediately regenerated. This is a slight
     overhead so for optimum performance, set
-    <link linkend="variable.compile.check">$compile_check</link>
-    to false.
+    <link linkend="variable.compile.check"><parameter>$compile_check</parameter>
+    </link> to &false;.
    </para>
    <example>
-    <title>enabling $compile_check</title>
+    <title>Enabling $compile_check</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -102,25 +107,26 @@
     </programlisting>
    </example>
    <para>
-    If <link linkend="variable.force.compile">$force_compile</link> is enabled,
+    If <link linkend="variable.force.compile">
+    <parameter>$force_compile</parameter></link> is enabled,
     the cache files will always be regenerated. This effectively turns off
     caching.
-    <link linkend="variable.force.compile">$force_compile</link>
-    is usually for 
-    <link
-        linkend="chapter.debugging.console">debugging</link> 
-        purposes only, a more
-    efficient way of disabling caching is to set <link
-    linkend="variable.caching">$caching</link> = 0.
+    <link linkend="variable.force.compile"><parameter>$force_compile</parameter>
+    </link> is usually for
+    <link linkend="chapter.debugging.console">debugging</link>
+    purposes only, a more  efficient way of disabling caching is to set <link
+    linkend="variable.caching"><parameter>$caching</parameter>
+    </link><literal> = 0</literal>.
    </para>
    <para>
-    The <link linkend="api.is.cached">is_cached()</link> function
+    The <link linkend="api.is.cached"><varname>is_cached()</varname></link>
+    function
     can be used to test if a template has a valid cache or not. If you have a
     cached template that requires something like a database fetch, you can use
     this to skip that process.
    </para>
    <example>
-    <title>using is_cached()</title>
+    <title>Using is_cached()</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -142,25 +148,28 @@
    </example>
    <para>
     You can keep parts of a page dynamic with the <link
-    linkend="language.function.insert">{insert}</link> template function. Let's
+    linkend="language.function.insert"><varname>{insert}</varname></link>
+    template function. Let's
     say the whole page can be cached except for a banner that is displayed down
-    the right side of the page. By using an 
-    <link linkend="language.function.insert">{insert}</link> 
+    the side of the page. By using the
+    <link linkend="language.function.insert"><varname>{insert}</varname></link>
     function for the banner, you
     can keep this element dynamic within the cached content. See the
-    documentation on <link linkend="language.function.insert">{insert}</link> for
-    more details and examples.
+    documentation on
+    <link linkend="language.function.insert"><varname>{insert}</varname></link>
+    for more details and examples.
    </para>
    <para>
     You can clear all the cache files with the <link
-    linkend="api.clear.all.cache">clear_all_cache()</link> function, or
-    individual cache files 
-    <link linkend="caching.groups">(or groups)</link>
+    linkend="api.clear.all.cache"><varname>clear_all_cache()</varname></link>
+    function, or
+    individual cache files
+    <link linkend="caching.groups">and groups</link>
     with the <link
-    linkend="api.clear.cache">clear_cache()</link> function.
+    linkend="api.clear.cache"><varname>clear_cache()</varname></link> function.
    </para>
    <example>
-    <title>clearing the cache</title>
+    <title>Clearing the cache</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -169,12 +178,12 @@
 
 $smarty->caching = 1;
 
-// clear out all cache files
-$smarty->clear_all_cache();
-
 // clear only cache for index.tpl
 $smarty->clear_cache('index.tpl');
 
+// clear out all cache files
+$smarty->clear_all_cache();
+
 $smarty->display('index.tpl');
 ?>
 ]]>