| Subject: | [PATCH] add ability to produce fragments that start below <h1> |
| Date: | Thu, 03 Aug 2006 22:48:41 -0500 |
| To: | cpan [...] bbc.co.uk, bugs-pod-xhtml [...] rt.cpan.org |
| From: | Jonathan Rockway <jon [...] jrock.us> |
Message body not shown because it is not plain text.
Hello,
In an application I'm writing, I need to be able to incorporate POD
fragments that fit into the document outline. This means that =head1
needs to be translated to <h2>, etc.
Attached is a patch to Pod::Xhtml that allows you to pass it a
"TopHeading" argument (when in fragment mode) that specifies what the
top-level heading is. The default is "1", which results in the document
starting with <h1 id="foo">foo</h1>, as per the current behavior. If
you specify "2", the document starts with <h2 id="foo">foo</h2><h3>This
is a subsection of foo</h3>... and so on. If the parser goes past <h6>,
all deeper headings will be truncated to <h6> to ensure that the XHTML
remains valid.
Anyway, thanks for your excellent module!
Regards,
Jonathan Rockway
--- Pod-Xhtml-1.52-orig/lib/Pod/Xhtml.pm 2006-07-12 07:13:37.000000000 -0500
+++ Pod-Xhtml-1.52/lib/Pod/Xhtml.pm 2006-08-03 22:35:54.000000000 -0500
@@ -3,6 +3,7 @@
use strict;
use Pod::Parser;
use Pod::ParseUtils;
+use Carp;
use vars qw/@ISA %COMMANDS %SEQ $VERSION $FirstAnchorId $ContentSuffix/;
$FirstAnchorId = "TOP";
@@ -59,6 +60,9 @@
$self->{FragmentOnly} = 0 unless defined $self->{FragmentOnly};
$self->{HeadText} = $self->{BodyOpenText} = $self->{BodyCloseText} = '';
$self->{LinkParser} ||= new Pod::Hyperlink;
+ $self->{TopHeading} ||= 1;
+ $self->{TopHeading} = int $self->{TopHeading}; # heading level must be an integer
+ croak "TopHeading must be greater than zero" if $self->{TopHeading} < 1; # (prevent negative heading levels)
$self->SUPER::initialize();
}
@@ -197,13 +201,16 @@
for ($command) {
my $data_para = @{$self->{dataSections}}; # inside a data paragraph?
/^head1/ && !$data_para && do {
+ my $top_heading = 'h'. $self->{TopHeading};
+ $top_heading = 'h1' if !$self->{FragmentOnly}; # ignore TopHeading when not in fragment mode
+
# if ANY sections are open then close the previously opened div
$self->{buffer} .= "\n</div>\n" unless ( @{ $self->{sections} } == 1 );
$anchor = $self->_addSection( 'head1', $paragraph );
my $anchorContent = $self->_addSection( '', $paragraph . $ContentSuffix);
-
- $self->{buffer} .= qq(<h1 id="$anchor">$paragraph</h1>)
+
+ $self->{buffer} .= qq(<$top_heading id="$anchor">$paragraph</$top_heading>)
.($self->{TopLinks} ? $self->{TopLinks} : '')."\n"
."<div id=\"$anchorContent\">\n";
@@ -212,7 +219,10 @@
};
/^head([234])/ && !$data_para && do {
my $head_level = $1;
-
+ if($self->{FragmentOnly}){
+ $head_level += ($self->{TopHeading} - 1);
+ $head_level = 6 if $head_level > 6;
+ }
# if ANY sections are open then close the previously opened div
$self->{buffer} .= "\n</div>\n" unless ( @{ $self->{sections} } == 1 );
@@ -797,6 +807,21 @@
server-side include etc). There is no HEAD element nor any BODY or HTML
tags. Any text added with the add*Text methods will B<not> be output.
+
+=item TopHeading
+
+Allows you to set the starting heading level when in fragment mode.
+For example, if your document already has h1 tags and you want the
+generated POD to nest inside the outline, you can specify
+
+ TopHeading => 2
+
+and C<=head1> will be tagged with h2 tags, C<=head3> with h3, and so
+on.
+
+Note that XHTML doesn't allow for heading tags past h6, so h7 and up
+will be translated to h6 as necessary.
+
=item TopLinks
At each section head this text is added to provide a link back to the top.