cvs: smarty /docs/en/designers/language-builtin-functions language-function-section.xml

http://cvs.php.net/viewvc.cgi/smarty/docs/en/designers/language-builtin-functions/language-function-section.xml?r1=1.14&r2=1.15&diff_format=u
Index: smarty/docs/en/designers/language-builtin-functions/language-function-section.xml
diff -u smarty/docs/en/designers/language-builtin-functions/language-function-section.xml:1.14 smarty/docs/en/designers/language-builtin-functions/language-function-section.xml:1.15
--- smarty/docs/en/designers/language-builtin-functions/language-function-section.xml:1.14	Tue Sep 13 18:41:44 2005
+++ smarty/docs/en/designers/language-builtin-functions/language-function-section.xml	Mon Sep 25 19:21:24 2006
@@ -1,24 +1,17 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.14 $ -->
+<!-- $Revision: 1.15 $ -->
 <sect1 id="language.function.section">
  <title>{section},{sectionelse}</title>
   <para>
-   Template sections are used for looping over
-   <emphasis role="bold">arrays of data</emphasis>
-   (just like <link linkend="language.function.foreach">{foreach}</link>). All
-   <emphasis>{section}</emphasis> tags must be paired with
-   <emphasis>{/section}</emphasis> tags. Required parameters are
-   <emphasis>name</emphasis> and <emphasis>loop</emphasis>. The name
-   of the {section} can be anything you like, made up of letters,
-   numbers and underscores. Sections can be nested, and the nested
-   section names must be unique from each other. The loop variable
-   (usually an array of values) determines the number of times the
-   section will loop. When printing a variable within a section, the
-   section name must be given next to variable name within brackets
-   []. <emphasis>{sectionelse}</emphasis> is
-   executed when there are no values in the loop variable.
- </para>
- 
+  A <varname>{section}</varname>
+  is for looping over <emphasis role="bold">arrays of data</emphasis>,
+  unlike <link linkend="language.function.foreach"><varname>{foreach}</varname></link>
+  which is used to loop over a
+   <emphasis role="bold">single associative array</emphasis>.
+  Every <varname>{section}</varname> tag must be paired with
+   a closing <varname>{/section}</varname> tag.
+   </para>
+
  <informaltable frame="all">
   <tgroup cols="5">
    <colspec colname="param" align="center" />
@@ -85,26 +78,81 @@
      <entry>show</entry>
      <entry>boolean</entry>
      <entry>No</entry>
-     <entry><emphasis>true</emphasis></entry>
+     <entry><emphasis>&true;</emphasis></entry>
      <entry>determines whether or not to show this section</entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 
- <example>
-  <title>{section}</title>
+ <itemizedlist>
+   <listitem><para>
+   Required attributes are <parameter>name</parameter> and <parameter>loop</parameter>.
+   </para></listitem>
+
+   <listitem><para>
+    The <parameter>name</parameter> of the <varname>{section}</varname> can be
+    anything you like,  made up of letters,  numbers and underscores, like
+    <ulink url="&url.php-manual;language.variables">PHP variables</ulink>.
+    </para></listitem>
+
+    <listitem><para>
+    Sections can be nested, and the nested
+   <varname>{section}</varname> names must be unique from each other.
+   </para></listitem>
+
+   <listitem><para>
+   The <parameter>loop</parameter> attribute,
+   usually an array of values, determines the number of times the
+   <varname>{section}</varname> will loop.
+   </para></listitem>
+
+   <listitem><para>When printing a variable within a <varname>{section}</varname>, the
+   <varname>{section}</varname> <parameter>name</parameter> must be given next
+   to variable name within [brackets].
+   </para></listitem>
+
+   <listitem><para>
+   <varname>{sectionelse}</varname> is
+   executed when there are no values in the loop variable.
+ 	</para></listitem>
+
+  <listitem><para>
+  A <varname>{section}</varname> also has its own variables that handle
+  <varname>{section}</varname> properties.
+  These properties are accessible as: <link linkend="language.variables.smarty.loops">
+  <parameter>{$smarty.section.name.property}</parameter></link>
+  where <quote>name</quote> is the attribute <parameter>name</parameter>.
+  </para></listitem>
+
+	<listitem><para>
+	<varname>{section}</varname> properties are
+	<link linkend="section.property.index"><parameter>index</parameter></link>,
+	<link linkend="section.property.index.prev"><parameter>index_prev</parameter></link>,
+	<link linkend="section.property.index.next"><parameter>index_next</parameter></link>,
+	<link linkend="section.property.iteration"><parameter>iteration</parameter></link>,
+	<link linkend="section.property.first"><parameter>first</parameter></link>,
+	<link linkend="section.property.last"><parameter>last</parameter></link>,
+	<link linkend="section.property.rownum"><parameter>rownum</parameter></link>,
+	<link linkend="section.property.loop"><parameter>loop</parameter></link>,
+	<link linkend="section.property.show"><parameter>show</parameter></link>,
+	<link linkend="section.property.total"><parameter>total</parameter></link>.
+	</para></listitem>
 
