commit 3.1 into the trunk

SMARTY2_BC_NOTES

@@ -1,23 +1,19 @@
-Smarty 2 and Smarty 3 are quite similar in implementation, but do have a few
-differences you need to be aware of when upgrading from Smarty 2 to Smarty 3.
-
 = Known incompatibilities with Smarty 2 =
 
 == Syntax ==
 
-The Smarty 3 API has been updated in various places. Some Smarty 2 API calls
-need to be updated to comply with Smarty 3. You will get a deprecation notice
-with old Smarty 2 API calls, and informed what the new one is. See the README that
-comes with Smarty 3 for more information.
+Smarty 3 API has a new syntax. Much of the Smarty 2 syntax is supported 
+by a wrapper but deprecated. See the README that comes with Smarty 3 for more 
+information.
 
 The {$array|@mod} syntax has always been a bit confusing, where an "@" is required
-to apply a modifier to an array instead of the individual array elements. Normally you
+to apply a modifier to an array instead of the individual elements. Normally you
 always want the modifier to apply to the variable regardless of its type. In Smarty 3,
 {$array|mod} and {$array|@mod} behave identical. It is safe to drop the "@" and the
 modifier will still apply to the array. If you really want the modifier to apply to
 each array element, you must loop the array in-template, or use a custom modifier that
-supports array iteration. Most smarty functions already escape array elements where
-necessary such as {html_options}
+supports array iteration. Most smarty functions already escape values where necessary
+such as {html_options}
 
 == PHP Version ==
 Smarty 3 is PHP 5 only. It will not work with PHP 4.
@@ -26,31 +22,30 @@ Smarty 3 is PHP 5 only. It will not work with PHP 4.
 The {php} tag is disabled by default. The use of {php} tags is
 deprecated. It can be enabled with $smarty->allow_php_tag=true.
 
-Variables inside {php} blocks no longer share scope with other
-{php} blocks on the page, so be aware of this change if you use them.
+But if you scatter PHP code which belongs together into several
+{php} tags it may not work any longer.
 
 == Delimiters and whitespace ==
-Smarty delimiters {} surrounded by whitespace are no longer treated as Smarty tags.
-Therefore, { foo } will be ignored by Smarty, but {foo} is recognized. This change
-makes Javascript/CSS easier to work with, eliminating the need for {literal}.
-This feature can be disabled by setting $smarty->auto_literal = false;
+Delimiters surrounded by whitespace are no longer treated as Smarty tags.
+Therefore, { foo } will not compile as a tag, you must use {foo}. This change
+Makes Javascript/CSS easier to work with, eliminating the need for {literal}.
+This can be disabled by setting $smarty->auto_literal = false;
 
 == Unquoted Strings ==
 Smarty 2 was a bit more forgiving (and ambiguous) when it comes to unquoted strings 
 in parameters. Smarty3 is more restrictive. You can still pass strings without quotes 
 so long as they contain no special characters. (anything outside of A-Za-z0-9_) 
 
-For example filename strings must be quoted:
-
+For example filename strings must be quoted
 <source lang="smarty">
-{assign var=foo value=baz} <-- works ok
-{include file="path/foo.tpl"} <-- needs quotes!
+{include file='path/foo.tpl'}
 </source>
 
 == Extending the Smarty class ==
