diff --git a/docs/en/designers/config-files.xml b/docs/en/designers/config-files.xml
index d41b705a..8f8ba32d 100644
--- a/docs/en/designers/config-files.xml
+++ b/docs/en/designers/config-files.xml
@@ -49,8 +49,8 @@ pass=foobar
   #</literal> (hash) at the beginning of the line.
  </para>
  <para>
-  This config file example has two sections. Section names are
-  enclosed in brackets []. Section names can be arbitrary strings not
+  The example config file above has two sections. Section names are
+  enclosed in [brackets]. Section names can be arbitrary strings not
   containing <literal>[</literal> or <literal>]</literal> symbols. The
   four variables at the top are global variables, or variables not
   within a section.  These variables are always loaded from the config
@@ -59,29 +59,30 @@ pass=foobar
   exists both as a global and in a section, the section variable is
   used. If you name two variables the same within a section, the last
   one will be used unless <link linkend="variable.config.overwrite">
-  $config_overwrite</link> is disabled.
+  <parameter>$config_overwrite</parameter></link> is disabled.
  </para>
  <para>
-  Config files are loaded into templates with the built-in function
-  <link linkend="language.function.config.load"><command>
-  {config_load}</command></link> (see also <link
-  linkend="api.config.load"><command>config_load()</command></link> ).
+  Config files are loaded into templates with the built-in template function
+  <link linkend="language.function.config.load"><varname>
+  {config_load}</varname></link> or the API <link
+  linkend="api.config.load"><varname>config_load()</varname></link> function.
  </para>
  <para>
   You can hide variables or entire sections by prepending the variable
-  name or section name with a period. This is useful if your
+  name or section name with a period eg <literal>[.hidden]</literal>. This is useful if your
   application reads the config files and gets sensitive data from them
   that the template engine does not need. If you have third parties
   doing template editing, you can be certain that they cannot read
   sensitive data from the config file by loading it into the template.
  </para>
  <para>
-  See also <link
-  linkend="language.function.config.load">{config_load}</link>, <link
-  linkend="variable.config.overwrite">$config_overwrite</link>, <link
-  linkend="api.get.config.vars">get_config_vars()</link>, <link
-  linkend="api.clear.config">clear_config()</link> and <link
-  linkend="api.config.load">config_load()</link>
+  See also
+  <link linkend="language.function.config.load"><varname>{config_load}</varname></link>,
+  <link linkend="variable.config.overwrite"><parameter>$config_overwrite</parameter></link>,
+  <link linkend="api.get.config.vars"><varname>get_config_vars()</varname></link>,
+  <link linkend="api.clear.config"><varname>clear_config()</varname></link>
+  and
+  <link linkend="api.config.load"><varname>config_load()</varname></link>
  </para>
 </chapter>
 <!-- Keep this comment at the end of the file
diff --git a/docs/en/getting-started.xml b/docs/en/getting-started.xml
index ec00e72d..844923be 100644
--- a/docs/en/getting-started.xml
+++ b/docs/en/getting-started.xml
@@ -141,6 +141,8 @@
    </listitem>
   </itemizedlist>
  </chapter>
+
+
  <chapter id="installation">
   <title>Installation</title>
 
@@ -154,7 +156,8 @@
   <sect1 id="installing.smarty.basic">
    <title>Basic Installation</title>
    <para>
-    Install the Smarty library files which are in the /libs/ sub directory of
+    Install the Smarty library files which are in the <filename>/libs/</filename>
+    sub directory of
     the distribution. These are 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.
@@ -174,23 +177,26 @@ debug.tpl
    </example>
    <para>
     Smarty uses a PHP <ulink url="&url.php-manual;define">constant</ulink>  named
-    <link linkend="constant.smarty.dir">SMARTY_DIR</link> which is the 
-    <emphasis role="bold">full system file path</emphasis> to the Smarty 'libs/' directory. 
+    <link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link> which is the
+    <emphasis role="bold">full system file path</emphasis> to the Smarty
+    <filename>libs/</filename> directory.
     Basically, if your application
     can find  the <filename>Smarty.class.php</filename> file, you do not need
