Minor formatting and error correction

docs/en/designers/language-basic-syntax.xml

@@ -4,11 +4,11 @@
  <title>Basic Syntax</title>
  <para>
   All Smarty template tags are enclosed within delimiters. By
-  default, these delimiters are <literal>{</literal> and
+  default these are <literal>{</literal> and
   <literal>}</literal>, but they can be <link linkend="variable.left.delimiter">changed</link>.
  </para>
  <para>
-  For these examples, we will assume that you are using the default
+  For examples, we will assume that you are using the default
   delimiters. In Smarty, all content outside of delimiters is displayed as
   static content, or unchanged. When Smarty encounters template tags, it
   attempts to interpret them, and displays the appropriate output in their

docs/en/designers/language-basic-syntax/language-syntax-attributes.xml

@@ -11,7 +11,7 @@
   should not be in quotes.
  </para>
  <para>
-  Some attributes require boolean values (true or false). These 
+  Some attributes require boolean values (&true; or &false;). These
   can be specified
   as either unquoted <literal>true</literal>,
   <literal>on</literal>, and <literal>yes</literal>, or

docs/en/designers/language-basic-syntax/language-syntax-comments.xml

@@ -6,10 +6,19 @@
   Template comments are surrounded by asterisks, and that is surrounded
   by the
   <link linkend="variable.left.delimiter">delimiter</link>
-  tags like so: <literal>{* this is a comment *}</literal>
+  tags like so:
+  </para>
+    <informalexample>
+   <programlisting>
+<![CDATA[
+{* this is a comment *}
+]]>
+   </programlisting>
+  </informalexample>
+  <para>
   Smarty comments are NOT displayed in the final output of the template,
-  unlike <literal>&lt;!-- HTML comments --&gt;</literal>
-  these are useful for making internal notes in the templates which no one will see ;-)
+  unlike <literal>&lt;!-- HTML comments --&gt;</literal>.
+  These are useful for making internal notes in the templates which no one will see ;-)
  </para>
  <example>
   <title>Comments within a template</title>
@@ -53,6 +62,18 @@ Multi line comment block with credits block
 </select>
 *}
 
