do some updates to the text

SMARTY2_BC_NOTES

@@ -1,19 +1,23 @@
+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 ==
 
-Smarty 3 API has a new syntax. Much of the Smarty 2 syntax is supported 
+The Smarty 3 API has been updated in various places. Some Smarty 2 API calls
-by a wrapper but deprecated. See the README that comes with Smarty 3 for more 
+need to be updated to comply with Smarty 3. You will get a deprecation notice
-information.
+with old Smarty 2 API calls, and informed what the new one is. 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 elements. Normally you
+to apply a modifier to an array instead of the individual array 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 values where necessary
+supports array iteration. Most smarty functions already escape array elements where
-such as {html_options}
+necessary such as {html_options}
 
 == PHP Version ==
 Smarty 3 is PHP 5 only. It will not work with PHP 4.
@@ -22,30 +26,31 @@ 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.
 
-But if you scatter PHP code which belongs together into several
+Variables inside {php} blocks no longer share scope with other
-{php} tags it may not work any longer.
+{php} blocks on the page, so be aware of this change if you use them.
 
 == Delimiters and whitespace ==
-Delimiters surrounded by whitespace are no longer treated as Smarty tags.
+Smarty 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
+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}.
+makes Javascript/CSS easier to work with, eliminating the need for {literal}.
-This can be disabled by setting $smarty->auto_literal = false;
+This feature 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">
-{include file='path/foo.tpl'}
+{assign var=foo value=baz} <-- works ok
+{include file="path/foo.tpl"} <-- needs quotes!
 </source>
 
 == Extending the Smarty class ==
-Smarty 3 makes use of the __construct method for initialization. If you are extending 
+Smarty 3 follows standard PHP5 constructor rules. When extending the Smarty class,
-the Smarty class, its constructor is not called implicitly if the your child class defines 
+use __construct() as the class constructor name.  If you implement your own constructor,
-its own constructor. In order to run Smarty's constructor, a call to parent::__construct() 
+be certain to call parent::__construct() first.
-within your child constructor is required. 
 
 <source lang="php">
 class MySmarty extends Smarty {
@@ -59,41 +64,35 @@ class MySmarty extends Smarty {
 </source>
 
 == Autoloader ==
-Smarty 3 does register its own autoloader with spl_autoload_register. If your code has 
+Smarty implements its own autoloader with spl_autoload_register. If you
-an existing __autoload function then this function must be explicitly registered on 
+use an autoloader in your own application, you MUST register yours as well. Using
-the __autoload stack. See http://us3.php.net/manual/en/function.spl-autoload-register.php 
+__autoload() WILL FAIL. This is standard PHP5 autoloader procedure for shared libraries.
-for further details.
+See http://us3.php.net/manual/en/function.spl-autoload-register.php 
 
 == Plugin Filenames ==
-Smarty 3 optionally supports the PHP spl_autoloader. The autoloader requires filenames 
+Since Smarty 3 uses the default spl_autoloader, the plugin filenames are now required to be
-to be lower case. Because of this, Smarty plugin file names must also be lowercase. 
+lower case. Smarty 2 allowed mixed case plugin names, you must rename them for Smarty 3.
-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... 
+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 
+had global scope. If you had loops with the same name in subtemplates, you could accidentally 
-overwrite values of parent template.
+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 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 default template charset. 
+Smarty 3 sets the constant SMARTY_RESOURCE_CHAR_SET to utf-8 as the default template charset. 
-This is now used also on modifiers like escape as default charset. If your templates use 
+This is now used with modifiers like escape as the default charset. If your templates use 
-other charsets make sure that you define the constant accordingly. Otherwise you may not 
+another charset, make sure that you define the constant accordingly.
-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 because it did just map to PHP trigger_error.
+The API function trigger_error() has been removed. It is still included in the Smarty2 API wrapper.
-However it's still included in the Smarty2 API wrapper.
 
 == Smarty constants ==
 The constants