Update Pod-Simple to CPAN version 3.15

  [DELTA]

  2010-11-11   David E. Wheeler <david@justatheory.org>
        * Release 3.15

        Removed "perlpod.pod" and "perlpodspec.pod". These now just live
        in the Perl core.

        Fixed stylesheet names output by HTMLBatch to match the names of
        the actual stylesheet files (broken in 3.09). Thanks to Kevin Ryde
        for the report (RT #56725).

        Added missing closing slash to the CSS links in the XHTML output.
        Thanks to HarleyPig for the patch!

        Added parens around bar "qw(...)" in t/xhtml05.t. Thanks to Jerry
        D. Hedden for the patch.

        Improved the Pod::Simple::HTML docs. Thanks to Gabor Szabo for the
        patch.

        Pod::Simple::XHTML now properly encodes entities in URLs in the
        anchor tag. Thanks to John McNamara for the report (RT-60249).

        Pod::Simple::HTML and XHTML now strip whitespace from the end of
        section names that appear as anchor names for headers (in HTML)
        and IDs (in XHTML). Such whitespace appeared when "X<>" entities
        were stripped out but not the space between them (RT-56572).

        Make test "t/search50.t" always pass on case-insensitive file
        systems rather than just skip VMS.

1 files changed, 162 insertions, 9 deletions

diff --git a/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm b/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm
index b1a75cb4e3..21bf7c24fd 100644
--- a/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm
+++ b/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm
@@ -10,7 +10,7 @@ use vars qw(
   $Doctype_decl  $Content_decl
 );
 @ISA = ('Pod::Simple::PullParser');
-$VERSION = '3.14';
+$VERSION = '3.15';
 
 BEGIN {
   if(defined &DEBUG) { } # no-op
@@ -81,7 +81,7 @@ __PACKAGE__->_accessorize(
     #  out of apparently longstanding habit)
 
  'html_css', # URL of CSS file to point to
- 'html_javascript', # URL of CSS file to point to
+ 'html_javascript', # URL of Javascript file to point to
 
  'force_title',   # should already be &-escaped
  'default_title', # should already be &-escaped
@@ -685,6 +685,8 @@ sub section_escape {
 
 sub section_name_tidy {
   my($self, $section) = @_;
+  $section =~ s/^\s+//;
+  $section =~ s/\s+$//;
   $section =~ tr/ /_/;
   $section =~ tr/\x00-\x1F\x80-\x9F//d if 'A' eq chr(65); # drop crazy characters
   $section = $self->unicode_escape_url($section);
@@ -897,25 +899,176 @@ TODO
 
 =head1 CALLING FROM PERL
 
-TODO   make a new object, set any options, and use parse_from_file
+=head2 Minimal code
 
+  use Pod::Simple::HTML;
+  my $html;
+  $p->output_string(\$html);
+  $p->parse_from_file('path/to/Module/Name.pm');
+  open my $out, '>', 'out.html' or die;
+  print $out $html;
+
+=head2 More detailed example
+
+  use Pod::Simple::HTML;
+
+Set the content type:
+
+  $Pod::Simple::HTML::Content_decl =  q{<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" >};
+
+  my $p = Pod::Simple::HTML->new;
+
+Include a single javascript source:
+
+  $p->html_javascript('http://abc.com/a.js');
+
+Or insert multiple javascript source in the header 
+(or for that matter include anything, thought this is not recommended)
+
+  $p->html_javascript('
+      <script type="text/javascript" src="http://abc.com/b.js"></script>
+      <script type="text/javascript" src="http://abc.com/c.js"></script>');
+
+Include a single css source in the header:
+
+  $p->html_css('/style.css');
+
+or insert multiple css sources:
+
+  $p->html_css('
+      <link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://remote.server.com/jquery.css">
+      <link rel="stylesheet" type="text/css" title="pod_stylesheet" href="/style.css">');
+
+Tell the parser where should the output go. In this case it will be placed in the $html variable:
+
+  my $html;
+  $p->output_string(\$html);
+
+Parse and process a file with pod in it:
+
+  $p->parse_from_file('path/to/Module/Name.pm');
 
 =head1 METHODS
 
 TODO
 all (most?) accessorized methods
 
+The following variables need to be set B<before> the call to the ->new constructor.
+
+Set the string that is included before the opening <html> tag:
+
+  $Pod::Simple::HTML::Doctype_decl = qq{<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
+	 "http://www.w3.org/TR/html4/loose.dtd">\n};
+
+Set the content-type in the HTML head: (defaults to ISO-8859-1)
+
+  $Pod::Simple::HTML::Content_decl =  q{<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" >};
+
+Set the value that will be ebedded in the opening tags of F, C tags and verbatim text.
+F maps to <em>, C maps to <code>, Verbatim text maps to <pre> (Computerese defaults to "")
+
+  $Pod::Simple::HTML::Computerese =  ' class="some_class_name';
+
+=head2 html_css
+
+=head2 html_javascript
+
+=head2 title_prefix
+
+=head2 title_postfix
+
+=head2 html_header_before_title
+
+This includes everything before the <title> opening tag including the Document type
+and including the opening <title> tag. The following call will set it to be a simple HTML
+file:
+
+  $p->html_header_before_title('<html><head><title>');
+
+=head2 html_h_level
+
+Normally =head1 will become <h1>, =head2 will become <h2> etc.
+Using the html_h_level method will change these levels setting the h level
+of =head1 tags:
+
+  $p->html_h_level(3);
+
+Will make sure that =head1 will become <h3> and =head2 will become <h4> etc...
+
+
+=head2 index
+
+Set it to some true value if you want to have an index (in reality a table of contents)
+to be added at the top of the generated HTML.
+
+  $p->index(1);
+
+=head2 html_header_after_title
+
+Includes the closing tag of </title> and throught the rest of the head
+till the opening of the body
+
+  $p->html_header_after_title('</title>...</head><body id="my_id">');
+
+=head2 html_footer
+
+The very end of the document:
+
+  $p->html_footer( qq[\n<!-- end doc -->\n\n</body></html>\n] );
 
 =head1 SUBCLASSING
 
-TODO
+Can use any of the methods described above but for further customization
+one needs to override some of the methods:
+
+  package My::Pod;
+  use strict;
+  use warnings;
+
+  use base 'Pod::Simple::HTML';
+
+  # needs to return a URL string such
+  # http://some.other.com/page.html
+  # #anchor_in_the_same_file
+  # /internal/ref.html
+  sub do_pod_link {
+    # My::Pod object and Pod::Simple::PullParserStartToken object
+    my ($self, $link) = @_;
+
+    say $link->tagname;          # will be L for links
+    say $link->attr('to');       # 
+    say $link->attr('type');     # will be 'pod' always
+    say $link->attr('section');
+
+    # Links local to our web site
+    if ($link->tagname eq 'L' and $link->attr('type') eq 'pod') {
+      my $to = $link->attr('to');
+      if ($to =~ /^Padre::/) {
+          $to =~ s{::}{/}g;
+          return "/docs/Padre/$to.html";
+      }
+    }
 
- can just set any of:  html_css html_javascript title_prefix
-  'html_header_before_title',
-  'html_header_after_title',
-  'html_footer',
+    # all other links are generated by the parent class
+    my $ret = $self->SUPER::do_pod_link($link);
+    return $ret;
+  }
 
-maybe override do_pod_link
+  1;
+
+Meanwhile in script.pl:
+
+  use My::Pod;
+
+  my $p = My::Pod->new;
+
+  my $html;
+  $p->output_string(\$html);
+  $p->parse_from_file('path/to/Module/Name.pm');
+  open my $out, '>', 'out.html' or die;
+  print $out $html;
+
+TODO
 
 maybe override do_beginning do_end