Improve auto-paragraph to preserve newlines and handle edge-cases better.

This is a very large commit that includes numerous improvements to the
AutoParagraph injector.  These are:

* Rewritten flow control of the injector to use almost exclusively
  binary conditionals.
* Improved inline documentation with "State" comments, which give concise
  examples of what the token stack looks like at flow points.
* Documentation for all flow branches, even those with no actions.
* Factoring out of common operations to improve readability, especially the
  new iterator private methods.
* Expanded test-suite which covers new flow points, and corrects some errors
  in previous cases.

Signed-off-by: Edward Z. Yang <edwardzyang@thewritingpot.com>

tests/HTMLPurifier/ComplexHarness.php

@@ -35,16 +35,6 @@ class HTMLPurifier_ComplexHarness extends HTMLPurifier_Harness
      */
     protected $lexer;
     
-    /**
-     * Default config to fall back on if no config is available
-     */
-    protected $config;
-    
-    /**
-     * Default context to fall back on if no context is available
-     */
-    protected $context;
-    
     public function __construct() {
         $this->lexer     = new HTMLPurifier_Lexer_DirectLex();
         parent::__construct();
@@ -88,7 +78,6 @@ class HTMLPurifier_ComplexHarness extends HTMLPurifier_Harness
                 $expect = $this->generate($expect);
             }
         }
-        
         $this->assertIdentical($expect, $result);
         
     }