+<!-- Show header from affiliate is disabled -->
+{* $affiliate|upper *}
+
+{* you cannot nest comments *}
+{*
+<select name="company">
+  {* <option value="0">-- none -- </option> *}
+  {html_options options=$vals selected=$selected_id}
+</select>
+*}
+
+
 {* cvs tag for a template, below the 36 SHOULD be an american currency
 . however its converted in cvs.. *}
 {* &#36;Id: Exp &#36; *}

docs/en/designers/language-basic-syntax/language-syntax-quotes.xml

@@ -2,24 +2,35 @@
 <!-- $Revision$ -->
 <sect1 id="language.syntax.quotes">
  <title>Embedding Vars in Double Quotes</title>
+
+ <itemizedlist>
+  <listitem>
  <para>
   Smarty will recognize <link
   linkend="api.assign">assigned</link>
   <link   linkend="language.syntax.variables">variables</link>
-  embedded in double quotes so long as the variable name contains only numbers,
-  letters, underscores and brackets[]
-  (see <ulink url="&url.php-manual;language.variables">naming</ulink>).
-  With any other characters (period,
-  object reference, etc.) the variable must be surrounded by
-  `backticks`. You cannot embed
+  embedded in "double quotes" so long as the variable name contains only numbers,
+  letters, under_scores and brackets[].
+  See <ulink url="&url.php-manual;language.variables">naming</ulink>
+  for more detail.
+  </para></listitem>
+
+  <listitem><para>
+  With any other characters, for example a .period or
+  <literal>$object>reference</literal>, then the variable must be
+  surrounded by  <literal>`backticks`</literal>.
+  </para></listitem>
+
+  <listitem><para>You cannot embed
   <link linkend="language.modifiers">modifiers</link>, they must always
   be applied outside of quotes.
- </para>
+ </para></listitem>
+ </itemizedlist>
+
  <example>
-  <title>embedded quotes syntax</title>
+  <title>Syntax examples</title>
   <programlisting>
 <![CDATA[
-SYNTAX EXAMPLES:
 {func var="test $foo test"}       <-- sees $foo
 {func var="test $foo_bar test"}   <-- sees $foo_bar
 {func var="test $foo[0] test"}    <-- sees $foo[0]
@@ -27,13 +38,32 @@ SYNTAX EXAMPLES:
 {func var="test $foo.bar test"}   <-- sees $foo (not $foo.bar)
 {func var="test `$foo.bar` test"} <-- sees $foo.bar
 {func var="test `$foo.bar` test"|escape} <-- modifiers outside quotes!
-
-PRACTICAL EXAMPLES:
-{include file="subdir/$tpl_name.tpl"} <-- will replace $tpl_name with value
-{cycle values="one,two,`$smarty.config.myval`"} <-- must have backticks
 ]]>
   </programlisting>
 </example>
+
+ <example>
+  <title>Practical examples</title>
+  <programlisting>
+<![CDATA[
+{* will replace $tpl_name with value *}
+{include file="subdir/$tpl_name.tpl"}
+
+{* doesn't replace $tpl_name *}
+{include file='subdir/$tpl_name.tpl'} <--
+
+{* must have backticks as it contains a . *}
+{cycle values="one,two,`$smarty.config.myval`"}
+
+{*  same as $module['contact'].'.tpl' in a php script
+{include file="`$module.contact`.tpl"}
+
+{*  same as $module[$view].'.tpl' in a php script
+{include file="$module.$view.tpl"}
+]]>
+  </programlisting>
+ </example>
+
  <para>
   See also <link linkend="language.modifier.escape"><varname>escape</varname></link>.
  </para>

docs/en/designers/language-builtin-functions.xml

@@ -7,12 +7,12 @@
   are the integral part of the smarty template engine. You cannot create your own
   <link linkend="language.custom.functions">custom functions</link>
   with the same name; and you  should  not need to
-  modify the built-in functions.
- </para>
+  modify the built-in functions.</para>
+
  <para>
- A few on these functions have an <parameter>assign</parameter>
- attribute which collects the result the function to a named
- variable within a template instead of being output;
+ A few of these functions have an <parameter>assign</parameter>
+ attribute which collects the result the function to a named template
+ variable instead of being output;
  much like the <link linkend="language.function.assign">
  <varname>{assign}</varname></link> function.
  </para>

docs/en/designers/language-modifiers/language-modifier-escape.xml

@@ -3,11 +3,11 @@
  <sect1 id="language.modifier.escape">
   <title>escape</title>
     <para>
-     This is used to encode/escape a variable to <literal>html</literal>,
+    <varname>escape</varname> is used to encode or escape a variable to for example <literal>html</literal>,
      <literal>url</literal>, <literal>single quotes</literal>,
      <literal>hex</literal>, <literal>hexentity</literal>,
      <literal>javascript</literal> and <literal>mail</literal>.
-     By default its <literal>html</literal> escaped.
+     By default its <literal>html</literal>.
   </para>
 
   <informaltable frame="all">
@@ -73,37 +73,36 @@ $smarty->assign('EmailAddress','smarty@example.com');
 ]]>
    </programlisting>
    <para>
-    Where template is:
+   These are example <literal>escape</literal> template lines followed by the output
    </para>
    <programlisting>
 <![CDATA[
 {$articleTitle}
+'Stiff Opposition Expected to Casketless Funeral Plan'
+
 {$articleTitle|escape}
+&#039;Stiff Opposition Expected to Casketless Funeral Plan&#039;
+
 {$articleTitle|escape:'html'}    {* escapes  & " ' < > *}
+&#039;Stiff Opposition Expected to Casketless Funeral Plan&#039;
+
 {$articleTitle|escape:'htmlall'} {* escapes ALL html entities *}
-{$articleTitle|escape:'url'}
+&#039;Stiff Opposition Expected to Casketless Funeral Plan&#039;
+
+<a href="?title={$articleTitle|escape:'url'}">click here</a>
+<a href="?title=%27Stiff+Opposition+Expected+to+Casketless+Funeral+Plan%27">click here</a>
+
 {$articleTitle|escape:'quotes'}
+\'Stiff Opposition Expected to Casketless Funeral Plan\'
+
 <a href="mailto:{$EmailAddress|escape:"hex"}">{$EmailAddress|escape:"hexentity"}</a>
 {$EmailAddress|escape:'mail'}    {* this converts to email to text *}
+<a href="mailto:%62%6f%..snip..%65%74">&#x62;&#x6f;&#x62..snip..&#x65;&#x74;</a>
+
 {'mail@example.com'|escape:'mail'}
+smarty [AT] example [DOT] com
 ]]>
    </programlisting>
-   <para>
-    Will output:
-   </para>
-   <screen>
-<![CDATA[
-'Stiff Opposition Expected to Casketless Funeral Plan'
-&#039;Stiff Opposition Expected to Casketless Funeral Plan&#039;
-&#039;Stiff Opposition Expected to Casketless Funeral Plan&#039;
-&#039;Stiff Opposition Expected to Casketless Funeral Plan&#039;
-%27Stiff+Opposition+Expected+to+Casketless+Funeral+Plan%27
-\'Stiff Opposition Expected to Casketless Funeral Plan\'
-<a href="mailto:%62%6f%..snip..%65%74">&#x62;&#x6f;&#x62..snip..&#x65;&#x74;</a>
-smarty [AT] example [DOT] com
-mail [AT] example [DOT] com
-]]>
-   </screen>
    </example>
 
    <example>