diff --git a/docs/en/designers/language-builtin-functions/language-function-capture.xml b/docs/en/designers/language-builtin-functions/language-function-capture.xml
index e463e717..a242c553 100644
--- a/docs/en/designers/language-builtin-functions/language-function-capture.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-capture.xml
@@ -2,23 +2,24 @@
 <!-- $Revision$ -->
 <sect1 id="language.function.capture">
  <title>{capture}</title>
- 
+
   <para>
-   {capture} is used to collect the output of the template between the tags into a
-   variable instead of displaying it. Any content between {capture
-   name='foo'} and {/capture} is collected into the variable specified
-   in the name attribute. 
+   <varname>{capture}</varname> is used to collect the output of the template between the
+   tags into a  variable instead of displaying it. Any content between
+   <varname>{capture name='foo'}</varname> and <varname>{/capture}</varname> is collected
+   into the variable specified  in the <parameter>name</parameter> attribute.
    </para>
    <para>The captured content can be used in the
    template from the variable <link
-    linkend="language.variables.smarty.capture">$smarty.capture.foo</link>
-   where "foo" is the value passed in the name attribute. If you do not
-   supply a name attribute, then "default" will be used as the name 
-   ie $smarty.capture.default </para>
-   <para>{capture}'s can be nested.
- </para>
- 
- 
+    linkend="language.variables.smarty.capture"><parameter>$smarty.capture.foo</parameter></link>
+   where <quote>foo</quote> is the value passed in the <parameter>name</parameter> attribute.
+   If you do not supply the <parameter>name</parameter> attribute, then <quote>default</quote> will
+   be used as the name ie <parameter>$smarty.capture.default</parameter>.
+   </para>
+   <para><varname>{capture}'s</varname> can be nested.
+   </para>
+
+
  <informaltable frame="all">
   <tgroup cols="5">
    <colspec colname="param" align="center" />
@@ -58,11 +59,11 @@
  <caution>
   <para>
    Be careful when capturing <link
-   linkend="language.function.insert">{insert}</link>
+   linkend="language.function.insert"><varname>{insert}</varname></link>
    output. If you have
-   <link linkend="caching">$caching</link>
+   <link linkend="caching"><parameter>$caching</parameter></link>
    enabled and you have
-   <link linkend="language.function.insert">{insert}</link>
+   <link linkend="language.function.insert"><varname>{insert}</varname></link>
    commands that you expect to run
    within cached content, do not capture this content.
   </para>
@@ -83,11 +84,11 @@
 ]]>
    </programlisting>
   </example>
-  
+
     <example>
      <title>{capture} into a template variable</title>
-     <para>This example also demonstrates the 
-     <link linkend="language.function.popup">{popup}</link> 
+     <para>This example also demonstrates the
+     <link linkend="language.function.popup"><varname>{popup}</varname></link>
      function</para>
      <programlisting>
 <![CDATA[
@@ -99,17 +100,17 @@ Your ip is {$smarty.server.REMOTE_ADDR}.
 ]]>
      </programlisting>
   </example>
-  
-  
+
+
  </para>
  <para>
   See also
   <link
-   linkend="language.variables.smarty.capture">$smarty.capture</link>,
-   <link linkend="language.function.eval">{eval}</link>,
-  <link linkend="language.function.fetch">{fetch}</link>,
-  <link linkend="api.fetch">fetch()</link>
-  and <link linkend="language.function.assign">{assign}</link>.
+   linkend="language.variables.smarty.capture"><parameter>$smarty.capture</parameter></link>,
+   <link linkend="language.function.eval"><varname>{eval}</varname></link>,
+  <link linkend="language.function.fetch"><varname>{fetch}</varname></link>,
+  <link linkend="api.fetch"><varname>fetch()</varname></link>
+  and <link linkend="language.function.assign"><varname>{assign}</varname></link>.
  </para>
 </sect1>
 
diff --git a/docs/en/designers/language-builtin-functions/language-function-config-load.xml b/docs/en/designers/language-builtin-functions/language-function-config-load.xml
index 1ec978cb..37d50c44 100644
--- a/docs/en/designers/language-builtin-functions/language-function-config-load.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-config-load.xml
@@ -3,11 +3,11 @@
 <sect1 id="language.function.config.load">
  <title>{config_load}</title>
   <para>
-   {config_load} is used for loading  config
-   <link linkend="language.config.variables">#variables#</link> from a
-   <link linkend="config.files">configuration file</link> into the template.
+   <varname>{config_load}</varname> is used for loading  config
+   <link linkend="language.config.variables"><parameter>#variables#</parameter></link>
+   from a <link linkend="config.files">configuration file</link> into the template.
  </para>
- 
+
  <informaltable frame="all">
   <tgroup cols="5">
    <colspec colname="param" align="center" />
