update ChangeLog, update documentation

NEWS

@@ -1,5 +1,9 @@
+    - changed Smarty to compile templates at runtime, allowing for arbitrary
+      template resources. Also added fix for LOCK_EX under windows and changed
+      a couple file permissions for security. (Monte)
     - allow arbitrary date strings to date_format, html_select_date and
       html_select_time (Monte)
+
 Version 1.3.2
 -------------
     - fixed a bug that caused some nested includes to loop infinitely. (Andrei)

docs.sgml

@@ -137,8 +137,8 @@
             caching</link>, Smarty will store a copy of the generated template
             output, and use this until the copy <link
             linkend="setting.cache.lifetime">expires</link>, regenerating a new
-            one. The default cache expire time is one hour, and can be
+            one. The default cache expire time can be configured from the
-            configured from the class. The exception to the rule is the <link
+            class. The exception to the rule is the <link
             linkend="function.insert">insert</link> tag. Anything generated by
             the insert tag is not cached, but run dynamically on every
             invocation, even within cached content.
@@ -242,8 +242,11 @@ chmod 700 cache
 		<sect2 id="setting.template.dir">
 			<title>$template_dir</title>
 			<para>
-				This is the name of the directory where template files are located.
+                This is the name of the default template directory. If you do
-				By default this is "./templates".
+                not supply a resource type when including files, they will be
+                found here. By default this is "./templates", meaning that it
+                will look for the templates directory in the same directory as
+                the executing php script.
 			</para>
 			<para>
                 TECHNICAL NOTE: It is not mandatory to put this directory under
@@ -253,9 +256,11 @@ chmod 700 cache
 		<sect2 id="setting.compile.dir">
 			<title>$compile_dir</title>
 			<para>
-				This is the name of the directory where compiled templates are
+                This is the name of the directory where compiled templates are
-				located. By default this is "./templates_c". This was
+                located. By default this is "./templates_c", meaning that it
-				added to Smarty version 1.2.1.
+                will look for the compile directory in the same directory as
+                the executing php script. This was added to Smarty version
+                1.2.1.
 			</para>
 			<para>
                 TECHNICAL NOTE: This setting must be either a relative or
@@ -269,8 +274,10 @@ chmod 700 cache
 		<sect2 id="setting.config.dir">
 			<title>$config_dir</title>
 			<para>
-				This is the directory used to store config files used in the templates.
+                This is the directory used to store config files used in the
-				Default is "./configs".
+                templates. Default is "./configs", meaning that it will look
+                for the configs directory in the same directory as the
+                executing php script.
 			</para>
 			<para>
                 TECHNICAL NOTE: It is not mandatory to put this directory under
@@ -290,24 +297,23 @@ chmod 700 cache
 		<sect2>
 			<title>$compile_check</title>
 			<para>
-				Upon each invocation of the PHP application, Smarty recursively
+                Upon each invocation of the PHP application, Smarty tests to
-				traverses the template directory and its subdirectories and
+                see if the current template has changed (later time stamp)
-				searches for templates that have changed (later time stamp)
+                since the last time it was compiled. If it has changed, it
-				since the last time they were compiled. For each one that has
+                recompiles that template. By default this variable is set to
-				changed, it recompiles that template. By default this variable
+                true. Once an application is put into production and all
-				is set to true. Once an application is put into production and
+                templates are initially compiled, the compile_check step is no
-				it is initially compiled, the compile_check step is no longer
+                longer needed. Be sure to set $compile_check to "false" to
-				needed. Be sure to set $compile_check to "false" to improve
+                improve performance! Note that if you change this to "false"
-				performance! Note that if you change this to "false" and a
+                and a template file is changed, you will *not* see the change
-				template file is changed, you will *not* see the change since
+                since the template will not get recompiled. See <link
-				the template will not get recompiled. See <link
+                linkend="setting.force.compile">$force_compile</link>
-				linkend="setting.force.compile">$force_compile</link>
 			</para>
 		</sect2>
 		<sect2 id="setting.force.compile">
 			<title>$force_compile</title>
 			<para>
-				This forces Smarty to compile all templates on every
+				This forces Smarty to (re)compile each template on every
 				invocation. This setting overrides $compile_check. By default
 				this is disabled. This is handy for development and debugging.
 				It should never be used in a production environment.
@@ -328,9 +334,10 @@ chmod 700 cache
 		<sect2 id="setting.cache.dir">
 			<title>$cache_dir</title>
 			<para>
-				This is the name of the directory where template caches are
+                This is the name of the directory where template caches are
-				located. By default this is "./cache". This was
+                stored. By default this is "./cache", meaning that it will
-				added to Smarty version 1.3.0.
+                look for the cache directory in the same directory as the
+                executing php script. This was added to Smarty version 1.3.0.
 			</para>
 			<para>
                 TECHNICAL NOTE: This setting must be either a relative or
@@ -352,25 +359,6 @@ chmod 700 cache
 				added to Smarty 1.3.0.
 			</para>
 		</sect2>
-		<sect2 id="setting.tpl.file.ext">
-			<title>$tpl_file_ext</title>
-			<para>
-				This is the extention used for template files. By default this
-				is ".tpl". All other files in the template directory are
-				ignored.
-			</para>
-		</sect2>
-		<sect2 id="setting.allow.php">
-			<title>$allow_php</title>
-			<para>
-				Whether or not to allow PHP code in the templates. If set to
-				false, PHP code is escaped and not interpreted. Embedding PHP
-				code into templates is highly discouraged. Use <link
-				linkend="custom.functions">custom functions</link> or <link
-				linkend="variable.modifiers">modifiers</link> instead. Default
-				is "false".
-			</para>
-		</sect2>
 		<sect2 id="setting.php.handling">
 			<title>$php_handling</title>
 			<para>