-Smarty 3 follows standard PHP5 constructor rules. When extending the Smarty class,
-use __construct() as the class constructor name.  If you implement your own constructor,
-be certain to call parent::__construct() first.
+Smarty 3 makes use of the __construct method for initialization. If you are extending 
+the Smarty class, its constructor is not called implicitly if the your child class defines 
+its own constructor. In order to run Smarty's constructor, a call to parent::__construct() 
+within your child constructor is required. 
 
 <source lang="php">
 class MySmarty extends Smarty {
@@ -64,35 +59,41 @@ class MySmarty extends Smarty {
 </source>
 
 == Autoloader ==
-Smarty implements its own autoloader with spl_autoload_register. If you
-use an autoloader in your own application, you MUST register yours as well. Using
-__autoload() WILL FAIL. This is standard PHP5 autoloader procedure for shared libraries.
-See http://us3.php.net/manual/en/function.spl-autoload-register.php 
+Smarty 3 does register its own autoloader with spl_autoload_register. If your code has 
+an existing __autoload function then this function must be explicitly registered on 
+the __autoload stack. See http://us3.php.net/manual/en/function.spl-autoload-register.php 
+for further details.
 
 == Plugin Filenames ==
-Since Smarty 3 uses the default spl_autoloader, the plugin filenames are now required to be
-lower case. Smarty 2 allowed mixed case plugin names, you must rename them for Smarty 3.
+Smarty 3 optionally supports the PHP spl_autoloader. The autoloader requires filenames 
+to be lower case. Because of this, Smarty plugin file names must also be lowercase. 
+In Smarty 2, mixed case file names did work.
 
 == Scope of Special Smarty Variables ==
-In Smarty 2 the special Smarty variables $smarty.section.* and $smarty.foreach.*
-had global scope. If you had loops with the same name in subtemplates, you could accidentally 
-overwrite values of a parent template.
-
-In Smarty 3 these special Smarty variables now have local scope in the template which 
-is defining the loop. In the rare case you need these values in a subtemplate, you have to
-pass them as parameters.
+In Smarty 2 the special Smarty variables $smarty.section... and $smarty.foreach... 
+had global scope. If you had loops with the same name in subtemplates you could accidentally 
+overwrite values of parent template.
 
+In Smarty 3 these special Smarty variable have only local scope in the template which 
+is defining the loop. If you need their value in a subtemplate you have to pass them 
+as parameter.
 <source lang="smarty">
-{include file="path/foo.tpl" index=$smarty.section.foo.index}
+{include file='path/foo.tpl' index=$smarty.section.foo.index}
 </source>
 
 == SMARTY_RESOURCE_CHAR_SET ==
-Smarty 3 sets the constant SMARTY_RESOURCE_CHAR_SET to utf-8 as the default template charset. 
-This is now used with modifiers like escape as the default charset. If your templates use 
-another charset, make sure that you define the constant accordingly.
+Smarty 3 sets the constant SMARTY_RESOURCE_CHAR_SET to utf-8 as default template charset. 
+This is now used also on modifiers like escape as default charset. If your templates use 
+other charsets make sure that you define the constant accordingly. Otherwise you may not 
+get any output.
+
+== newline at {if} tags ==
+A \n was added to the compiled code of the {if},{else},{elseif},{/if} tags to get output of newlines as expected by the template source. 
+If one of the {if} tags is at the line end you will now get a newline in the HTML output.
 
 == trigger_error() ==
-The API function trigger_error() has been removed. It is still included in the Smarty2 API wrapper.
+The API function trigger_error() has been removed because it did just map to PHP trigger_error.
+However it's still included in the Smarty2 API wrapper.
 
 == Smarty constants ==
 The constants 

SMARTY3.0_BC_NOTES.txt

@@ -0,0 +1,24 @@
+== Smarty2 backward compatibility ==
+All Smarty2 specific API functions and deprecated functionallity has been moved
+to the SmartyBC class.
+
+== {php} Tag ==
+The {php} tag is no longer available in the standard Smarty calls. 
+The use of {php} tags is deprecated and only available in the SmartyBC class. 
+
+== {include_php} Tag ==
+The {include_php} tag is no longer available in the standard Smarty calls. 
+The use of {include_php} tags is deprecated and only available in the SmartyBC class. 
+
+== php template resource ==
+The support of the php template resource is removed.
+
+== $cache_dir, $compile_dir, $config_dir, $template_dir access ==
+The mentioned properties can't be accessed directly any longer. You must use
+corresponding getter/setters like addConfigDir(), setConfigDir(), getConfigDir()
+
+== obsolete Smarty class properties ==
+The following no longer used properties are removed:
+$allow_php_tag
+$allow_php_template
+$deprecation_notices