+</itemizedlist>
+
+ <example>
+  <title>Looping a simple array with {section}</title>
+<para><link linkend="api.assign">assign()</link> an array to Smarty from the php script</para>
 <programlisting role="php">
 <![CDATA[
 <?php
-
 $data = array(1000,1001,1002);
 $smarty->assign('custid',$data);
-
 ?>
 ]]>
 </programlisting>
+<para>The template that outputs the array</para>
   <programlisting>
 <![CDATA[
 {* this example will print out all the values of the $custid array *}
@@ -132,9 +180,11 @@
 id: 1000<br />
 ]]>
   </screen>
-  <para>
-  Another couple of examples without an assigned array.
-  </para>
+  </example>
+
+
+   <example>
+  <title>{section} without an assigned array</title>
 <programlisting>
 <![CDATA[
 {section name=foo start=10 loop=20 step=2}
@@ -156,11 +206,93 @@
 20 18 16 14 12 10
 ]]>
   </screen>
+ </example>
+
 
+<example>
+  <title>Naming a {section}</title>
+  <para>The <parameter>name</parameter> of the <varname>{section}</varname> can be anything
+  you like, see <ulink url="&url.php-manual;language.variables">PHP variables</ulink>.
+  It is used to reference the data within the <varname>{section}</varname>.</para>
+  <programlisting>
+<![CDATA[
+{section name=anything loop=$myArray}
+  {$myArray[anything].foo}
+  {$name[anything]}
+  {$address[anything].bar}
+{/section}
+]]>
+  </programlisting>
  </example>
 
+
+ <example>
+  <title>Looping an associative array's with {section}</title>
+  <para>This is an example of printing an associative array
+   of data within a <varname>{section}</varname>. Following is the php script to assign the
+   <parameter>$contacts</parameter> array to Smarty.</para>
+  <programlisting role="php">
+  <![CDATA[
+<?php
+$data = array(
+          array('name' => 'John Smith', 'home' => '555-555-5555',
+                'cell' => '666-555-5555', 'email' => '[email protected]'),
+          array('name' => 'Jack Jones', 'home' => '777-555-5555',
+                'cell' => '888-555-5555', 'email' => '[email protected]'),
+          array('name' => 'Jane Munson', 'home' => '000-555-5555',
+                'cell' => '123456', 'email' => '[email protected]')
+        );
+$smarty->assign('contacts',$data);
+?>
+]]>
+  </programlisting>
+
+<para>The template to output <parameter>$contacts</parameter></para>
+  <programlisting>
+<![CDATA[
+{section name=customer loop=$contacts}
+<p>
+  name: {$contacts[customer].name}<br />
+  home: {$contacts[customer].home}<br />
+  cell: {$contacts[customer].cell}<br />
+  e-mail: {$contacts[customer].email}
+</p>
+{/section}
+]]>
+  </programlisting>
+  <para>
+   The above example will output:
+  </para>
+  <screen>
+<![CDATA[
+<p>
+  name: John Smith<br />
+  home: 555-555-5555<br />
+  cell: 666-555-5555<br />
+  e-mail: [email protected]
+</p>
+<p>
+  name: Jack Jones<br />
+  home phone: 777-555-5555<br />
+  cell phone: 888-555-5555<br />
+  e-mail: [email protected]
+</p>
+<p>
+  name: Jane Munson<br />
+  home phone: 000-555-5555<br />
+  cell phone: 123456<br />
+  e-mail: [email protected]
+</p>
+]]>
+  </screen>
+</example>
+
  <example>
