diff --git a/docs/en/programmers/plugins/plugins-block-functions.xml b/docs/en/programmers/plugins/plugins-block-functions.xml
index 673314ff..4d626370 100644
--- a/docs/en/programmers/plugins/plugins-block-functions.xml
+++ b/docs/en/programmers/plugins/plugins-block-functions.xml
@@ -11,62 +11,64 @@
      </funcprototype>
     </funcsynopsis>
     <para>
-     Block functions are functions of the form: {func} .. {/func}. In other
-     words, they enclose a template block and operate on the contents of
-     this block. Block functions take precedence over custom functions of
-     the same name, that is, you cannot have both custom function {func} and
-     block function {func} .. {/func}.
+     Block functions are functions of the form:
+     <literal>{func} .. {/func}</literal>. In other words, they enclose a
+     template block and operate on the contents of
+     this block. Block functions take precedence over
+     <link linkend="language.custom.functions">custom functions</link> of
+     the same name, that is, you cannot have both custom function
+     <literal>{func}</literal> and block function
+     <literal>{func}..{/func}</literal>.
     </para>
-    <para>
+
+    <itemizedlist>
+    <listitem><para>
      By default your function implementation is called twice by
-     Smarty: once for the opening tag, and once for the closing tag
-     (see <literal>&amp;$repeat</literal> below how to change this).
-    </para>
-    <para>
-     Only the opening tag of the block function may have attributes. All
+     Smarty: once for the opening tag, and once for the closing tag.
+     (See <literal>$repeat</literal> below on how to change this.)
+    </para></listitem>
+    <listitem><para>
+     Only the opening tag of the block function may have
+     <link linkend="language.syntax.attributes">attributes</link>. All
      attributes passed to template functions from the template are contained
-     in the <parameter>$params</parameter> as an associative array. You can
-     access those values as e.g. <varname>$params['start']</varname>.
+     in the <parameter>$params</parameter> variable as an associative array.
      The opening tag attributes are also accessible to your function
      when processing the closing tag.
-    </para>
-    <para>
-     The value of <parameter>$content</parameter> variable depends on
+    </para></listitem>
+    <listitem><para>
+     The value of the <parameter>$content</parameter> variable depends on
      whether your function is called for the opening or closing tag. In case
-     of the opening tag, it will be <literal>null</literal>, and in case of
+     of the opening tag, it will be &null;, and in case of
      the closing tag it will be the contents of the template block.
      Note that the template block will have already been processed by
      Smarty, so all you will receive is the template output, not the
      template source.
-    </para>
+    </para></listitem>
 
-    <para>
-     The parameter <parameter>&amp;$repeat</parameter> is passed by
+    <listitem><para>
+     The parameter <parameter>$repeat</parameter> is passed by
      reference to the function implementation and provides a
      possibility for it to control how many times the block is
      displayed. By default <parameter>$repeat</parameter> is
