A lot of formatting, tagging and tidy up. Some consistency at last

2025-08-06 03:14:27 +02:00 · 2006-09-25 21:47:31 +00:00
parent cffb3cf957
commit 345a0d56fa
12 changed files with 259 additions and 236 deletions
--- 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>

--- 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>

--- 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>
--- 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:
--- 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:
--- 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
--- 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
--- 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>

--- 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>

--- 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
--- 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>
--- 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>