-  <title>{section} loop variable</title>
+  <title>{section} demonstrating the <varname>loop</varname> variable</title>
+  <para>This example assumes that <parameter>$custid</parameter>, <parameter>$name</parameter>
+  and <parameter>$address</parameter> are all
+  arrays containing the same number of values. First the php script that assign's the
+  arrays to Smarty.</para>
 <programlisting role="php">
 <![CDATA[
 <?php
@@ -171,20 +303,16 @@
 $fullnames = array('John Smith','Jack Jones','Jane Munson');
 $smarty->assign('name',$fullnames);
 
-$addr = array('253 N 45th', '417 Mulberry ln', '5605 apple st');
+$addr = array('253 Abbey road', '417 Mulberry ln', '5605 apple st');
 $smarty->assign('address',$addr);
 
 ?>
 ]]>
 </programlisting>
+<para>The <parameter>loop</parameter> variable only determines the number of times to loop.
+  You can access ANY variable from the template within the <varname>{section}</varname></para>
   <programlisting>
 <![CDATA[
-{*
-  the loop variable only determines the number of times to loop.
-  you can access any variable from the template within the section.
-  This example assumes that $custid, $name and $address are all
-  arrays containing the same number of values
-*}
 {section name=customer loop=$custid}
 <p>
   id: {$custid[customer]}<br />
@@ -202,7 +330,7 @@
 <p>
   id: 1000<br />
   name: John Smith<br />
-  address: 253 N 45th
+  address: 253 Abbey road
 </p>
 <p>
   id: 1001<br />
@@ -218,27 +346,15 @@
   </screen>
  </example>
 
- <example>
-  <title>{section} naming</title>
-  <programlisting>
-<![CDATA[
-{*
-  the name of the section can be anything you like,
-  as it is used to reference the data within the section
-*}
-{section name=anything loop=$custid}
-<p>
-  id: {$custid[anything]}<br />
-  name: {$name[anything]}<br />
-  address: {$address[anything]}
-</p>
-{/section}
-]]>
-  </programlisting>
- </example>
+
 
  <example>
-  <title>nested sections</title>
+  <title>Nested {section}'s</title>
+  <para>
+  Sections can be nested as deep as you like. With nested sections,
+  you can access complex data structures, such as multi-dimensional
+  arrays. This is a php script thats assign's the arrays.
+  </para>
   <programlisting role="php">
 <![CDATA[
 <?php
@@ -269,14 +385,10 @@
 ?>
   ]]>
 </programlisting>
+<para>In this template, <emphasis>$contact_type[customer]</emphasis> is an array of
+  contact types for the current customer.</para>
   <programlisting>
 <![CDATA[
-{*
-  sections can be nested as deep as you like. With nested sections,
-  you can access complex data structures, such as multi-dimensional
-  arrays. In this example, $contact_type[customer] is an array of
-  contact types for the current customer.
-*}
 {section name=customer loop=$custid}
 <hr>
   id: {$custid[customer]}<br />
@@ -315,85 +427,22 @@
   </screen>
  </example>
 
- <example>
-  <title>sections and associative arrays</title>
-  <programlisting role="php">
-  <![CDATA[
-<?php
-
-$data = array(
-          array('name' => 'John Smith', 'home' => '555-555-5555',
-                'cell' => '666-555-5555', 'email' => '[email protected]'),
-          array('name' => 'Jack Jones', 'home' => '777-555-5555',
-                'cell' => '888-555-5555', 'email' => '[email protected]'),
-          array('name' => 'Jane Munson', 'home' => '000-555-5555',
-                'cell' => '123456', 'email' => '[email protected]')
-        );
-$smarty->assign('contacts',$data);
-
-?>
-]]>
-  </programlisting>
-
-  <programlisting>
-<![CDATA[
-{*
-   This is an example of printing an associative array
-   of data within a section
-*}
-{section name=customer loop=$contacts}
-<p>
-  name: {$contacts[customer].name}<br />
-  home: {$contacts[customer].home}<br />
-  cell: {$contacts[customer].cell}<br />
-  e-mail: {$contacts[customer].email}
-</p>
-{/section}
-]]>
-  </programlisting>
-  <para>
-   The above example will output:
-  </para>
-  <screen>
-<![CDATA[
-<p>
-  name: John Smith<br />
-  home: 555-555-5555<br />
-  cell: 666-555-5555<br />
-  e-mail: [email protected]
-</p>
-<p>
-  name: Jack Jones<br />
-  home phone: 777-555-5555<br />
-  cell phone: 888-555-5555<br />
-  e-mail: [email protected]
-</p>
-<p>
-  name: Jane Munson<br />
-  home phone: 000-555-5555<br />
-  cell phone: 123456<br />
-  e-mail: [email protected]
-</p>
-]]>
-  </screen>
 
-  <para>Database example (eg using Pear or Adodb)</para>
+<example>
+<title>Database example with a {sectionelse}</title>
+  <para>Results of a database search (eg ADODB or PEAR) are assigned to Smarty</para>
     <programlisting role="php">
   <![CDATA[
 <?php
-
-$sql = 'select id, name, home, cell, email from contacts';
-$smarty->assign('contacts',$db->getAll($sql) );
-
+$sql = 'select id, name, home, cell, email from contacts '
+      ."where name like '$foo%' ";
+$smarty->assign('contacts', $db->getAll($sql));
 ?>
 ]]>
 </programlisting>
-
+<para>The template to output the database result in a HTML table</para>
   <programlisting>
 <![CDATA[
-{*
-   output database result in a table
-*}
 <table>
 <tr><th>&nbsp;</th><th>Name></th><th>Home</th><th>Cell</th><th>Email</th></tr>
 {section name=co loop=$contacts}
@@ -404,60 +453,42 @@
     <td>{$contacts[co].cell}</td>
     <td>{$contacts[co].email}</td>
   <tr>
+{sectionelse}
+  <tr><td colspan="5">No items found</td></tr>
 {/section}
 </table>
 ]]>
 </programlisting>
  </example>
 
- <example>
-  <title>{sectionelse}</title>
-  <programlisting>
-<![CDATA[
-{* sectionelse will execute if there are no $custid values *}
-{section name=customer loop=$custid}
-  id: {$custid[customer]}<br />
-{sectionelse}
-  there are no values in $custid.
-{/section}
-]]>
-  </programlisting>
- </example>
- <para>
-  Sections also have their own variables that handle section properties.
-  These are indicated like so:
-  <link linkend="language.variables.smarty.loops">{$smarty.section.sectionname.varname}</link>
- </para>
- <note>
-  <para>
-   As of Smarty 1.5.0, the syntax for section property variables has
-    changed from {%sectionname.varname%} to
-   {$smarty.section.sectionname.varname}. The old syntax is still
-   supported, but you will only see examples of the new syntax.
-  </para>
- </note>
+
  <sect2 id="section.property.index">
-  <title>index</title>
+  <title>.index</title>
   <para>
-   index is used to display the current array index, starting with zero
-   (or the start attribute if given), and incrementing by one (or by
-   the step attribute if given.)
+   <parameter>index</parameter> contains the current array index, starting with zero
+   or the <parameter>start</parameter> attribute if given It increments by one or by
+   the <parameter>step</parameter> attribute if given.
   </para>
   <note>
    <title>Technical Note</title>
    <para>
-    If the step and start section properties are not
+    If the <parameter>step</parameter> and <parameter>start</parameter>
+     properties are not
     modified, then this works the same as the <link
-    linkend="section.property.iteration">iteration</link> section
-    property, except it starts at 0 instead of 1.
+    linkend="section.property.iteration"><parameter>iteration</parameter></link>
+    property, except it starts at zero instead of one.
    </para>
   </note>
   <example>
-<title>{section} property index</title>
+<title>{section} <varname>index</varname> property</title>
+<para>
+<note><title>FYI</title>
+<para><parameter>$custid[customer.index]</parameter> and <varname>$custid[customer]</varname>
+ are identical in meaning.</para>
+</note>
+</para>
    <programlisting>
 <![CDATA[
-{* FYI, $custid[customer.index] and $custid[customer] are identical in meaning *}
-
 {section name=customer loop=$custid}
   {$smarty.section.customer.index} id: {$custid[customer]}<br />
 {/section}
@@ -478,48 +509,47 @@
 
 
  <sect2 id="section.property.index.prev">
-  <title>index_prev</title>
+  <title>.index_prev</title>
   <para>
-   index_prev is used to display the previous loop index.
-   on the first loop, this is set to -1.
+   <parameter>index_prev</parameter> is the previous loop index.
+   On the first loop, this is set to -1.
   </para>
  </sect2>
 
  <sect2 id="section.property.index.next">
-  <title>index_next</title>
+  <title>.index_next</title>
   <para>
-   index_next is used to display the next loop index. On the last
-   loop, this is still one more than the current index (respecting the
-   setting of the step attribute, if given.)
+   <parameter>index_next</parameter> is  the next loop index. On the last
+   loop, this is still one more than the current index, respecting the
+   setting of the <parameter>step</parameter> attribute, if given.
   </para>
 
   <example>
-<title>{section} property index_next and index_prev</title>
+<title><varname>index</varname>, <varname>index_next</varname>
+ and <varname>index_prev</varname> properties </title>
 <programlisting role="php">
 <![CDATA[
 <?php
-
 $data = array(1001,1002,1003,1004,1005);
-$smarty->assign('custid',$data);
-
+$smarty->assign('rows',$data);
 ?>
 ]]>
 </programlisting>
+<para>Template to output the above array in a table</para>
    <programlisting>
 <![CDATA[
-{* FYI, $custid[cus.index] and $custid[cus] are identical in meaning *}
-
+{* $rows[row.index] and $rows[row] are identical in meaning *}
 <table>
   <tr>
     <th>index</th><th>id</th>
     <th>index_prev</th><th>prev_id</th>
     <th>index_next</th><th>next_id</th>
   </tr>
-{section name=cus loop=$custid}
+{section name=row loop=$rows}
   <tr>
-    <td>{$smarty.section.cus.index}</td><td>{$custid[cus]}</td>
-    <td>{$smarty.section.cus.index_prev}</td><td>{$custid[cus.index_prev]}</td>
-    <td>{$smarty.section.cus.index_next}</td><td>{$custid[cus.index_next]}</td>
+    <td>{$smarty.section.row.index}</td><td>{$rows[row]}</td>
+    <td>{$smarty.section.row.index_prev}</td><td>{$rows[row.index_prev]}</td>
+    <td>{$smarty.section.row.index_next}</td><td>{$rows[row.index_next]}</td>
   </tr>
 {/section}
 </table>
@@ -543,35 +573,37 @@
 
 
  <sect2 id="section.property.iteration">
-  <title>iteration</title>
+  <title>.iteration</title>
   <para>
-   iteration is used to display the current loop iteration.
+   <parameter>iteration</parameter> contains the current loop iteration and starts at one.
   </para>
   <note>
    <para>
-    This is not affected by the section properties start, step and
-    max, unlike the <link linkend="section.property.index">index</link>
-    property. Iteration also starts with 1 instead of 0 like index. <link
-    linkend="section.property.rownum">rownum</link> is an alias to iteration,
-    they work identical.
+    This is not affected by the <varname>{section}</varname> properties
+    <parameter>start</parameter>, <parameter>step</parameter> and <parameter>max</parameter>,
+     unlike the <link linkend="section.property.index"><parameter>index</parameter></link>
+    property. <parameter>iteration</parameter> also starts with one instead of zero
+    unlike <parameter>index</parameter>. <link
+    linkend="section.property.rownum"><parameter>rownum</parameter></link> is an alias to
+    <parameter>iteration</parameter>,  they are identical.
    </para>
   </note>
   <example>
-<title>{section} property iteration</title>
+<title>A section's <varname>iteration</varname> property </title>
 <programlisting role="php">
 <![CDATA[
 <?php
-
 // array of 3000 to 3015
 $id = range(3000,3015);
-$smarty->assign('custid',$id);
-
+$smarty->assign('arr',$id);
 ?>
 ]]>
 </programlisting>
+<para>Template to output every other element of the <varname>$arr</varname>
+array as <varname>step</varname>=2</para>
    <programlisting>
 <![CDATA[
-{section name=cu loop=$custid start=5 step=2}
+{section name=cu loop=$arr start=5 step=2}
   iteration={$smarty.section.cu.iteration}
   index={$smarty.section.cu.index}
   id={$custid[cu]}<br />
@@ -592,14 +624,14 @@
 ]]>
    </screen>
   <para>
-   This  example  uses the iteration property to
-   output a table header block every five rows
-   (uses <link linkend="language.function.if">{if}</link>
-   with the mod operator).
+   Another example uses the <parameter>iteration</parameter> property to
+   output a table header block every five rows and
+   uses <link linkend="language.function.if"><varname>{if}</varname></link>
+   with the mod operator.
   </para>
    <programlisting>
 <![CDATA[
-    <table>
+<table>
 {section name=co loop=$contacts}
   {if $smarty.section.co.iteration % 5 == 1}
     <tr><th>&nbsp;</th><th>Name></th><th>Home</th><th>Cell</th><th>Email</th></tr>
@@ -620,29 +652,27 @@
 
 
  <sect2 id="section.property.first">
-  <title>first</title>
+  <title>.first</title>
   <para>
-   first is set to true if the current section <link
-   linkend="section.property.iteration">iteration</link> is the first
-   one.
+   <parameter>first</parameter> is set to &true; if the current <varname>{section}</varname>
+   iteration is the initial one.
   </para>
  </sect2>
 
 
  <sect2 id="section.property.last">
-  <title>last</title>
+  <title>.last</title>
   <para>
-   last is set to true if the current section <link
-   linkend="section.property.iteration">iteration</link> is the last
-   one.
+   <parameter>last</parameter> is set to &true;
+   if the current section iteration is the final one.
   </para>
   <example>
-   <title>{section} property first and last</title>
+   <title>{section} property <varname>first</varname> and <varname>last</varname></title>
    <para>
-   This example loops the $customers array;
+   This example loops the <varname>$customers</varname> array,
    outputs a header block on the first iteration and
-   on the last outputs the footer block
-   (uses section <link linkend="section.property.total">total</link> property)
+   on the last outputs the footer block. Also uses the
+   <link linkend="section.property.total"><parameter>total</parameter></link> property.
    </para>
    <programlisting>
 <![CDATA[
@@ -669,29 +699,30 @@
 
 
  <sect2 id="section.property.rownum">
-  <title>rownum</title>
+  <title>.rownum</title>
   <para>
-   rownum is used to display the current loop iteration,
+   <parameter>rownum</parameter> contains the current loop iteration,
    starting with one. It is an alias to <link
-   linkend="section.property.iteration">iteration</link>, they work
-   identically.
+   linkend="section.property.iteration"><parameter>iteration</parameter></link>,
+   they work identically.
   </para>
  </sect2>
+
  <sect2 id="section.property.loop">
-  <title>loop</title>
+  <title>.loop</title>
   <para>
-   loop is used to display the last index number that this section
-   looped. This can be used inside or after the section.
-  </para>
+   <parameter>loop</parameter> contains the last index number
+   that this {section}
+   looped. This can be used inside or after the <varname>{section}</varname>.
+     </para>
   <example>
-   <title>{section} property index</title>
+   <title>{section} property <varname>loop</varname>s</title>
    <programlisting>
 <![CDATA[
 {section name=customer loop=$custid}
   {$smarty.section.customer.index} id: {$custid[customer]}<br />
 {/section}
-
-There were {$smarty.section.customer.loop} customers shown above.
+There are {$smarty.section.customer.loop} customers shown above.
 ]]>
   </programlisting>
   <para>
@@ -702,30 +733,28 @@
 0 id: 1000<br />
 1 id: 1001<br />
 2 id: 1002<br />
-
-There were 3 customers shown above.
+There are 3 customers shown above.
 ]]>
    </screen>
   </example>
  </sect2>
+
  <sect2 id="section.property.show">
-  <title>show</title>
+  <title>.show</title>
   <para>
-   <emphasis>show</emphasis> is used as a parameter to section.
-   <emphasis>show</emphasis> is a boolean value, true or false. If
-   false, the section will not be displayed. If there is a {sectionelse}
-   present, that will be alternately displayed.
+   <parameter>show</parameter> is used as a parameter to section.
+   <parameter>show</parameter> is a boolean value, &true; or &false;. If
+   &false;, the section will not be displayed. If there is a
+   <varname>{sectionelse}</varname>  present, that will be alternately displayed.
   </para>
   <example>
-   <title>{section} attribute show</title>
+   <title><varname>show</varname> property </title>
+   <para>Boolean <varname>$show_customer_info</varname> has been passed from the PHP
+  application, to regulate whether or not this section shows.</para>
    <programlisting>
 <![CDATA[
-{*
-  $show_customer_info (true/false) may have been passed from the PHP
-  application, to regulate whether or not this section shows
-*}
-{section name=customer loop=$custid show=$show_customer_info}
-  {$smarty.section.customer.rownum} id: {$custid[customer]}<br />
+{section name=customer loop=$customers show=$show_customer_info}
+  {$smarty.section.customer.rownum} id: {$customers[customer]}<br />
 {/section}
 
 {if $smarty.section.customer.show}
@@ -749,35 +778,24 @@
    </screen>
   </example>
  </sect2>
+
  <sect2 id="section.property.total">
-  <title>total</title>
+  <title>.total</title>
   <para>
-   total is used to display the number of iterations that this section
-   will loop. This can be used inside or after the section.
+   <parameter>total</parameter> contains the number of iterations that this
+   <varname>{section}</varname> will loop. This can be used inside or after a
+   <varname>{section}</varname>.
   </para>
   <example>
-   <title>{section} property total</title>
+   <title><varname>total</varname> property example</title>
    <programlisting>
 <![CDATA[
 {section name=customer loop=$custid step=2}
   {$smarty.section.customer.index} id: {$custid[customer]}<br />
 {/section}
-
-    There were {$smarty.section.customer.total} customers shown above.
+   There are {$smarty.section.customer.total} customers shown above.
 ]]>
   </programlisting>
-  <para>
-   The above example will output:
-  </para>
-  <screen>
-<![CDATA[
-0 id: 1000<br />
-2 id: 1002<br />
-4 id: 1004<br />
-
-There were 3 customers shown above.
-]]>
-   </screen>
   </example>
   <para>
    See also <link linkend="language.function.foreach">{foreach}</link>