-     <literal>true</literal> at the first call of the block-function
-     (the block opening tag) and <literal>false</literal> on all
-     subsequent calls to the block function (the block's closing tag).
+     &true; at the first call of the block-function (the opening tag)
+     and &false; on all subsequent calls to the block function
+     (the block's closing tag).
      Each time the function implementation returns with
-     <parameter>&amp;$repeat</parameter> being true, the contents between
-     {func} .. {/func} are evaluated and the function implementation
-     is called again with the new block contents in the parameter
+     <parameter>$repeat</parameter> being &true;, the contents between
+     <literal>{func}...{/func}</literal> are evaluated and the function
+     implementation is called again with the new block contents in the parameter
      <parameter>$content</parameter>.
-
-	</para>
+	</para></listitem>
+    </itemizedlist>
 
     <para>
      If you have nested block functions, it's possible to find out what the
      parent block function is by accessing
-     <varname>$smarty->_tag_stack</varname> variable. Just do a var_dump()
+     <literal>$smarty->_tag_stack</literal> variable. Just do a
+     <ulink url="&url.php-manual;var_dump"><varname>var_dump()</varname></ulink>
      on it and the structure should be apparent.
     </para>
-    <para>
-     See also:
-     <link linkend="api.register.block">register_block()</link>,
-     <link linkend="api.unregister.block">unregister_block()</link>.
-    </para>
+
     <example>
      <title>block function</title>
      <programlisting role="php">
@@ -83,16 +85,26 @@
  */
 function smarty_block_translate($params, $content, &$smarty, &$repeat)
 {
-    if (isset($content)) {
-        $lang = $params['lang'];
-        // do some intelligent translation thing here with $content
-        return $translation;
+    // only output on the closing tag
+    if(!$repeat){
+        if (isset($content)) {
+            $lang = $params['lang'];
+            // do some intelligent translation thing here with $content
+            return $translation;
+        }
     }
 }
 ?>
 ]]>
      </programlisting>
     </example>
+
+<para>
+ See also:
+ <link linkend="api.register.block"><varname>register_block()</varname></link>,
+ <link linkend="api.unregister.block"><varname>unregister_block()</varname></link>.
+</para>
+
    </sect1>
 
 <!-- Keep this comment at the end of the file
diff --git a/docs/en/programmers/plugins/plugins-compiler-functions.xml b/docs/en/programmers/plugins/plugins-compiler-functions.xml
index 17c390f7..475fca81 100644
--- a/docs/en/programmers/plugins/plugins-compiler-functions.xml
+++ b/docs/en/programmers/plugins/plugins-compiler-functions.xml
@@ -5,8 +5,8 @@
      Compiler functions are called only during compilation of the template.
      They are useful for injecting PHP code or time-sensitive static
      content into the template. If there is both a compiler function and a
-     custom function registered under the same name, the compiler function
-     has precedence.
+     <link linkend="language.custom.functions">custom function</link> registered
+      under the same name, the compiler function has precedence.
     </para>
     <funcsynopsis>
      <funcprototype>
@@ -21,13 +21,9 @@
      delimiter, and the Smarty object. It's supposed to return the PHP code
      to be injected into the compiled template.
     </para>
-    <para>
-     See also
-     <link linkend="api.register.compiler.function">register_compiler_function()</link>,
-     <link linkend="api.unregister.compiler.function">unregister_compiler_function()</link>.
-    </para>
+
     <example>
-     <title>simple compiler function</title>
+     <title>A simple compiler function</title>
      <programlisting role="php">
 <![CDATA[
 <?php
@@ -52,8 +48,10 @@ function smarty_compiler_tplheader($tag_arg, &$smarty)
       This function can be called from the template as:
      </para>
      <programlisting>
+<![CDATA[
 {* this function gets executed at compile time only *}
 {tplheader}
+]]>
      </programlisting>
      <para>
       The resulting PHP code in the compiled template would be something like this:
@@ -66,6 +64,15 @@ echo 'index.tpl compiled at 2002-02-20 20:02';
 ]]>
      </programlisting>
     </example>
+
+    <para>
+     See also
+     <link linkend="api.register.compiler.function">
+     <varname>register_compiler_function()</varname></link>,
+     <link linkend="api.unregister.compiler.function">
+     <varname>unregister_compiler_function()</varname></link>.
+    </para>
+
    </sect1>
 
 <!-- Keep this comment at the end of the file
diff --git a/docs/en/programmers/plugins/plugins-functions.xml b/docs/en/programmers/plugins/plugins-functions.xml
index b78717f7..acf46e41 100644
--- a/docs/en/programmers/plugins/plugins-functions.xml
+++ b/docs/en/programmers/plugins/plugins-functions.xml
@@ -9,26 +9,25 @@
      </funcprototype>
     </funcsynopsis>
     <para>
-     All attributes passed to template functions from the template are
-     contained in the <parameter>$params</parameter> as an associative
-     array.
+     All <link linkend="language.syntax.attributes">attributes</link> passed to
+     template functions from the template are contained in the
+     <parameter>$params</parameter> as an associative array.
     </para>
     <para>
-	 The output (return value) of the function will be substituted in place of the
-     function tag in the template (<function>fetch</function> function, for
-     example). Alternatively, the function can simply perform some other
-     task without any output (<function>assign</function> function).
+	 The output (return value) of the function will be substituted in place of
+     the function tag in the template, eg the
+     <link linkend="language.function.fetch"><varname>{fetch}</varname></link>
+     function. Alternatively, the function can simply perform some other
+     task without any output, eg the <link linkend="language.function.assign">
+     <varname>{assign}</varname></link> function.
     </para>
     <para>
      If the function needs to assign some variables to the template or use
      some other Smarty-provided functionality, it can use the supplied
-     <parameter>$smarty</parameter> object to do so.
-    </para>
-    <para>
-     See also:
-     <link linkend="api.register.function">register_function()</link>,
-     <link linkend="api.unregister.function">unregister_function()</link>.
+     <parameter>$smarty</parameter> object to do so eg
+     <literal>$smarty->foo()</literal>.
     </para>
+
     <para>
      <example>
       <title>function plugin with output</title>
@@ -101,6 +100,11 @@ function smarty_function_assign($params, &$smarty)
 ]]>
       </programlisting>
      </example>
