cvs: smarty /docs getting-started.sgml

http://cvs.php.net/diff.php/smarty/docs/getting-started.sgml?r1=1.25&r2=1.26&ty=u
Index: smarty/docs/getting-started.sgml
diff -u smarty/docs/getting-started.sgml:1.25 smarty/docs/getting-started.sgml:1.26
--- smarty/docs/getting-started.sgml:1.25	Fri Jan 23 15:56:41 2004
+++ smarty/docs/getting-started.sgml	Tue Mar 16 09:55:11 2004
@@ -2,76 +2,126 @@
  <title>Getting Started</title>
 
  <chapter id="what.is.smarty">
-   <title>What is Smarty?</title>
-   <para>
-	Smarty is a template engine for PHP. More specifically, it facilitates a
-	manageable way to separate application logic and content from its
-	presentation. This is best described in a situation where the application
-	programmer and the template designer play different roles, or in most cases
-	are not the same person. For example, let's say you are creating a web page
-	that is displaying a newspaper article. The article headline, tagline,
-	author and body are content elements, they contain no information about how
-	they will be presented. They are passed into Smarty by the application,
-	then the template designer edits the templates and uses a combination of
-	HTML tags and template tags to format the presentation of these elements
-	(HTML tables, background colors, font sizes, style sheets, etc.) One day
-	the programmer needs to change the way the article content is retrieved (a
-	change in application logic.) This change does not affect the template
-	designer, the content will still arrive in the template exactly the same.
-	Likewise, if the template designer wants to completely redesign the
-	templates, this requires no changes to the application logic. Therefore,
-	the programmer can make changes to the application logic without the need
-	to restructure templates, and the template designer can make changes to
-	templates without breaking application logic.
-	</para>
-	<para>
-    One design goal of Smarty is the separation of business logic and
-    presentation logic. This means templates can certainly contain logic under
-    the condition that it is for presentation only. Things such as including
-    other templates, altering table row colors, upper-casing a variable,
-    looping over an array of data and displaying it, etc. are all examples of
-    presentation logic. This does not mean that Smarty forces a separation of
-    business and presentation logic. Smarty has no knowledge of which is which,
-    so placing business logic in the template is your own doing. Also, if you
-    desire NO logic in your templates you certainly can do so by boiling the
-    content down to text and variables only.
-	</para>
-	<para>
-	One of the unique aspects about Smarty is the template compling. This means
-	Smarty reads the template files and creates PHP scripts from them. Once
-	they are created, they are executed from then on. Therefore there is no
-	costly template file parsing for each request, and each template can take
-	full advantage of PHP compiler cache solutions such as Zend Accelerator
-	(http://www.zend.com) or PHP Accelerator
-	(http://www.php-accelerator.co.uk).
-   </para>
-   <para>
-    Some of Smarty's features:
-   </para>
-   <itemizedlist>
-    <listitem><para>It is extremely fast.</para></listitem>
-    <listitem><para>It is efficient since the PHP parser does the
-      dirty work.</para></listitem>
-    <listitem><para>No template parsing overhead, only compiles once.</para></listitem>
-    <listitem><para>It is smart about recompiling only the template
-      files that have changed.</para></listitem>
-    <listitem><para>You can make <link linkend="language.custom.functions">custom
-       functions</link> and custom <link linkend="language.modifiers">variable
-       modifiers</link>, so the template language is extremely extensible.</para></listitem>
-    <listitem><para>Configurable template delimiter tag syntax, so you can use
-      {}, {{}}, &lt;!--{}--&gt;, etc.</para></listitem>
-    <listitem><para>The if/elseif/else/endif constructs are passed to the
-      PHP parser, so the {if ...} expression syntax can be as simple or as complex
-      as you like.</para></listitem>
-    <listitem><para>Unlimited nesting of sections, ifs, etc. allowed.</para></listitem>
-    <listitem><para>It is possible to embed PHP code right in your template files,
-      although this may not be needed (nor recommended)
-      since the engine is so customizable.</para></listitem>
-    <listitem><para>Built-in caching support</para></listitem>
-    <listitem><para>Arbitrary template sources</para></listitem>
-    <listitem><para>Custom cache handling functions</para></listitem>
-    <listitem><para>Plugin architecture</para></listitem>
-   </itemizedlist>
+  <title>What is Smarty?</title>
+  <para>
+   Smarty is a template engine for PHP. More specifically, it facilitates a
+   manageable way to separate application logic and content from its
+   presentation. This is best described in a situation where the application
+   programmer and the template designer play different roles, or in most cases
+   are not the same person. For example, let's say you are creating a web page
+   that is displaying a newspaper article. The article headline, tagline,
+   author and body are content elements, they contain no information about how
+   they will be presented. They are passed into Smarty by the application,
+   then the template designer edits the templates and uses a combination of
+   HTML tags and template tags to format the presentation of these elements
+   (HTML tables, background colors, font sizes, style sheets, etc.) One day
+   the programmer needs to change the way the article content is retrieved (a
+   change in application logic.) This change does not affect the template
+   designer, the content will still arrive in the template exactly the same.
+   Likewise, if the template designer wants to completely redesign the
+   templates, this requires no changes to the application logic. Therefore,
+   the programmer can make changes to the application logic without the need
+   to restructure templates, and the template designer can make changes to
+   templates without breaking application logic.
+  </para>
+  <para>
+   One design goal of Smarty is the separation of business logic and
+   presentation logic. This means templates can certainly contain logic under
+   the condition that it is for presentation only. Things such as including
+   other templates, altering table row colors, upper-casing a variable,
+   looping over an array of data and displaying it, etc. are all examples of
+   presentation logic. This does not mean that Smarty forces a separation of
+   business and presentation logic. Smarty has no knowledge of which is which,
+   so placing business logic in the template is your own doing. Also, if you
+   desire NO logic in your templates you certainly can do so by boiling the
+   content down to text and variables only.
+  </para>
+  <para>
+   One of the unique aspects about Smarty is the template compling. This means
+   Smarty reads the template files and creates PHP scripts from them. Once
+   they are created, they are executed from then on. Therefore there is no
+   costly template file parsing for each request, and each template can take
+   full advantage of PHP compiler cache solutions such as Zend Accelerator
+   (http://www.zend.com) or PHP Accelerator
+   (http://www.php-accelerator.co.uk).
+  </para>
+  <para>
+   Some of Smarty's features:
+  </para>
+  <itemizedlist>
+   <listitem>
+    <para>
+     It is extremely fast.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     It is efficient since the PHP parser does the dirty work.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     No template parsing overhead, only compiles once.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     It is smart about recompiling only the template files that have changed.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     You can make <link linkend="language.custom.functions">custom functions</link>
+     and custom <link linkend="language.modifiers">variable modifiers</link>, so the
+     template language is extremely extensible.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Configurable template delimiter tag syntax, so you can use
+     {}, {{}}, &lt;!--{}--&gt;, etc.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     The if/elseif/else/endif constructs are passed to the
+     PHP parser, so the {if ...} expression syntax can be as simple or as complex
+     as you like.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Unlimited nesting of sections, ifs, etc. allowed.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     It is possible to embed PHP code right in your template files,
+     although this may not be needed (nor recommended)
+     since the engine is so customizable.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Built-in caching support
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Arbitrary template sources
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Custom cache handling functions
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Plugin architecture
+    </para>
+   </listitem>
+  </itemizedlist>
  </chapter>
  <chapter id="installation">
   <title>Installation</title>
@@ -79,136 +129,159 @@
   <sect1 id="installation.requirements">
    <title>Requirements</title>
    <para>
-   Smarty requires a web server running PHP 4.0.6 or later.
+    Smarty requires a web server running PHP 4.0.6 or later.
    </para>
   </sect1>
 
   <sect1 id="installing.smarty.basic">
-    <title>Basic Installation</title>
-	<para>
-	Install the Smarty library files which are in the /libs/ directory of
-	the distribution. These are the PHP files that you SHOULD NOT edit. They
-	are shared among all applications and they only get updated when you
-	upgrade to a new version of Smarty.
-	</para>
-	<example>
-     <title>Smarty library files</title>
-     <screen>
+   <title>Basic Installation</title>
+   <para>
+    Install the Smarty library files which are in the /libs/ directory of
+    the distribution. These are the PHP files that you SHOULD NOT edit. They
+    are shared among all applications and they only get updated when you
+    upgrade to a new version of Smarty.
+   </para>
+   <example>
+    <title>Smarty library files</title>
+    <screen>
+<![CDATA[
 Smarty.class.php
 Smarty_Compiler.class.php
 Config_File.class.php
 debug.tpl
 /core/*.php (all of them)
-/plugins/*.php (all of them)</screen>
-	</example>
-
-	<para>
-	Smarty uses a PHP constant named <link
-	linkend="constant.smarty.dir">SMARTY_DIR</link> which is the system
-	filepath Smarty library directory. Basically, if your application can find
-	the <emphasis>Smarty.class.php</emphasis> file, you do not need to set
-	SMARTY_DIR, Smarty will figure it out on its own. Therefore, if
-	<emphasis>Smarty.class.php</emphasis> is not in your include_path, or you
-	do not supply an absolute path to it in your application, then you must
-	define SMARTY_DIR manually. SMARTY_DIR <emphasis>must</emphasis> include a
-	trailing slash.
-	</para>
-	<para>
-	Here is how you create an instance of Smarty in your PHP scripts:
-	</para>
-
-	<example>
-     <title>Create Smarty instance of Smarty</title>
-     <screen>
+/plugins/*.php (all of them)
+]]>
+    </screen>
+   </example>
+   <para>
+    Smarty uses a PHP constant named <link
+    linkend="constant.smarty.dir">SMARTY_DIR</link> which is the system
+    filepath Smarty library directory. Basically, if your application can find
+    the <emphasis>Smarty.class.php</emphasis> file, you do not need to set
+    SMARTY_DIR, Smarty will figure it out on its own. Therefore, if
+    <emphasis>Smarty.class.php</emphasis> is not in your include_path, or you
+    do not supply an absolute path to it in your application, then you must
+    define SMARTY_DIR manually. SMARTY_DIR <emphasis>must</emphasis> include a
+    trailing slash.
+   </para>
+   <para>
+    Here is how you create an instance of Smarty in your PHP scripts:
+   </para>
+   
+   <example>
+    <title>Create Smarty instance of Smarty</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
 require('Smarty.class.php');
-$smarty = new Smarty;</screen>
-	</example>
+$smarty = new Smarty;
+?>
+]]>
+    </programlisting>
+   </example>
+
+   <para>
+    Try running the above script. If you get an error saying the
+    <emphasis>Smarty.class.php</emphasis> file could not be found, you have to
+    do one of the following:
+   </para>
 
-	<para>
-	Try running the above script. If you get an error saying the
-	<emphasis>Smarty.class.php</emphasis> file could not be found, you have to
-	do one of the following:
-	</para>
-
-	<example>
-     <title>Supply absolute path to library file</title>
-     <screen>
+   <example>
+    <title>Supply absolute path to library file</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
 require('/usr/local/lib/php/Smarty/Smarty.class.php');
-$smarty = new Smarty;</screen>
-	</example>
+$smarty = new Smarty;
+?>
+]]>
+    </programlisting>
+   </example>
 
-	<example>
-     <title>Add library directory to php_include path</title>
-     <screen>
+   <example>
+    <title>Add library directory to php_include path</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
 // Edit your php.ini file, add the Smarty library
 // directory to the include_path and restart web server.
 // Then the following should work:
 require('Smarty.class.php');
-$smarty = new Smarty;</screen>
-	</example>
+$smarty = new Smarty;
+?>
+]]>
+    </programlisting>
+   </example>
+
+   <example>
+    <title>Set SMARTY_DIR constant manually</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+define('SMARTY_DIR', '/usr/local/lib/php/Smarty/');
+require(SMARTY_DIR . 'Smarty.class.php');
+$smarty = new Smarty;
+?>
+]]>
+    </programlisting>
+   </example>
 
-	<example>
-     <title>Set SMARTY_DIR constant manually</title>
-     <screen>
-define('SMARTY_DIR','/usr/local/lib/php/Smarty/');
-require(SMARTY_DIR.'Smarty.class.php');
-$smarty = new Smarty;</screen>
-	</example>
-
-	<para>
-	Now that the library files are in place, it's time to setup the Smarty
-	directories for your application. Smarty requires four directories which
-	are (by default) named <emphasis>templates</emphasis>,
-	<emphasis>templates_c</emphasis>, <emphasis>configs</emphasis> and
-	<emphasis>cache</emphasis>. Each of these are definable by the Smarty class
-	properties <emphasis>$template_dir</emphasis>,
-	<emphasis>$compile_dir</emphasis>, <emphasis>$config_dir</emphasis>, and
-	<emphasis>$cache_dir</emphasis> respectively. It is highly recommended
-	that you setup a separate set of these directories for each application
-	that will use Smarty.
-	</para>
-	<para>
-	Be sure you know the location of your web server document root. In our
-	example, the document root is "/web/www.mydomain.com/docs/". The Smarty
-	directories are only accessed by the Smarty library and never accessed
-	directly by the web browser. Therefore to avoid any security concerns, it
-	is recommended to place these directories <emphasis>outside</emphasis> of
-	the document root.
-	</para>
-	<para>
-	For our installation example, we will be setting up the Smarty environment
-	for a guest book application. We picked an application only for the purpose
-	of a directory naming convention. You can use the same environment for any
-	application, just replace "guestbook" with the name of your app. We'll
-	place our Smarty directories under
-	"/web/www.mydomain.com/smarty/guestbook/".
-	</para>
-	<para>
-	You will need as least one file under your document root, and that is the
-	script accessed by the web browser. We will call our script "index.php",
-	and place it in a subdirectory under the document root called
-	"/guestbook/".
-	</para>
-	
-	<note>
-	<title>Technical Note</title>
-	<para>
-	It is convenient to setup the web server so that "index.php" can be
-	identified as the default directory index, so if you access
-	"http://www.mydomain.com/guestbook/", the index.php script will be executed
-	without "index.php" in the URL. In Apache you can set this up by adding
-	"index.php" onto the end of your DirectoryIndex setting (separate each
-	entry with a space.)
-	</para>
-	</note>
-	
-	<para>
-	Lets take a look at the file structure so far:
-	</para>
-
-	<example>
-     <title>Example file structure</title>
-     <screen>
+   <para>
+    Now that the library files are in place, it's time to setup the Smarty
+    directories for your application. Smarty requires four directories which
+    are (by default) named <emphasis>templates</emphasis>,
+    <emphasis>templates_c</emphasis>, <emphasis>configs</emphasis> and
+    <emphasis>cache</emphasis>. Each of these are definable by the Smarty class
+    properties <emphasis>$template_dir</emphasis>,
+    <emphasis>$compile_dir</emphasis>, <emphasis>$config_dir</emphasis>, and
+    <emphasis>$cache_dir</emphasis> respectively. It is highly recommended
+    that you setup a separate set of these directories for each application
+    that will use Smarty.
+   </para>
+   <para>
+    Be sure you know the location of your web server document root. In our
+    example, the document root is "/web/www.mydomain.com/docs/". The Smarty
+    directories are only accessed by the Smarty library and never accessed
+    directly by the web browser. Therefore to avoid any security concerns, it
+    is recommended to place these directories <emphasis>outside</emphasis> of
+    the document root.
+   </para>
+   <para>
+    For our installation example, we will be setting up the Smarty environment
+    for a guest book application. We picked an application only for the purpose
+    of a directory naming convention. You can use the same environment for any
+    application, just replace "guestbook" with the name of your app. We'll
+    place our Smarty directories under
+    "/web/www.mydomain.com/smarty/guestbook/".
+   </para>
+   <para>
+    You will need as least one file under your document root, and that is the
+    script accessed by the web browser. We will call our script "index.php",
+    and place it in a subdirectory under the document root called
+    "/guestbook/".
+   </para>
+    
+   <note>
+    <title>Technical Note</title>
+    <para>
+     It is convenient to setup the web server so that "index.php" can be
+     identified as the default directory index, so if you access
+     "http://www.mydomain.com/guestbook/", the index.php script will be executed
+     without "index.php" in the URL. In Apache you can set this up by adding
+     "index.php" onto the end of your DirectoryIndex setting (separate each
+     entry with a space.)
+    </para>
+   </note>
+    
+   <para>
+    Lets take a look at the file structure so far:
+   </para>
+
+   <example>
+    <title>Example file structure</title>
+    <screen>
+<![CDATA[
 /usr/local/lib/php/Smarty/Smarty.class.php
 /usr/local/lib/php/Smarty/Smarty_Compiler.class.php
 /usr/local/lib/php/Smarty/Config_File.class.php
@@ -221,75 +294,84 @@
 /web/www.mydomain.com/smarty/guestbook/configs/
 /web/www.mydomain.com/smarty/guestbook/cache/
 
-/web/www.mydomain.com/docs/guestbook/index.php</screen>
-	</example>
+/web/www.mydomain.com/docs/guestbook/index.php
+]]>
+    </screen>
+   </example>
 
-	<para>
-	Smarty will need write access to the <emphasis>$compile_dir</emphasis> and
-	<emphasis>$cache_dir</emphasis>, so be sure the web server user can write
-	to them. This is usually user "nobody" and group "nobody". For OS X users,
-	the default is user "www" and group "www". If you are using Apache, you can
-	look in your httpd.conf file (usually in "/usr/local/apache/conf/") to see
-	what user and group are being used.
-	</para>
-
-	<example>
-     <title>Setting file permissions</title>
-     <screen>
+   <para>
+    Smarty will need write access to the <emphasis>$compile_dir</emphasis> and
+    <emphasis>$cache_dir</emphasis>, so be sure the web server user can write
+    to them. This is usually user "nobody" and group "nobody". For OS X users,
+    the default is user "www" and group "www". If you are using Apache, you can
+    look in your httpd.conf file (usually in "/usr/local/apache/conf/") to see
+    what user and group are being used.
+   </para>
 
+   <example>
+    <title>Setting file permissions</title>
+    <programlisting role="shell">
+<![CDATA[
 chown nobody:nobody /web/www.mydomain.com/smarty/guestbook/templates_c/
 chmod 770 /web/www.mydomain.com/smarty/guestbook/templates_c/
 
 chown nobody:nobody /web/www.mydomain.com/smarty/guestbook/cache/
-chmod 770 /web/www.mydomain.com/smarty/guestbook/cache/</screen>
-	</example>
+chmod 770 /web/www.mydomain.com/smarty/guestbook/cache/
+]]>
+    </programlisting>
+   </example>
+
+   <note>
+    <title>Technical Note</title>
+    <para>
+     chmod 770 will be fairly tight security, it only allows user "nobody" and
+     group "nobody" read/write access to the directories. If you would like to
+     open up read access to anyone (mostly for your own convenience of viewing
+     these files), you can use 775 instead.
+    </para>
+   </note>
 
-	<note>
-	 <title>Technical Note</title>
-	 <para>
-	 chmod 770 will be fairly tight security, it only allows user "nobody" and
-	 group "nobody" read/write access to the directories. If you would like to
-	 open up read access to anyone (mostly for your own convenience of viewing
-	 these files), you can use 775 instead.
-     </para>
-	</note>
-
-	<para>
-	We need to create the index.tpl file that Smarty will load. This will be
-	located in your $template_dir.
-	</para>
-
-	<example>
-     <title>Editing /web/www.mydomain.com/smarty/guestbook/templates/index.tpl</title>
-     <screen>
+   <para>
+    We need to create the index.tpl file that Smarty will load. This will be
+    located in your $template_dir.
+   </para>
+
+   <example>
+    <title>Editing /web/www.mydomain.com/smarty/guestbook/templates/index.tpl</title>
+    <screen>
+<![CDATA[
 
 {* Smarty *}
 
-Hello, {$name}!</screen>
-	</example>
+Hello, {$name}!
+]]>
+    </screen>
+   </example>
+
+   <note>
+    <title>Technical Note</title>
+    <para>
+     {* Smarty *} is a template comment. It is not required, but it is good
+     practice to start all your template files with this comment. It makes
+     the file easy to recognize regardless of the file extension. For
+     example, text editors could recognize the file and turn on special
+     syntax highlighting.
+    </para>
+   </note>
+
+   <para>
+    Now lets edit index.php. We'll create an instance of Smarty, assign a
+    template variable and display the index.tpl file. In our example
+    environment, "/usr/local/lib/php/Smarty" is in our include_path. Be sure you
+    do the same, or use absolute paths.
+   </para>
 
+   <example>
+    <title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
 
-	<note>
-	<title>Technical Note</title>
-	<para>
-		{* Smarty *} is a template comment. It is not required, but it is good
-		practice to start all your template files with this comment. It makes
-		the file easy to recognize regardless of the file extension. For
-		example, text editors could recognize the file and turn on special
-		syntax highlighting.
-	</para>
-	</note>
-
-	<para>
-	Now lets edit index.php. We'll create an instance of Smarty, assign a
-	template variable and display the index.tpl file. In our example
-	environment, "/usr/local/lib/php/Smarty" is in our include_path. Be sure you
-	do the same, or use absolute paths.
-	</para>
-
-	<example>
-     <title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
-     <screen>
 // load Smarty library
 require('Smarty.class.php');
 
@@ -302,49 +384,54 @@
 
 $smarty->assign('name','Ned');
 
-$smarty->display('index.tpl');</screen>
-	</example>
+$smarty->display('index.tpl');
+?>
+]]>
+    </programlisting>
+   </example>
 
-	<note>
-	 <title>Technical Note</title>
-	 <para>
-	 In our example, we are setting absolute paths to all of the Smarty
-	 directories. If '/web/www.mydomain.com/smarty/guestbook/' is within your
-	 PHP include_path, then these settings are not necessary. However, it is
-	 more efficient and (from experience) less error-prone to set them to
-	 absolute paths. This ensures that Smarty is getting files from the
-	 directories you intended.
-	 </para>
-	</note>
-
-	<para>
-	Now load the index.php file from your web browser. You should see "Hello,
-	Ned!"
-	</para>
-	<para>
-	You have completed the basic setup for Smarty!
-	</para>
-   </sect1>
-   <sect1 id="installing.smarty.extended">
+   <note>
+    <title>Technical Note</title>
+    <para>
+     In our example, we are setting absolute paths to all of the Smarty
+     directories. If '/web/www.mydomain.com/smarty/guestbook/' is within your
+     PHP include_path, then these settings are not necessary. However, it is
+     more efficient and (from experience) less error-prone to set them to
+     absolute paths. This ensures that Smarty is getting files from the
+     directories you intended.
+    </para>
+   </note>
+
+   <para>
+    Now load the index.php file from your web browser. You should see "Hello,
+    Ned!"
+   </para>
+   <para>
+    You have completed the basic setup for Smarty!
+   </para>
+  </sect1>
+  <sect1 id="installing.smarty.extended">
    <title>Extended Setup</title>
 
    <para>
-   This is a continuation of the <link
-   linkend="installing.smarty.basic">basic installation</link>, please read
-   that first!
+    This is a continuation of the <link
+    linkend="installing.smarty.basic">basic installation</link>, please read
+    that first!
    </para>
    <para>
-   A slightly more flexible way to setup Smarty is to extend the class and
-   initialize your Smarty environment. So instead of repeatedly setting
-   directory paths, assigning the same vars, etc., we can do that in one place.
-   Lets create a new directory "/php/includes/guestbook/" and make a new file
-   called "setup.php". In our example environment, "/php/includes" is in our
-   include_path. Be sure you set this up too, or use absolute file paths.
+    A slightly more flexible way to setup Smarty is to extend the class and
+    initialize your Smarty environment. So instead of repeatedly setting
+    directory paths, assigning the same vars, etc., we can do that in one place.
+    Lets create a new directory "/php/includes/guestbook/" and make a new file
+    called "setup.php". In our example environment, "/php/includes" is in our
+    include_path. Be sure you set this up too, or use absolute file paths.
    </para>
 
    <example>
     <title>Editing /php/includes/guestbook/setup.php</title>
-    <screen>
+    <programlisting role="php">
+<![CDATA[
+<?php
 
 // load Smarty library
 require('Smarty.class.php');
@@ -358,29 +445,34 @@
 
    function Smarty_GuestBook() {
    
-   		// Class Constructor. These automatically get set with each new instance.
+           // Class Constructor. These automatically get set with each new instance.
 
-		$this->Smarty();
+        $this->Smarty();
 
-		$this->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/';
-		$this->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
-		$this->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
-		$this->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/'; 
-		
-		$this->caching = true;
-		$this->assign('app_name','Guest Book');
+        $this->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/';
+        $this->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
+        $this->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
+        $this->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/'; 
+        
+        $this->caching = true;
+        $this->assign('app_name','Guest Book');
    }
 
-}</screen>
+}
+?>
+]]>
+    </programlisting>
    </example>
 
   <para>
-  Now lets alter the index.php file to use setup.php:
+   Now lets alter the index.php file to use setup.php:
   </para>
    
-   <example>
-    <title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
-    <screen>
+  <example>
+   <title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
 
 require('guestbook/setup.php');
 
@@ -388,12 +480,15 @@
 
 $smarty->assign('name','Ned');
 
-$smarty->display('index.tpl');</screen>
-   </example>
+$smarty->display('index.tpl');
+?>
+]]>
+   </programlisting>
+  </example>
 
   <para>
-  Now you see it is quite simple to bring up an instance of Smarty, just use
-  Smarty_GuestBook which automatically initializes everything for our application.
+   Now you see it is quite simple to bring up an instance of Smarty, just use
+   Smarty_GuestBook which automatically initializes everything for our application.
   </para>
    
   </sect1>