@@ -73,7 +73,7 @@
  <example>
   <title>{config_load}</title>
   <para>
-   example.conf
+   The <filename>example.conf</filename> file.
   </para>
   <programlisting>
 <![CDATA[
@@ -114,15 +114,14 @@ pageTitle = "Customer Info"
   <link linkend="config.files">Config Files</link>
   may also contain sections. You can load variables from
   within a section with the added attribute
-  <emphasis>'section'</emphasis>.
+  <parameter>section</parameter>.
  </para>
  <note>
   <para>
-   <emphasis>Config file sections</emphasis> and the built-in
+   Config file <emphasis>sections</emphasis> and the built-in
    template function called
-   <link linkend="language.function.section"><emphasis>{section}</emphasis></link>
-   have nothing
-   to do with each other, they just happen to share a common naming
+   <link linkend="language.function.section"><varname>{section}</varname></link>
+   have nothing  to do with each other, they just happen to share a common naming
    convention.
   </para>
  </note>
@@ -149,16 +148,17 @@ pageTitle = "Customer Info"
  </example>
 
 <para>
-See <link linkend="variable.config.overwrite">$config_overwrite</link> for arrays of config variables
+See <link linkend="variable.config.overwrite"><parameter>$config_overwrite</parameter></link>
+to create arrays of config file variables.
 </para>
 
  <para>
-  See also <link linkend="config.files">Config files</link>,
-  <link linkend="language.config.variables">Config variables</link>,
-  <link linkend="variable.config.dir">$config_dir</link>,
-  <link linkend="api.get.config.vars">get_config_vars()</link>
+  See also the <link linkend="config.files">config files</link> page,
+  <link linkend="language.config.variables">config variables</link> page,
+  <link linkend="variable.config.dir"><parameter>$config_dir</parameter></link>,
+  <link linkend="api.get.config.vars"><varname>get_config_vars()</varname></link>
   and
-  <link linkend="api.config.load">config_load()</link>.
+  <link linkend="api.config.load"><varname>config_load()</varname></link>.
  </para>
 </sect1>
 
diff --git a/docs/en/designers/language-builtin-functions/language-function-foreach.xml b/docs/en/designers/language-builtin-functions/language-function-foreach.xml
index 7f3dfd86..4b002e23 100644
--- a/docs/en/designers/language-builtin-functions/language-function-foreach.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-foreach.xml
@@ -80,7 +80,7 @@
 
    <listitem><para>
    <varname>{foreach}</varname> loops can be nested, and the nested
-   <varname>{foreach}</varname> names MUST be unique from each other.
+   <varname>{foreach}</varname> names must be unique from each other.
    </para></listitem>
 
    <listitem><para>
@@ -95,10 +95,11 @@
 
   <listitem><para>
 	  <varname>{foreach}</varname> loops also have their own variables that handle properties.
-	  These are accessible as:
+	  These are accessed with:
 	  <link linkend="language.variables.smarty.loops">
 	  <parameter>{$smarty.foreach.name.property}</parameter></link> with
-	  <quote>name</quote> being the  <parameter>name</parameter> attribute.
+	  <quote>name</quote> being the
+	  <parameter>name</parameter> attribute.
 	 </para>
 	 <note>
 	 <title>Note</title>
@@ -168,7 +169,7 @@ $smarty->assign('myArray', $arr);
 ]]>
   </programlisting>
    <para>Template to output <parameter>$myArray</parameter> as key/val pair,