+    </para>
+        <para>
+     See also:
+     <link linkend="api.register.function"><varname>register_function()</varname></link>,
+     <link linkend="api.unregister.function"><varname>unregister_function()</varname></link>.
     </para>
   </sect1>
 
diff --git a/docs/en/programmers/plugins/plugins-inserts.xml b/docs/en/programmers/plugins/plugins-inserts.xml
index 0f07c1e1..6f5f9cd8 100644
--- a/docs/en/programmers/plugins/plugins-inserts.xml
+++ b/docs/en/programmers/plugins/plugins-inserts.xml
@@ -3,7 +3,7 @@
    <sect1 id="plugins.inserts"><title>Inserts</title>
     <para>
      Insert plugins are used to implement functions that are invoked by
-     <link linkend="language.function.insert">{insert}</link>
+     <link linkend="language.function.insert"><varname>{insert}</varname></link>
      tags in the template.
     </para>
     <funcsynopsis>
@@ -19,7 +19,7 @@
     </para>
     <para>
      The insert function is supposed to return the result which will be
-     substituted in place of the <command>{insert}</command> tag in the
+     substituted in place of the <varname>{insert}</varname> tag in the
      template.
     </para>
     <example>
@@ -29,7 +29,7 @@
 <?php
 /*
  * Smarty plugin
- * ------------------------------------------------------------- 
+ * -------------------------------------------------------------
  * File:     insert.time.php
  * Type:     time
  * Name:     time
diff --git a/docs/en/programmers/plugins/plugins-modifiers.xml b/docs/en/programmers/plugins/plugins-modifiers.xml
index a482c513..deb3f87a 100644
--- a/docs/en/programmers/plugins/plugins-modifiers.xml
+++ b/docs/en/programmers/plugins/plugins-modifiers.xml
@@ -2,9 +2,9 @@
 <!-- $Revision$ -->
    <sect1 id="plugins.modifiers"><title>Modifiers</title>
     <para>
-     Modifiers are little functions that are applied to a variable in the
-     template before it is displayed or used in some other context.
-     Modifiers can be chained together.
+     <link linkend="language.modifiers">Modifiers</link> are little functions
+     that are applied to a variable in the template before it is displayed or
+     used in some other context. Modifiers can be chained together.
     </para>
     <funcsynopsis>
      <funcprototype>
@@ -15,20 +15,16 @@
     </funcsynopsis>
     <para>
      The first parameter to the modifier plugin is the value on which
-     the modifier is supposed to operate. The rest of the parameters can be
-     optional, depending on what kind of operation is supposed to be
-     performed.
+     the modifier is to operate. The rest of the parameters are optional,
+     depending on what kind of operation is to be  performed.
     </para>
     <para>
-     The modifier has to return the result of its processing.
-    </para>
-    <para>
-     See also
-     <link linkend="api.register.modifier">register_modifier()</link>,
-     <link linkend="api.unregister.modifier">unregister_modifier()</link>.
+     The modifier has to <ulink url="&url.php-manual;return">return</ulink>
+     the result of its processing.
     </para>
+
     <example>
-     <title>simple modifier plugin</title>
+     <title>A simple modifier plugin</title>
      <para>
       This plugin basically aliases one of the built-in PHP functions. It
       does not have any additional parameters.
@@ -55,7 +51,7 @@ function smarty_modifier_capitalize($string)
     </example>
     <para></para>
     <example>
-     <title>more complex modifier plugin</title>
+     <title>More complex modifier plugin</title>
      <programlisting role="php">
 <![CDATA[
 <?php
@@ -66,7 +62,7 @@ function smarty_modifier_capitalize($string)
  * Type:     modifier
  * Name:     truncate
  * Purpose:  Truncate a string to a certain length if necessary,
- *           optionally splitting in the middle of a word, and 
+ *           optionally splitting in the middle of a word, and
  *           appending the $etc string.
  * -------------------------------------------------------------
  */
