Item13897: Experimental rewrite of Foswiki::IncludeHandlers::doc

It was a hard to extend mess. Reimplemented using simple lexical parsing
based on Perl's regexps. It is now much easier to adapt it to the new
OO terminology and constructs.

The old behaviour can be returned back by setting
Foswiki::IncludeHandlers::doc::USER_LEXICAL_PARSER constant to 0. Could
also be controlled by some LSC value but I see no point in this.

- Slightly improved error handling by INCLUDE macro.

UnitTestContrib/test/unit/Fn_INCLUDE.pm

@@ -810,7 +810,25 @@ sub test_docInclude {
 
     my $class = 'Foswiki::IncludeHandlers::doc';
     my $text  = $this->test_topicObject->expandMacros("%INCLUDE{doc:$class}%");
-    my $expected = <<"EXPECTED";
+    my $expected;
+
+    # Use eval to avoid pre-declaration of the module or Foswiki::load_package
+    # would detect it as already loaded.
+    if ( eval "&Foswiki::IncludeHandlers::doc::USE_LEXICAL_PARSER" ) {
+        $expected = <<"EXPECTED";
+
+---+ =internal Package= Foswiki::IncludeHandlers::doc
+
+
+This package is designed to be lazy-loaded when Foswiki sees
+an INCLUDE macro with the doc: protocol. It implements a single
+method INCLUDE which generates perl documentation for a Foswiki class.
+
+EXPECTED
+
+    }
+    else {
+        $expected = <<"EXPECTED";
 
 ---+ =internal package= Foswiki::IncludeHandlers::doc
 
@@ -819,6 +837,7 @@ an INCLUDE macro with the doc: protocol. It implements a single
 method INCLUDE which generates perl documentation for a Foswiki class.
 
 EXPECTED
+    }
     $this->assert_str_equals( $expected, $text );
 
     # Add a pattern