-   like PHP's <ulink url="&url.php-manual;foreach">foreach</ulink>.</para>
+   like PHP's <ulink url="&url.php-manual;foreach"><varname>foreach</varname></ulink>.</para>
   <programlisting>
 <![CDATA[
 <ul>
@@ -425,8 +426,8 @@ $smarty->assign('items', $items_list);
   </example>
 
   <para>
-   See also <link linkend="language.function.section">{section}</link> and
-   <link linkend="language.variables.smarty.loops">$smarty.foreach</link>.
+   See also <link linkend="language.function.section"><varname>{section}</varname></link>
+   and  <link linkend="language.variables.smarty.loops"><parameter>$smarty.foreach</parameter></link>.
   </para>
  </sect2>
 </sect1>
diff --git a/docs/en/designers/language-builtin-functions/language-function-if.xml b/docs/en/designers/language-builtin-functions/language-function-if.xml
index da7d0b29..c5a74000 100644
--- a/docs/en/designers/language-builtin-functions/language-function-if.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-if.xml
@@ -3,21 +3,21 @@
 <sect1 id="language.function.if">
  <title>{if},{elseif},{else}</title>
  <para>
-  <emphasis>{if}</emphasis> statements in Smarty have much the same flexibility as PHP
-  <ulink url="&url.php-manual;if"><command>if</command></ulink>
+  <varname>{if}</varname> statements in Smarty have much the same flexibility as PHP
+  <ulink url="&url.php-manual;if">if</ulink>
   statements, with a few added features for the template engine.
-  Every <emphasis>{if}</emphasis> must be paired with an
-  <emphasis>{/if}</emphasis>. <emphasis>{else}</emphasis> and
-  <emphasis>{elseif}</emphasis> are also permitted. All PHP conditionals
-  and functions 
+  Every <varname>{if}</varname> must be paired with a matching
+  <varname>{/if}</varname>. <varname>{else}</varname> and
+  <varname>{elseif}</varname> are also permitted. All PHP conditionals
+  and functions
   are recognized, such as <emphasis>||</emphasis>, <emphasis>or</emphasis>,
-  <emphasis>&amp;&amp;</emphasis>, <emphasis>and</emphasis>, 
+  <emphasis>&amp;&amp;</emphasis>, <emphasis>and</emphasis>,
   <emphasis>is_array()</emphasis>, etc.
  </para>
  <para>
-  If <link linkend="variable.security">$security</link> is enabled
+  If <link linkend="variable.security"><parameter>$security</parameter></link> is enabled
   then <emphasis>IF_FUNCS</emphasis> array in the <link
-  linkend="variable.security.settings">$security_settings</link> array.
+  linkend="variable.security.settings"><parameter>$security_settings</parameter></link> array.
  </para>
  <para>
   The following is a list of recognized qualifiers, which must be
@@ -221,8 +221,8 @@
 ]]>
   </programlisting>
  </example>
- 
- 
+
+
  <example>
    <title>{if} with more examples</title>
 <programlisting>
@@ -239,7 +239,7 @@
   ]]>
 </programlisting>
  </example>
- 
+
 </sect1>
 <!-- Keep this comment at the end of the file
      Local variables:
diff --git a/docs/en/designers/language-builtin-functions/language-function-include-php.xml b/docs/en/designers/language-builtin-functions/language-function-include-php.xml
index f3c8bd4d..0acef7d7 100644
--- a/docs/en/designers/language-builtin-functions/language-function-include-php.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-include-php.xml
@@ -5,18 +5,18 @@
   <note>
    <title>Technical Note</title>
    <para>
-    {include_php} is pretty much deprecated from Smarty, you can
+    <varname>{include_php}</varname> is pretty much deprecated from Smarty, you can
     accomplish the same functionality via a custom template function.
-    The only reason to use {include_php} is if you really have a need to
+    The only reason to use <varname>{include_php}</varname> is if you really have a need to
     quarantine the php function away from the
-    <link linkend="variable.plugins.dir">plugins</link>
+    <link linkend="variable.plugins.dir"><filename>plugins/</filename></link>
     directory or your
     application code. See the <link
     linkend="tips.componentized.templates">componentized template
     example</link> for details.
    </para>
  </note>
- 
+
  <informaltable frame="all">
   <tgroup cols="5">
    <colspec colname="param" align="center" />
@@ -45,7 +45,7 @@
      <entry>once</entry>
      <entry>boolean</entry>
      <entry>No</entry>
-     <entry><emphasis>true</emphasis></entry>
+     <entry><emphasis>&true;</emphasis></entry>
      <entry>whether or not to include the php file more than
       once if included multiple times</entry>
     </row>
@@ -62,36 +62,35 @@
  </informaltable>
 
  <para>
-  {include_php} tags are used to include a php script in your template.
-  If <link linkend="variable.security">$security</link> is enabled,
+  <varname>{include_php}</varname> tags are used to include a php script in your template.
+  If <link linkend="variable.security"><parameter>$security</parameter></link> is enabled,
   then the php script must be located in the <link
-  linkend="variable.trusted.dir">$trusted_dir</link> path.
-  The {include_php} tag must have the attribute
-  "file", which contains the path to the included php file, either
-  relative to
-  <link linkend="variable.trusted.dir">$trusted_dir</link>,
+  linkend="variable.trusted.dir"><parameter>$trusted_dir</parameter></link> path.
+  The <varname>{include_php}</varname> tag must have the attribute
+  <parameter>file</parameter>, which contains the path to the included php file, either
+  relative to  <link linkend="variable.trusted.dir"><parameter>$trusted_dir</parameter></link>,
   or an absolute path.
  </para>
  <para>
   By default, php files are only included once even if called
   multiple times in the template. You can specify that it should be
-  included every time with the <emphasis>once</emphasis> attribute.
-  Setting once to false will include the php script each time it is
+  included every time with the <parameter>once</parameter> attribute.
+  Setting once to &false; will include the php script each time it is
   included in the template.
  </para>
  <para>
-  You can optionally pass the <emphasis>assign</emphasis> attribute,
+  You can optionally pass the <parameter>assign</parameter> attribute,
   which will specify a template variable name that the output of