@@ -91,6 +87,11 @@ function smarty_modifier_truncate($string, $length = 80, $etc = '...',
 ]]>
      </programlisting>
     </example>
+     <para>
+     See also
+     <link linkend="api.register.modifier"><varname>register_modifier()</varname></link>,
+     <link linkend="api.unregister.modifier"><varname>unregister_modifier()</varname></link>.
+    </para>
    </sect1>
 
 <!-- Keep this comment at the end of the file
diff --git a/docs/en/programmers/plugins/plugins-naming-conventions.xml b/docs/en/programmers/plugins/plugins-naming-conventions.xml
index a3ecc866..89e463e2 100644
--- a/docs/en/programmers/plugins/plugins-naming-conventions.xml
+++ b/docs/en/programmers/plugins/plugins-naming-conventions.xml
@@ -7,7 +7,7 @@
      convention in order to be located by Smarty.
     </para>
     <para>
-     The plugin files must be named as follows:
+     <emphasis role="bold">plugin files</emphasis> must be named as follows:
      <blockquote>
       <para>
        <filename>
@@ -16,7 +16,9 @@
       </para>
      </blockquote>
     </para>
-    <para>
+
+    <itemizedlist>
+    <listitem><para>
      Where <literal>type</literal> is one of these plugin types:
      <itemizedlist spacing="compact">
       <listitem><simpara>function</simpara></listitem>
@@ -30,27 +32,41 @@
       <listitem><simpara>insert</simpara></listitem>
      </itemizedlist>
     </para>
-    <para>
-     And <literal>name</literal> should be a valid identifier (letters,
-     numbers, and underscores only).
+    </listitem>
+
+    <listitem><para>
+     And <literal>name</literal> should be a valid identifier; letters,
+     numbers, and underscores only, see
+     <ulink url="&url.php-manual;language.variables">php variables</ulink>.
+    </para></listitem>
+
+    <listitem><para>
+     Some examples: <filename>function.html_select_date.php</filename>,
+     <filename>resource.db.php</filename>,
+     <filename>modifier.spacify.php</filename>.
     </para>
+    </listitem>
+    </itemizedlist>
+
+
     <para>
-     Some examples: <literal>function.html_select_date.php</literal>,
-     <literal>resource.db.php</literal>,
-     <literal>modifier.spacify.php</literal>.
-    </para>
-    <para>
-     The plugin functions inside the plugin files must be named as follows:
+     <emphasis role="bold">plugin functions</emphasis> inside the PHP files must be named as follows:
      <blockquote>
       <para>
        <function>smarty_<replaceable>type</replaceable>_<replaceable>name</replaceable></function>
       </para>
      </blockquote>
     </para>
-    <para>
+
+    <itemizedlist>
+     <listitem><para>
      The meanings of <literal>type</literal> and <literal>name</literal> are
-     the same as before.
-    </para>
+     the same as above.
+    </para></listitem>
+      <listitem><para>
+     An example modifier name <varname>foo</varname> would be <literal>function smarty_modifier_foo()</literal>.
+    </para></listitem>
+    </itemizedlist>
     <para>
      Smarty will output appropriate error messages if the plugin file it
      needs is not found, or if the file or the plugin function are named