-    to set the <link linkend="constant.smarty.dir">SMARTY_DIR</link>,
-     Smarty will figure it out on its own. Therefore, if
+    to set <link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link>
+     as Smarty will figure it out on its own. Therefore, if
      <filename>Smarty.class.php</filename> 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 role="bold">must include a
-    trailing slash</emphasis>.
-   </para>
-   <para>
-    Here's how you create an instance of Smarty in your PHP scripts:
+    define <constant>SMARTY_DIR</constant> manually.
+    <constant>SMARTY_DIR</constant> <emphasis role="bold">must include a
+    trailing slash/</emphasis>.
    </para>
 
+
    <example>
-    <title>Create Smarty instance of Smarty</title>
+    <title>Create an instance of Smarty</title>
+       <para>
+    Here's how you create an instance of Smarty in your PHP scripts:
+   </para>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -229,7 +235,7 @@ $smarty = new Smarty();
 ]]>
     </programlisting>
    </example>
-   
+
    <example>
     <title>Supply absolute path to library file</title>
     <programlisting role="php">
@@ -290,7 +296,7 @@ $smarty = new Smarty();
    </para>
    <para>
     Be sure you know the location of your web server document root. In our
-    example, the document root is <filename
+    examples, the document root is <filename
     class="directory">/web/www.example.com/docs/</filename>. 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
@@ -301,33 +307,38 @@ $smarty = new Smarty();
     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
+    application, just replace <quote>guestbook</quote> with the name of your app.
+    We'll place our Smarty directories under
     <filename
     class="directory">/web/www.example.com/smarty/guestbook/</filename>.
    </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
-    <emphasis>'index.php'</emphasis>, and place it in a subdirectory under the
+    <filename>index.php</filename>, and place it in a subdirectory under the
     document root called <filename class="directory">/guestbook/</filename>.
    </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.example.com/guestbook/, the 'index.php' script will be executed
-     without adding 'index.php' to the URL. In Apache you can set this up by adding
-     "index.php" onto the end of your <emphasis>DirectoryIndex</emphasis> setting (separate
-     each entry with a space.) as in the httpd.conf example
-    </para>
-    <para>
-    <emphasis>DirectoryIndex
-    index.htm index.html index.php index.php3 default.html index.cgi
-    </emphasis>
+     It is convenient to setup the web server so that <filename>index.php</filename>
+      can be identified as the default directory index, so if you access
+     <literal>http://www.example.com/guestbook/</literal>, the <filename>index.php</filename>
+      script will be executed without adding <filename>index.php</filename> to
+      the URL. In Apache you can set this up by adding
+     <literal>index.php</literal> onto the end of your
+     <literal>DirectoryIndex</literal> setting (separate
+     each entry with a space) as in the following <filename>httpd.conf</filename> example.
     </para>
+
+    <example>
+    <title>http.conf</title>
+    <programlisting>
+<![CDATA[DirectoryIndex index.htm index.html index.cgi index.php]]>
+    </programlisting>
+    </example>
+
    </note>
 
    <para>
@@ -335,7 +346,7 @@ $smarty = new Smarty();
    </para>
 
    <example>
