summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Pod/Simple/HTML.pm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Pod/Simple/HTML.pm')
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Simple/HTML.pm173
1 files changed, 163 insertions, 10 deletions
diff --git a/Master/tlpkg/tlperl/lib/Pod/Simple/HTML.pm b/Master/tlpkg/tlperl/lib/Pod/Simple/HTML.pm
index b1a75cb4e39..9d7d069645a 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Simple/HTML.pm
+++ b/Master/tlpkg/tlperl/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.16';
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 $p = Pod::Simple::HTML->new;
+ $p->output_string(\my $html);
+ $p->parse_file('path/to/Module/Name.pm');
+ open my $out, '>', 'out.html' or die "Cannot open 'out.html': $!\n";
+ 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_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 through 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_file('path/to/Module/Name.pm');
+ open my $out, '>', 'out.html' or die;
+ print $out $html;
+
+TODO
maybe override do_beginning do_end
@@ -952,7 +1105,7 @@ merchantability or fitness for a particular purpose.
=head1 ACKNOWLEDGEMENTS
-Thanks to L<Hurricane Electrict|http://he.net/> for permission to use its
+Thanks to L<Hurricane Electric|http://he.net/> for permission to use its
L<Linux man pages online|http://man.he.net/> site for man page links.
Thanks to L<search.cpan.org|http://search.cpan.org/> for permission to use the