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 
-by a wrapper but deprecated. See the README that comes with Smarty 3 for more 
-information.
+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.
 
 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
-such as {html_options}
+supports array iteration. Most smarty functions already escape array elements where
+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
-{php} tags it may not work any longer.
+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.
 
 == Delimiters and whitespace ==
-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;
+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;
 
 == 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 
-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. 
+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.
 
 <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 
-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.
+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 
 
 == Plugin Filenames ==
-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.
+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.
 
 == 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 parent template.
+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 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. 
-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.
+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.
 
 == trigger_error() ==
-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.
+The API function trigger_error() has been removed. It is still included in the Smarty2 API wrapper.
 
 == Smarty constants ==
 The constants