diff --git a/docs/en/programmers/plugins/plugins-outputfilters.xml b/docs/en/programmers/plugins/plugins-outputfilters.xml
index 361c5e48..dd995701 100644
--- a/docs/en/programmers/plugins/plugins-outputfilters.xml
+++ b/docs/en/programmers/plugins/plugins-outputfilters.xml
@@ -19,7 +19,7 @@
      the processing and return the results.
     </para>
     <example>
-     <title>output filter plugin</title>
+     <title>An output filter plugin</title>
      <programlisting role="php">
 <![CDATA[
 <?php
@@ -29,7 +29,7 @@
  * File:     outputfilter.protect_email.php
  * Type:     outputfilter
  * Name:     protect_email
- * Purpose:  Converts @ sign in email addresses to %40 as 
+ * Purpose:  Converts @ sign in email addresses to %40 as
  *           a simple protection against spambots
  * -------------------------------------------------------------
  */
@@ -42,6 +42,13 @@
 ]]>
      </programlisting>
     </example>
+            <para>
+     See also
+     <link linkend="api.register.outputfilter">
+     <varname>register_outputfilter()</varname></link>,
+     <link linkend="api.unregister.outputfilter">
+     <varname>unregister_outputfilter()</varname></link>.
+     </para>
    </sect1>
 
 <!-- Keep this comment at the end of the file
diff --git a/docs/en/programmers/plugins/plugins-prefilters-postfilters.xml b/docs/en/programmers/plugins/plugins-prefilters-postfilters.xml
index 2bceb6c4..35dcaa3f 100644
--- a/docs/en/programmers/plugins/plugins-prefilters-postfilters.xml
+++ b/docs/en/programmers/plugins/plugins-prefilters-postfilters.xml
@@ -82,6 +82,17 @@
 ]]>
      </programlisting>
     </example>
+        <para>
+     See also
+     <link linkend="api.register.prefilter">
+     <varname>register_prefilter()</varname></link>,
+     <link linkend="api.unregister.prefilter">
+     <varname>unregister_prefilter()</varname></link>
+        <link linkend="api.register.postfilter">
+     <varname>register_postfilter()</varname></link>,
+     <link linkend="api.unregister.postfilter">
+     <varname>unregister_postfilter()</varname></link>.
+    </para>
    </sect1>
 
 <!-- Keep this comment at the end of the file
diff --git a/docs/en/programmers/plugins/plugins-resources.xml b/docs/en/programmers/plugins/plugins-resources.xml
index a40705b8..7cb415bf 100644
--- a/docs/en/programmers/plugins/plugins-resources.xml
+++ b/docs/en/programmers/plugins/plugins-resources.xml
@@ -8,7 +8,7 @@
     </para>
 
     <para>
-     There are a total of 4 functions that need to be registered for each
+     There are a total of four functions that need to be registered for each
      type of resource. Every function will receive the requested resource as
      the first parameter and the Smarty object as the last parameter. The
      rest of parameters depend on the function.
@@ -39,44 +39,44 @@
      </funcprototype>
     </funcsynopsis>
 
-    <para>
-     The first function is supposed to retrieve the resource. Its second
-     parameter is a variable passed by reference where the result should be
-     stored. The function is supposed to return <literal>true</literal> if
-     it was able to successfully retrieve the resource and
-     <literal>false</literal> otherwise.
-    </para>
+	<itemizedlist>
+	<listitem><para>
+     The first function, <literal>source()</literal> is supposed to retrieve
+     the resource. Its second parameter <parameter>$source</parameter> is a
+     variable passed by reference where the result should be
+     stored. The function is supposed to return &true; if
+     it was able to successfully retrieve the resource and &false; otherwise.
+    </para></listitem>
 