-  <emphasis>{include_php}</emphasis> will be assigned to instead of
+  <varname>{include_php}</varname> will be assigned to instead of
   displayed.
  </para>
  <para>
-  The smarty object is available as $this within the PHP script that you
-  include.
+  The smarty object is available as <parameter>$this</parameter> within
+  the PHP script that you include.
  </para>
  <example>
   <title>function {include_php}</title>
-  <para>load_nav.php</para>
+  <para>The <filename>load_nav.php</filename> template.</para>
   <programlisting role="php">
 <![CDATA[
 <?php
@@ -106,26 +105,25 @@ $this->assign('sections',$sql->record);
 ]]>
   </programlisting>
   <para>
-   Where index.tpl is:
+   Where the teamplate is:
   </para>
   <programlisting>
 <![CDATA[
 {* absolute path, or relative to $trusted_dir *}
 {include_php file='/path/to/load_nav.php'}
 
-{foreach item="curr_section" from=$sections}
+{foreach item='curr_section' from=$sections}
   <a href="{$curr_section.url}">{$curr_section.name}</a><br />
 {/foreach}
 ]]>
   </programlisting>
  </example>
  <para>
-  See also <link linkend="language.function.include">{include}</link>,
-  <link linkend="language.function.php">{php}</link>, <link
-  linkend="language.function.capture">{capture}</link>, <link
-  linkend="template.resources">Template Resources</link> and <link
-  linkend="tips.componentized.templates">Componentized
-  Templates</link> </para>
+  See also <link linkend="language.function.include"><varname>{include}</varname></link>,
+  <link linkend="language.function.php"><varname>{php}</varname></link>, <link
+  linkend="language.function.capture"><varname>{capture}</varname></link>, <link
+  linkend="template.resources">template resources</link> and <link
+  linkend="tips.componentized.templates">componentized templates</link> </para>
 </sect1>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/docs/en/designers/language-builtin-functions/language-function-include.xml b/docs/en/designers/language-builtin-functions/language-function-include.xml
index 19207061..7407790d 100644
--- a/docs/en/designers/language-builtin-functions/language-function-include.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-include.xml
@@ -3,25 +3,50 @@
 <sect1 id="language.function.include">
  <title>{include}</title>
  <para>
-  {include} tags are used for including other templates in the current
+  <varname>{include}</varname> tags are used for including other templates in the current
   template. Any variables available in the current template are also
-  available within the included template. The {include} tag must have
-  the attribute <emphasis>'file'</emphasis>, 
+  available within the included template.
+  </para>
+
+  <itemizedlist>
+  <listitem><para>
+  The <varname>{include}</varname> tag must have
+  the  <parameter>file</parameter> attribute
   which contains the template resource path.
- </para>
- <para>
-  You can optionally pass the <emphasis>'assign'</emphasis> attribute,
-  which will specify a template variable name that the output of
-  {include} will be assigned to instead of
-  displayed.
- </para>
- <para>
-  All assigned variables' values are restored after the scope of the
+  </para></listitem>
+
+ <listitem><para>
+  Setting the optional <parameter>assign</parameter> attribute
+   specifies the template variable that the output of
+  <varname>{include}</varname> is assigned to, instead of being displayed. Similar to
+  <link linkend="language.function.assign"><varname>{assign}</varname></link>.
+ </para></listitem>
+
+ <listitem><para>
+  Variables can be passed to included templates as
+  <link linkend="language.syntax.attributes">attributes</link>.
+  Any variables explicitly passed to an included template
+   are only available within the scope of the included
+  file. Attribute variables override current template variables, in
+  the case when they are named the same.
+ </para></listitem>
+
+  <listitem><para>
+  All assigned variable values are restored after the scope of the
   included template is left. This means you can use all variables from
   the including template inside the included template. But changes to
   variables inside the included template are not visible inside the
-  including template after the {include} statement.
- </para>
+  including template after the <varname>{include}</varname> statement.
+  </para></listitem>
+
+  <listitem><para>
+  Use the syntax for <link
+  linkend="template.resources">template resources</link> to
+  <varname>{include}</varname> files outside of the
+  <link linkend="variable.template.dir"><parameter>$template_dir</parameter></link>  directory.
+  </para></listitem>
+ </itemizedlist>
+
  <informaltable frame="all">
   <tgroup cols="5">
    <colspec colname="param" align="center" />
@@ -66,7 +91,7 @@
  </informaltable>
 
  <example>