-    <title>Example file structure</title>
+    <title>File structure so far</title>
     <screen>
 <![CDATA[
 /usr/local/lib/php/Smarty-v.e.r/libs/Smarty.class.php
@@ -359,13 +370,13 @@ $smarty = new Smarty();
     Smarty will need <emphasis role="bold">write access</emphasis>
     (windows users please ignore) to the
     <link linkend="variable.compile.dir">
-    <emphasis>$compile_dir</emphasis></link> and
+    <parameter>$compile_dir</parameter></link> and
     <link linkend="variable.cache.dir">
-    <emphasis>$cache_dir</emphasis></link>,
+    <parameter>$cache_dir</parameter></link>,
     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
+    look in your <filename>httpd.conf</filename> file to see
     what user and group are being used.
    </para>
 
@@ -383,7 +394,7 @@ chmod 770 /web/www.example.com/smarty/guestbook/cache/
    </example>
 
    <note>
-    <title>Technical Note</title>
+    <title>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
@@ -393,15 +404,15 @@ chmod 770 /web/www.example.com/smarty/guestbook/cache/
    </note>
 
    <para>
-    We need to create the 'index.tpl' file that Smarty will load. This will be
-    located in the <link linkend="variable.template.dir">$template_dir</link>.
+    We need to create the <filename>index.tpl</filename> file that Smarty will
+    load. This needs to be located in the <link linkend="variable.template.dir">
+    <parameter>$template_dir</parameter></link>.
    </para>
 
    <example>
-    <title>Editing /web/www.example.com/smarty/guestbook/templates/index.tpl</title>
+    <title>Our /web/www.example.com/smarty/guestbook/templates/index.tpl</title>
     <screen>
 <![CDATA[
-
 {* Smarty *}
 
 Hello {$name}, welcome to Smarty!
@@ -412,7 +423,7 @@ Hello {$name}, welcome to Smarty!
    <note>
     <title>Technical Note</title>
     <para>
-     {* Smarty *} is a template
+     <literal>{* Smarty *}</literal> is a template
      <link linkend="language.syntax.comments">comment</link>.
      It is not required, but it is good
      practice to start all your template files with this comment. It makes
@@ -423,10 +434,10 @@ Hello {$name}, welcome to Smarty!
    </note>
 
    <para>
-    Now lets edit 'index.php'. We'll create an instance of Smarty, 
-    <link linkend="api.assign">assign</link> a
-    template variable and <link linkend="api.display">display</link>
-    the 'index.tpl' file. 
+    Now lets edit <filename>index.php</filename>. We'll create an instance of Smarty,
+    <link linkend="api.assign"><varname>assign()</varname></link> a
+    template variable and <link linkend="api.display"><varname>display()</varname></link>
+    the <filename>index.tpl</filename> file.
    </para>
 
    <example>
@@ -474,6 +485,8 @@ $smarty->display('index.tpl');
     You have completed the basic setup for Smarty!
    </para>
   </sect1>
+
+
   <sect1 id="installing.smarty.extended">
    <title>Extended Setup</title>
 
@@ -486,10 +499,10 @@ $smarty->display('index.tpl');
     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 <filename>setup.php</filename>. In our example environment,
-    "/php/includes" is in our include_path. Be sure you set this up too, or
-    use absolute file paths.
+    Lets create a new directory <filename>/php/includes/guestbook/</filename>
+     and make a new file called <filename>setup.php</filename>. In our example
+     environment, <filename>/php/includes</filename> is in our include_path.
+     Be sure you set this up too, or use absolute file paths.
    </para>
 
    <example>
@@ -532,7 +545,7 @@ class Smarty_GuestBook extends Smarty {
    </example>
 
   <para>
-   Now lets alter the index.php file to use setup.php:
+   Now lets alter the <filename>index.php</filename> file to use <filename>setup.php</filename>:
   </para>
 
   <example>
@@ -543,7 +556,7 @@ class Smarty_GuestBook extends Smarty {
 
 require('guestbook/setup.php');
 
-$smarty = new Smarty_GuestBook;
+$smarty = new Smarty_GuestBook();
 
 $smarty->assign('name','Ned');
 
@@ -555,7 +568,7 @@ $smarty->display('index.tpl');
 
   <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
+   <literal>Smarty_GuestBook()</literal> which automatically initializes everything for our
    application.
   </para>
 
diff --git a/docs/en/programmers/caching.xml b/docs/en/programmers/caching.xml
index 8cdd4029..61dc9f86 100644
--- a/docs/en/programmers/caching.xml
+++ b/docs/en/programmers/caching.xml
@@ -4,13 +4,14 @@
    <title>Caching</title>
    <para>
    Caching is used to speed up a call to <link
-   linkend="api.display">display()</link> or <link
-   linkend="api.fetch">fetch()</link> by saving its output to a file. If a
+   linkend="api.display"><varname>display()</varname></link> or <link
+   linkend="api.fetch"><varname>fetch()</varname></link> by saving its output
+   to a file. If a
    cached version of the call is available, that is displayed instead of
    regenerating the output. Caching can speed things up tremendously,
    especially templates with longer computation times. Since the output of
-   <link linkend="api.display">display()</link> or
-   <link linkend="api.fetch">fetch()</link> is cached,
+   <link linkend="api.display"><varname>display()</varname></link> or
+   <link linkend="api.fetch"><varname>fetch()</varname></link> is cached,
    one cache file could conceivably be made up
    of several template files, config files, etc.
    </para>
@@ -19,7 +20,7 @@
    caching and for how long. For instance, if you are displaying the front page
    of your website that does not change its content very often, it might work
    well to cache this page for an hour or more. On the other hand, if you are
-   displaying a page with a weather map containing new information by the
+   displaying a page with a timetable containing new information by the
    minute, it would not make sense to cache this page.
    </para>
 &programmers.caching.caching-setting-up;
diff --git a/docs/en/programmers/smarty-constants.xml b/docs/en/programmers/smarty-constants.xml
index a980c282..0840ac16 100644
--- a/docs/en/programmers/smarty-constants.xml
+++ b/docs/en/programmers/smarty-constants.xml
@@ -6,11 +6,11 @@
 <sect1 id="constant.smarty.dir">
   <title>SMARTY_DIR</title>
     <para>
-     This should be the <emphasis role="bold">full system path</emphasis>
+     This is the <emphasis role="bold">full system path</emphasis>
      to the location of the Smarty
-     class files. If this is not defined, then Smarty will attempt to
+     class files. If this is not defined in your script, then Smarty will attempt to
      determine the appropriate value automatically. If defined, the path
-     <emphasis role="bold">must end with a slash</emphasis>.
+     <emphasis role="bold">must end with a trailing slash/</emphasis>.
     </para>
     <example>
      <title>SMARTY_DIR</title>
@@ -18,12 +18,12 @@
 <![CDATA[
 <?php
 // set path to Smarty directory *nix style
-define('SMARTY_DIR', '/usr/local/lib/php/Smarty/libs/');
+define('SMARTY_DIR', '/usr/local/lib/php/Smarty-v.e.r/libs/');
 
 // path to Smarty windows style
-define('SMARTY_DIR', 'c:/webroot/libs/Smarty/libs/');
+define('SMARTY_DIR', 'c:/webroot/libs/Smarty-v.e.r/libs/');
 
-// include the smarty class Note 'S' is upper case
+// include the smarty class, note 'S' is upper case
 require_once(SMARTY_DIR . 'Smarty.class.php');
 ?>
 ]]>
@@ -31,22 +31,21 @@ require_once(SMARTY_DIR . 'Smarty.class.php');
     </example>
   <para>
   See also
-  <link linkend="language.variables.smarty.const">$smarty.const</link>
+  <link linkend="language.variables.smarty.const"><parameter>$smarty.const</parameter></link>
   and
   <link
-  linkend="variable.php.handling">$php_handling constants</link>
+  linkend="variable.php.handling"><parameter>$php_handling constants</parameter></link>
   </para>
 </sect1>
 
 <sect1 id="constant.smarty.core.dir">
     <title>SMARTY_CORE_DIR</title>
     <para>
-     This should be the full system path to the location of the Smarty core
+     This if the <emphasis>full system path</emphasis> to the location of the Smarty core
      files. If not defined, Smarty will default this constant to the
-     <emphasis>internals/</emphasis>
-     sub-directory below
-     <link linkend="constant.smarty.dir">SMARTY_DIR</link>.
-     If defined, the path must end with a slash.
+     <filename>internals/</filename>  sub-directory below
+     <link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link>.
+     If defined, the path must end with a slash/.
      Use this constant when manually including any of the core.* files.
     </para>
     <example>
@@ -65,7 +64,7 @@ require_once(SMARTY_CORE_DIR . 'core.get_microtime.php');
 
     <para>
     See also
-    <link linkend="language.variables.smarty.const">$smarty.const</link>
+    <link linkend="language.variables.smarty.const"><parameter>$smarty.const</parameter></link>
     </para>
    </sect1>
 </chapter>