-    <para>
-     The second function is supposed to retrieve the last modification time
-     of the requested resource (as a UNIX timestamp). The second parameter
+    <listitem><para>
+     The second function, <literal>timestamp()</literal> is supposed to
+     retrieve the last modification time of the requested resource, as a UNIX
+     timestamp. The second parameter <parameter>$timestamp</parameter>
      is a variable passed by reference where the timestamp should be stored.
-     The function is supposed to return <literal>true</literal> if the
-     timestamp could be succesfully determined, and <literal>false</literal>
-     otherwise.
-    </para>
+     The function is supposed to return &true; if the timestamp could be
+     succesfully determined, or &false; otherwise.
+    </para></listitem>
 
-    <para>
-     The third function is supposed to return <literal>true</literal> or
-     <literal>false</literal>, depending on whether the requested resource
-     is secure or not. This function is used only for template resources but
+    <listitem><para>
+     The third function, <literal>secure()</literal>is supposed to return
+     &true; or &false;, depending on whether the requested resource is secure
+     or not. This function is used only for template resources but
      should still be defined.
-    </para>
+    </para></listitem>
 
-    <para>
-     The fourth function is supposed to return <literal>true</literal> or
-     <literal>false</literal>, depending on whether the requested resource
+    <listitem><para>
+     The fourth function, <literal>trusted()</literal> is supposed to return
+     &true; or &false;, depending on whether the requested resource
      is trusted or not. This function is used for only for PHP script
-     components requested by <command>include_php</command> tag or
-     <command>insert</command> tag with <structfield>src</structfield>
-     attribute. However, it should still be defined even for template
-     resources.
-    </para>
-    <para>
-     See also
-     <link linkend="api.register.resource">register_resource()</link>,
-     <link linkend="api.unregister.resource">unregister_resource()</link>.
-    </para>
+     components requested by <link linkend="language.function.include.php">
+     <varname>{include_php}</varname></link> tag or
+     <link linkend="language.function.insert"><varname>{insert}</varname></link>
+     tag with the <parameter>src</parameter> attribute. However, it should still
+     be defined even for template resources.
+    </para></listitem>
+    </itemizedlist>
+
+
     <example>
      <title>resource plugin</title>
      <programlisting role="php">
@@ -84,7 +84,7 @@
 <?php
 /*
  * Smarty plugin
- * ------------------------------------------------------------- 
+ * -------------------------------------------------------------
  * File:     resource.db.php
  * Type:     resource
  * Name:     db
@@ -136,6 +136,13 @@ function smarty_resource_db_trusted($tpl_name, &$smarty)
 ]]>
      </programlisting>
     </example>
+
+ <para>
+ See also
+ <link linkend="api.register.resource"><varname>register_resource()</varname></link>,
+ <link linkend="api.unregister.resource"><varname>unregister_resource()</varname></link>.
+</para>
+
    </sect1>
 
 <!-- Keep this comment at the end of the file
diff --git a/docs/en/programmers/plugins/plugins-writing.xml b/docs/en/programmers/plugins/plugins-writing.xml
index d20a9317..b639944b 100644
--- a/docs/en/programmers/plugins/plugins-writing.xml
+++ b/docs/en/programmers/plugins/plugins-writing.xml
@@ -26,11 +26,19 @@ require_once $smarty->_get_plugin_filepath('function', 'html_options');
     </programlisting>
     <para>
      As a general rule, Smarty object is always passed to the plugins
-     as the last parameter (with two exceptions: modifiers do not get
-     passed the Smarty object at all and blocks get passed
-     <parameter>&amp;$repeat</parameter> after the Smarty object to keep
-     backwards compatibility to older versions of Smarty).
-    </para>
+     as the last parameter with two exceptions:
+     </para>
+     <itemizedlist>
+     <listitem><para>
+     modifiers do not get passed the Smarty object at all
+     </para></listitem>
+     <listitem><para>
+     blocks get passed
+     <parameter>$repeat</parameter> after the Smarty object to keep
+     backwards compatibility to older versions of Smarty.
+     </para></listitem>
+     </itemizedlist>
+
    </sect1>
 
 <!-- Keep this comment at the end of the file