-  <title>function {include}</title>
+  <title>Simple {include} example</title>
   <programlisting>
 <![CDATA[
 <html>
@@ -76,8 +101,10 @@
 <body>
 {include file='page_header.tpl'}
 
-{* body of template goes here *}
-{include file="$tpl_name.tpl"} <-- will replace $tpl_name with value
+{* body of template goes here, the $tpl_name variable
+   is replaced with a value eg 'contact.tpl'
+*}
+{include file="$tpl_name.tpl"}
 
 {include file='page_footer.tpl'}
 </body>
@@ -85,33 +112,27 @@
 ]]>
   </programlisting>
  </example>
- <para>
-  You can also pass variables to included templates as 
-  <link linkend="language.syntax.attributes">attributes</link>.
-  Any variables explicitly passed to an included template as
-  attributes are only available within the scope of the included
-  file. Attribute variables override current template variables, in
-  the case they are named alike.
- </para>
+
  <example>
   <title>{include} passing variables</title>
   <programlisting>
 <![CDATA[
-{include file='header.tpl' title='Main Menu' table_bgcolor='#c0c0c0'}
-
+{include file='links.tpl' title='Newest links' links=$link_array}
 {* body of template goes here *}
-
-{include file='footer.tpl' logo='http://my.example.com/logo.gif'}
+{include file='footer.tpl' foo='bar'}
 ]]>
   </programlisting>
-  <para>where header.tpl could be</para>
+  <para>The template above includes the example <filename>links.tpl</filename> below</para>
 <programlisting>
 <![CDATA[
-<table border='1' width='100%' bgcolor='{$table_bgcolor|default:"#0000FF"}'>
-  <tr><td>
-    <h1>{$title}</h1>
-  </td></tr>
-</table>
+<div id="box">
+<h3>{$title}{/h3>
+<ul>
+{foreach from=$links item=l}
+.. do stuff  ...
+</foreach}
+</ul>
+</div>
 ]]>
 </programlisting>
  </example>
@@ -119,34 +140,26 @@
 
   <example>
    <title>{include} and assign to variable</title>
-   <para>This example assigns the contents of nav.tpl to the $navbar variable,
-   which is then output at the top and bottom of the page.
+   <para>This example assigns the contents of <filename>nav.tpl</filename>
+    to the <varname>$navbar</varname> variable,
+   which is then output at both the top and bottom of the page.
    </para>
    <programlisting>
  <![CDATA[
 <body>
-{include file='nav.tpl' assign=navbar}
-{include file='header.tpl' title='Main Menu' table_bgcolor='#effeef'}
-{$navbar}
-
-{* body of template goes here *}
-
-{include file='footer.tpl' logo='http://my.example.com/logo.gif'}
-{$navbar}
+  {include file='nav.tpl' assign=navbar}
+  {include file='header.tpl' title='Smarty is cool'}
+    {$navbar}
+    {* body of template goes here *}
+    {$navbar}
+  {include file='footer.tpl'}
 </body>
 ]]>
    </programlisting>
  </example>
 
-
- <para>
-  Use the syntax for <link
-  linkend="template.resources">template resources</link> to
-  include files outside of the <link linkend="variable.template.dir">$template_dir</link>
-  directory.
- </para>
  <example>
-  <title>{include} template resource examples</title>
+  <title>Various {include} resource examples</title>
   <programlisting>
 <![CDATA[
 {* absolute filepath *}
@@ -162,20 +175,23 @@
 {include file='db:header.tpl'}
 
 {* include a $variable template - eg $module = 'contacts' *}
-{include file="$module.tpl"} 
+{include file="$module.tpl"}
+
 {* wont work as its single quotes ie no variable substitution *}
 {include file='$module.tpl'}
 
+{* include a multi $variable template - eg amber/links.view.tpl *}
+{include file="$style_dir/$module.$view.tpl"}
 ]]>
   </programlisting>
  </example>
  <para>
   See also
-  <link linkend="language.function.include.php">{include_php}</link>,
-  <link linkend="language.function.insert">{insert}</link>,
-  <link linkend="language.function.php">{php}</link>,
-  <link linkend="template.resources">Template Resources</link> and
-  <link linkend="tips.componentized.templates">Componentized Templates</link>.
+  <link linkend="language.function.include.php"><varname>{include_php}</varname></link>,
+  <link linkend="language.function.insert"><varname>{insert}</varname></link>,
+  <link linkend="language.function.php"><varname>{php}</varname></link>,
+  <link linkend="template.resources">template resources</link> and
+  <link linkend="tips.componentized.templates">componentized templates</link>.
  </para>
 </sect1>
 <!-- Keep this comment at the end of the file
diff --git a/docs/en/designers/language-builtin-functions/language-function-insert.xml b/docs/en/designers/language-builtin-functions/language-function-insert.xml
index cad27e5c..9123ab0c 100644
--- a/docs/en/designers/language-builtin-functions/language-function-insert.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-insert.xml
@@ -3,13 +3,13 @@
 <sect1 id="language.function.insert">
  <title>{insert}</title>
   <para>