@@ -574,8 +562,8 @@ $smarty->clear_all_assign();
 			</funcsynopsis>
 			<para>
                 Use this to dynamically register functions with Smarty. Pass in
-                the Smarty function name, followed by the actual function name
+                the template function name, followed by the actual PHP function
-                that it is mapped to.
+                name that it will map to.
 			</para>
 <example>
 <title>register_function</title>
@@ -683,8 +671,8 @@ $smarty->unregister_modifier("fetch");
 			</funcsynopsis>
 			<para>
                 Use this to dynamically register modifiers with Smarty. Pass in
-                the Smarty modifier name, followed by the actual function name
+                the template modifier name, followed by the actual PHP function name
-                that it is mapped to.
+                that it will map to.
 			</para>
 <example>
 <title>register_modifier</title>
@@ -709,7 +697,7 @@ $smarty->register_modifier("sslash","stripslashes");
 			</funcsynopsis>
 			<para>
                 Use this to dynamically unregister modifiers with Smarty. Pass in
-                the Smarty modifier name.
+                the template modifier name.
 			</para>
 <example>
 <title>unregister_modifier</title>
@@ -804,11 +792,11 @@ var_dump($tpl_vars);
 			</funcprototype>
 			</funcsynopsis>
 			<para>
-				This displays the template. Supply a path relative to the
+                This displays the template. Supply a valid <link
-				<link linkend="setting.template.dir">template directory</link>.
+                linkend="section.template.resources"> template resource</link>
-                As an optional second parameter, you can pass a cache id.
+                type and path. As an optional second parameter, you can pass a
-                See the <link linkend="section.caching">caching section</link> for
+                cache id. See the <link linkend="section.caching">caching
-                more information.
+                section</link> for more information.
 			</para>
 <example>
 <title>display</title>
@@ -852,8 +840,11 @@ $smarty->display("index.tpl");
 			</funcsynopsis>
 			<para>
                 This returns the template output instead of displaying it.
-                Supply a path relative to the <link
+                Supply a valid <link
-                linkend="setting.template.dir">template directory</link>
+                linkend="section.template.resources">template resource</link>
+                type and path. As an optional second parameter, you can pass a
+                cache id. See the <link linkend="section.caching">caching
+                section</link> for more information.
 			</para>
 <example>
 <title>fetch</title>
@@ -892,6 +883,59 @@ echo $output;
 </example>
 		</sect2>
 	</sect1>
+	<sect1 id="section.template.resources">
+		<title>Smarty Template Resources</title>
+        <para>
+        Your templates may come from a variety of sources. When you display or
+        fetch a template, or when you include a template from within another
+        template, you supply a resource type, followed by the appropriate path
+        and template name. Template resources were added to Smarty 1.4.0.
+        </para>
+		<sect2>
+			<title>Templates from $template_dir</title>
+			<para>
+            Templates from the $template_dir do not require a template resource.
+            Just supply the path to the template you want to use relative to the
+            $template_dir root directory.
+            </para>
+<example>
+
+<title>using templates from $template_dir</title>
+<programlisting>
+
+// from PHP script
+$smarty->display("index.tpl");
+$smarty->display("admin/menu.tpl");
+
+{* from within Smarty template *}
+{include file="index.tpl"}
+
+</programlisting>
+</example>
+        </sect2>
+		<sect2>
+			<title>Templates from any directory</title>
+			<para>
+            Templates outside of the $template_dir require the file: template
+            resource type, followed by the absolute path and name of the
+            template.
+            </para>
+<example>
+
+<title>using templates from any directory</title>
+<programlisting>
+
+// from PHP script
+$smarty->display("file:/export/templates/index.tpl");
+$smarty->display("file:/path/to/my/templates/menu.tpl");
+
+{* from within Smarty template *}
+{include file="file:/usr/local/share/templates/navigation.tpl"}
+
+</programlisting>
+</example>
+        </sect2>
+    </sect1>
 </chapter>
 <chapter>
 	<title>Smarty Templates</title>
@@ -2989,9 +3033,11 @@ Dealers Will Hear Car Talk at Noon.
                 </tgroup>
             </informaltable>
 			<para>
-            This formats a date and time into the given strftime() format. All
+            This formats a date and time into the given strftime() format.
-            dates should be passed to Smarty as a timestamp so that the
+            Dates can be passed to Smarty as unix timestamps, mysql timestamps
-            template designer has full control of how this date is formatted.
+            or any string made up of month day year (parsable by strtotime).
+            Designers can then use date_format to have complete control of the
+            formatting of the date.
 			</para>
 <example>
 <title>date_format</title>
@@ -3090,10 +3136,10 @@ is the first week that has at least 4 days in the current year, and with Monday
 %% - a literal `%' character 
 
 
-PROGRAMMERS NOTE: date_format is a wrapper to PHP's strftime() function. You
+PROGRAMMERS NOTE: date_format is essentially a wrapper to PHP's strftime()
-may have more or less conversion specifiers available depending on your
+function. You may have more or less conversion specifiers available depending
-system's strftime() function where PHP was compiled. Check your system's manpage
+on your system's strftime() function where PHP was compiled. Check your
-for a full list of valid specifiers.
+system's manpage for a full list of valid specifiers.
 </programlisting>
 </example>
 
@@ -3616,7 +3662,8 @@ Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75
 	<sect1>
 		<title>Dates</title>
 		<para>
-		As a rule of thumb, always pass dates to Smarty as timestamps.
+        Dates can be passed to Smarty as unix timestamps, mysql timestamps,
+        or a parsable string made of month day and year (parsable by strtotime())
 		This allows template designers to use <link
 		linkend="date.format">date_format</link> for full control over date
 		formatting, and also makes it easy to compare dates if necessary.