-   {insert} tags work much like <link
-   linkend="language.function.include">{include}</link> tags,
-   except that {insert} tags are NOT cached when 
+   <varname>{insert}</varname> tags work much like <link
+   linkend="language.function.include"><varname>{include}</varname></link> tags,
+   except that <varname>{insert}</varname> tags are NOT cached when
    template <link linkend="caching">caching</link> is enabled. They
    will be executed on every invocation of the template.
  </para>
- 
+
  <informaltable frame="all">
   <tgroup cols="5">
    <colspec colname="param" align="center" />
@@ -80,7 +80,7 @@
 </programlisting>
  </example>
  <para>
-  In this example, we are using the name "getBanner" and passing the
+  In this example, we are using the name <quote>getBanner</quote> and passing the
   parameters #banner_location_id# and #site_id#. Smarty will look
   for a function named insert_getBanner() in your PHP application, passing
   the values of #banner_location_id# and #site_id# as the first argument
@@ -93,34 +93,46 @@
   insert_getBanner(array("lid" => "12345","sid" => "67890"));
    and display the returned results in place of the {insert} tag.
   </para>
-  <para>
-   If you supply the "assign" attribute, the output of the {insert} tag
+  <itemizedlist>
+  <listitem><para>
+   If you supply the <parameter>assign</parameter> attribute,
+   the output of the <varname>{insert}</varname> tag
    will be assigned to this template variable instead of being output
-   to the template. NOTE: assigning the output to a template variable
-   isn't too useful with
+   to the template.
+   <note>
+   <para>
+    Assigning the output to a template variable isn't too useful with
    <link linkend="variable.caching">caching</link> enabled.
-  </para>
-  <para>
-   If you supply the "script" attribute, this php script will be
-   included (only once) before the {insert} function is executed. This
+   </para>
+  </note>
+  </para></listitem>
+
+  <listitem><para>
+   If you supply the <parameter>script</parameter> attribute,
+   this php script will be
+   included (only once) before the <varname>{insert}</varname> function is executed. This
    is the case where the insert function may not exist yet, and a php
-   script must be included first to make it work. The path can be
+   script must be included first to make it work.
+   </para>
+   <para>
+   The path can be
    either absolute, or relative to
-   <link linkend="variable.trusted.dir">$trusted_dir</link>. When <link
-   linkend="variable.security">$security</link> is enabled, the script
-   must reside in <link linkend="variable.trusted.dir">$trusted_dir</link>.
-  </para>
+   <link linkend="variable.trusted.dir"><parameter>$trusted_dir</parameter></link>. When <link
+   linkend="variable.security"><parameter>$security</parameter></link> is enabled, the script
+   must reside in <link linkend="variable.trusted.dir"><parameter>$trusted_dir</parameter></link>.
+  </para></listitem>
+  </itemizedlist>
   <para>
    The Smarty object is passed as the second argument. This way you
    can reference and modify information in the Smarty object from
-   within the {insert} function.
+   within the <varname>{insert}</varname> function.
   </para>
   <note>
    <title>Technical Note</title>
    <para>
     It is possible to have portions of the template not
     cached. If you have <link linkend="caching">caching</link>
-    turned on, {insert} tags will not be cached. They will run
+    turned on, <varname>{insert}</varname> tags will not be cached. They will run
     dynamically every time the page is created, even within cached
     pages. This works good for things like banners, polls, live
     weather, search results, user feedback areas, etc.
@@ -128,7 +140,7 @@
   </note>
    <para>
     See also
-  <link linkend="language.function.include">{include}</link>
+  <link linkend="language.function.include"><varname>{include}</varname></link>
   </para>
  </sect1>
  <!-- Keep this comment at the end of the file
diff --git a/docs/en/designers/language-builtin-functions/language-function-ldelim.xml b/docs/en/designers/language-builtin-functions/language-function-ldelim.xml
index 827141be..8026e5e8 100644
--- a/docs/en/designers/language-builtin-functions/language-function-ldelim.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-ldelim.xml
@@ -3,14 +3,14 @@
  <sect1 id="language.function.ldelim">
   <title>{ldelim},{rdelim}</title>
   <para>
-   {ldelim} and {rdelim} are used for
+   <varname>{ldelim}</varname> and <varname>{rdelim}</varname> are used for
    <link linkend="language.escaping">escaping</link>
    template delimiters, by default
-   "{" and "}". You can also use <link
-    linkend="language.function.literal">{literal}{/literal}</link> to escape
-   blocks of text eg Javascript or css.
-    See also <link
-    linkend="language.variables.smarty.ldelim">{$smarty.ldelim}</link>.
+   <emphasis role="bold">{</emphasis> and <emphasis role="bold">}</emphasis>.
+   You can also use <link linkend="language.function.literal"><varname>{literal}{/literal}</varname></link>
+   to escape blocks of text eg Javascript or CSS.
+    See also the complimentary <link
+    linkend="language.variables.smarty.ldelim"><parameter>{$smarty.ldelim}</parameter></link>.
   </para>
   <example>
    <title>{ldelim}, {rdelim}</title>
@@ -29,7 +29,7 @@
 {funcname} is how functions look in Smarty!
 ]]>
    </screen>
-   <para>Another example with some javascript</para>
+   <para>Another example with some Javascript</para>
    <programlisting>
 <![CDATA[
 <script language="JavaScript">
@@ -53,9 +53,9 @@ function foo() {
    </screen>
 
   </example>
-  
+
   <example>
-     <title>another Javascript example</title>
+     <title>Another Javascript example</title>
 <programlisting>
 <![CDATA[
 <script language="JavaScript" type="text/javascript">
@@ -67,11 +67,10 @@ function foo() {
 ]]>
 </programlisting>
  </example>
- 
-  <para>See also 
-  <link linkend="language.function.literal">{literal}</link>
-  and
-  <link linkend="language.escaping">Escaping Smarty Parsing</link> 
+
+  <para>See also
+  <link linkend="language.function.literal"><varname>{literal}</varname></link>
+  and <link linkend="language.escaping">escaping Smarty parsing</link>.
   </para>
  </sect1>
 
diff --git a/docs/en/designers/language-builtin-functions/language-function-literal.xml b/docs/en/designers/language-builtin-functions/language-function-literal.xml
index 848b5417..f24eae6a 100644
--- a/docs/en/designers/language-builtin-functions/language-function-literal.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-literal.xml
@@ -3,17 +3,17 @@
 <sect1 id="language.function.literal">
  <title>{literal}</title>
  <para>
-  {literal} tags allow a block of data to be taken literally. This is typically
-  used around javascript or stylesheet blocks where curly braces would
+  <varname>{literal}</varname> tags allow a block of data to be taken literally. This is typically
+  used around Javascript or stylesheet blocks where {curly braces} would
   interfere with the template
   <link linkend="variable.left.delimiter">delimiter</link>
   syntax. Anything within
-  {literal}{/literal} tags is not interpreted, but displayed as-is. If you
-  need template tags embedded in your {literal} block, consider using <link
-  linkend="language.function.ldelim">{ldelim}{rdelim}</link> to escape the
+  <varname>{literal}{/literal}</varname> tags is not interpreted, but displayed as-is.
+  If you  need template tags embedded in a <varname>{literal}</varname> block, consider using
+  <link linkend="language.function.ldelim"><varname>{ldelim}{rdelim}</varname></link> to escape the
   individual delimiters instead.
  </para>
- 
+
  <example>
   <title>{literal} tags</title>
   <programlisting>
@@ -36,7 +36,7 @@
 ]]>
   </programlisting>
  </example>
- 
+
  <example>
    <title>Javascript function example</title>
    <programlisting>
@@ -54,7 +54,7 @@ function myJsFunction(name, ip){
  </example>
 
  <example>
-  <title>Some css in a template</title>
+  <title>Some css style in a template</title>
   <programlisting>
 <![CDATA[
 {* included this style .. as an experiment *}
@@ -68,16 +68,16 @@ function myJsFunction(name, ip){
 }
 {/literal}
 </style>
-<div class="madIdea">With smarty you can embed css in the template</div>
+<div class="madIdea">With smarty you can embed CSS in the template</div>
 ]]>
 </programlisting>
 </example>
- 
+
  <para>
   See also
-  <link linkend="language.function.ldelim">{ldelim} {rdelim}</link>
-  and 
-  <link linkend="language.escaping">Escaping Smarty Parsing</link>.
+  <link linkend="language.function.ldelim"><varname>{ldelim} {rdelim}</varname></link>
+  and the
+  <link linkend="language.escaping">escaping Smarty parsing</link> page.
  </para>
 </sect1>
 
diff --git a/docs/en/designers/language-builtin-functions/language-function-php.xml b/docs/en/designers/language-builtin-functions/language-function-php.xml
index e6d971aa..090feac6 100644
--- a/docs/en/designers/language-builtin-functions/language-function-php.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-php.xml
@@ -3,63 +3,60 @@
 <sect1 id="language.function.php">
  <title>{php}</title>
  <para>
-  The {php} tags allow PHP code to be embedded directly into the template. They
+  The <varname>{php}</varname> tags allow PHP code to be embedded directly into the template. They
   will not be escaped, regardless of the <link
-  linkend="variable.php.handling">$php_handling</link> setting. This
+  linkend="variable.php.handling"><parameter>$php_handling</parameter></link> setting. This
   is for advanced users only, not normally needed and not recommended.
  </para>
- <example>
-  <title>{php} tags</title>
-  <programlisting>
-<![CDATA[
-{php}
-   // including a php script directly
-   // from the template.
-   include('/path/to/display_weather.php');
-{/php}
-]]>
-  </programlisting>
- </example>
-<note>
+ <note>
 <title>Technical Note</title>
 <para>
-   To access PHP variables in {php} blocks you may need to use the PHP
+   To access PHP variables in <varname>{php}</varname> blocks you will need to use the PHP
    <ulink url="&url.php-manual;global">global</ulink>
    keyword.
 </para>
 </note>
 
+ <example>
+  <title>Example php in {php} tags</title>
+  <programlisting>
+<![CDATA[
+{php}
+   // including a php script directly from the template.
+   include('/path/to/display_weather.php');
+{/php}
+]]>
+  </programlisting>
+ </example>
+
+
  <example>
   <title>{php} tags with global and assigning a variable</title>
   <programlisting role="php">
 <![CDATA[
+{* this template includes a {php} block that assign's the variable $varX *}
 {php}
    global $foo, $bar;
    if($foo == $bar){
-     echo 'This will come out in the template';
+     echo 'This will be sent to browser';
    }
-$this->assign('varX','Strawberry');
+  // assign a variable to Smarty
+  $this->assign('varX','Toffee');
 {/php}
-<strong>{$varX}</strong> is my fav ice cream
+{* output the variable *}
+<strong>{$varX}</strong> is my fav ice cream :-)
 ]]>
   </programlisting>
-  <para>The following seriously NOT recommended as its in the template scope</para>
-<programlisting> 
-<![CDATA[
-{php}
-print_r($some_array);
-{/php}
-]]>
-</programlisting>
 </example>
- 
+
  <para>
   See also
-  <link linkend="variable.php.handling">$php_handling</link>,
-  <link linkend="language.function.include.php">{include_php}</link>,
-  <link linkend="language.function.include">{include}</link>,
-  <link linkend="language.function.insert">{insert}</link> and
-  <link linkend="tips.componentized.templates">Componentized Templates</link>.
+  <link linkend="variable.php.handling"><parameter>$php_handling</parameter></link>,
+  <link linkend="language.function.include.php"><varname>{include_php}</varname></link>,
+  <link linkend="language.function.include"><varname>{include}</varname></link>,
+  <link linkend="language.function.insert"><varname>{insert}</varname></link>
+  and
+  <link linkend="tips.componentized.templates">componentized templates</link>.
  </para>
 </sect1>
 <!-- Keep this comment at the end of the file
diff --git a/docs/en/designers/language-builtin-functions/language-function-section.xml b/docs/en/designers/language-builtin-functions/language-function-section.xml
index d1944d9f..18d32333 100644
--- a/docs/en/designers/language-builtin-functions/language-function-section.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-section.xml
@@ -798,8 +798,9 @@ the section was shown.
   </programlisting>
   </example>
   <para>
-   See also <link linkend="language.function.foreach">{foreach}</link>
-   and <link linkend="language.variables.smarty.loops">$smarty.section</link>.
+   See also <link linkend="language.function.foreach"><varname>{foreach}</varname></link>
+   and
+   <link linkend="language.variables.smarty.loops"><parameter>$smarty.section</parameter></link>.
   </para>
  </sect2>
 </sect1>
diff --git a/docs/en/designers/language-builtin-functions/language-function-strip.xml b/docs/en/designers/language-builtin-functions/language-function-strip.xml
index 6354094a..4792e04c 100644
--- a/docs/en/designers/language-builtin-functions/language-function-strip.xml
+++ b/docs/en/designers/language-builtin-functions/language-function-strip.xml
@@ -10,18 +10,16 @@
   unmanageable templates.
  </para>
  <para>
-  Anything within {strip}{/strip} tags  are stripped of the
+  Anything within <varname>{strip}{/strip}</varname> tags  are stripped of the
   extra spaces or carriage returns at the beginnings and ends of the
   lines before they are displayed. This way you can keep your
   templates readable, and not worry about extra white space causing
   problems.
  </para>
  <note>
-  <title>Technical Note</title>
   <para>
-   {strip}{/strip} does not affect the contents of template variables,
-   see the
-   <link linkend="language.modifier.strip">strip modifier</link> instead.
+   <varname>{strip}{/strip}</varname> does not affect the contents of template variables,
+   see the <link linkend="language.modifier.strip">strip modifier</link> instead.
   </para>
  </note>
  <example>
@@ -58,8 +56,8 @@
   they will be run together, and may not be desired results.
  </para>
  <para>
- See also
- <link linkend="language.modifier.strip">strip modifier</link>
+ See also the
+ <link linkend="language.modifier.strip"><varname>strip</varname></link> modifier.
  </para>
 </sect1>