Pod-Xhtml-1.60/0000755016522100007720000000000011424067100014520 5ustar jamielengineers00000000000000Pod-Xhtml-1.60/t/0000755016522100007720000000000011424067100014763 5ustar jamielengineers00000000000000Pod-Xhtml-1.60/t/pod_coverage.t0000644016522100007720000000076711424067054017627 0ustar jamielengineers00000000000000#!/usr/local/bin/perl -w #$Id: pod_coverage.t,v 1.3 2006/08/29 12:48:11 andreww Exp $ use Test::More; eval "use Test::Pod::Coverage 1.00"; plan skip_all => "Test::Pod::Coverage 1.00 required for testing POD Coverage" if $@; # Methods documented in Pod::Parser my @pod_parser = map "^$_\$", qw(command initialize end_pod textblock verbatim parse_tree); # Private methods my @private = map "^$_\$", qw(resetMe seq[A-Z]); all_pod_coverage_ok({also_private => [ qr/^[A-Z_]+$/, @private, @pod_parser ]}); Pod-Xhtml-1.60/t/02links.t0000644016522100007720000000623611424067054016451 0ustar jamielengineers00000000000000#!/usr/local/bin/perl -w #$Id: 02links.t,v 1.9 2006/08/29 12:48:11 andreww Exp $ use strict; use lib qw(./lib ../lib); use Test; use Pod::Xhtml; use Getopt::Std; use File::Basename; getopts('tTs', \my %opt); if ($opt{t} || $opt{T}) { require Log::Trace; import Log::Trace print => {Deep => $opt{T}}; } chdir ( dirname ( $0 ) ); require Test_LinkParser; plan tests => 16; my $pod_links = new Test_LinkParser(); my $parser = new Pod::Xhtml( LinkParser => $pod_links ); # Links to manpages ok($parser->seqL('Pod::Xhtml') eq 'Pod::Xhtml'); ok($parser->seqL('XHTML Podlator|Pod::Xhtml') eq 'XHTML Podlator (Pod::Xhtml)'); ok($parser->seqL('crontab(5)') eq 'crontab(5)'); # Links to section in other manpages ok($parser->seqL('Pod::Xhtml/"SEE ALSO"') eq 'SEE ALSO in Pod::Xhtml'); ok($parser->seqL('alt text|Pod::Xhtml/"SEE ALSO"') eq 'alt text (SEE ALSO in Pod::Xhtml)'); ok($parser->seqL('Pod::Xhtml/SYNOPSIS') eq 'SYNOPSIS in Pod::Xhtml'); ok($parser->seqL('alt text|Pod::Xhtml/SYNOPSIS') eq 'alt text (SYNOPSIS in Pod::Xhtml)'); # Links to sections in this manpage # Since 1.41, these are fully resolved at the end of the POD parse ok($parser->seqL('/"User Guide"') eq 'User Guide'); ok($parser->seqL('alt text|/"User Guide"') eq 'alt text'); ok($parser->seqL('/Notes') eq 'Notes'); ok($parser->seqL('alt text|/Notes') eq 'alt text'); ok($parser->seqL('"Installation Guide"') eq 'Installation Guide'); ok($parser->seqL('alt text|"Installation Guide"') eq 'alt text'); # Links to web pages ok($parser->seqL('http://bbc.co.uk/') eq 'http://bbc.co.uk/'); ok($parser->seqL('http://bbc.co.uk/#top') eq 'http://bbc.co.uk/#top'); my $pod_output = 'links.out'; open(OUT, '+>'.$pod_output) or die("Can't open $pod_output: $!"); $parser->parse_from_filehandle(\*DATA, \*OUT); seek OUT, 0, 0; my $output = do {local $/; }; close OUT; TRACE("Double encoding output ($pod_output):\n", $output); ok(index($output, canned_links()) > -1); unlink $pod_output unless $opt{'s'}; sub canned_links { return <Test 1

http://www.bbc.co.uk/opensource/test?ARG=VAL&ARG2=VAL2

Test 2

Escaping Args & Values

Test 3

whatisan&doinghere

Test 4

"AUTHOR & ACKNOWLEDGEMENTS" in Pod::Xhtml

LINKS } # Log::Trace stubs sub TRACE {} sub DUMP {} __DATA__ =head1 DOUBLE ENCODING TEST Test 1 LARG2=VAL2> Test 2 L Values|http://www.bbc.co.uk/opensource/test?ARG=VALEARG2=VAL2> Test 3 Ldoinghere> Test 4 L ACKNOWLEDGEMENTS"> Pod-Xhtml-1.60/t/d.xhtml0000644016522100007720000000471011424067054016276 0ustar jamielengineers00000000000000

Index

OFF PAGE

Top

name X Net::Ping X crontab(5) X

sec in name X For Loops in perlsyn X Apple Juice in Net::Ping X BUGS in crontab(5) X

text X Perl Error Messages X Is the host up? X User Crontab X

text X SWITCH statements X

ON PAGE

Top

BUGS X Constructor Options X

text X the various attributes X

HYPERLINK

Top

http://www.bbc.co.uk/ X

Pod-Xhtml-1.60/t/e.xhtml0000644016522100007720000000075411424067054016303 0ustar jamielengineers00000000000000

Index

NAME

Top

test POD

This is some text/html

DESCRIPTION

Top

Woo!
Pod-Xhtml-1.60/t/a.xhtml0000644016522100007720000000754011424067054016277 0ustar jamielengineers00000000000000

Index

NAME

Top

A - Some demo POD

SYNOPSIS

Top

	use Pod::Xhtml;
	my $px = new Pod::Xhtml;

DESCRIPTION

Top

This is a module to translate POD to Xhtml. Lorem ipsum Dolor in Dolor sit amet consectueur adipscing elit. Sed diam nomumny. This is a module to translate POD to Xhtml. The Lorem entry ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. This is a module to translate POD to Xhtml. Lorem ipsum dolor sit amet consectueur adipscing elit. . This is a module to translate POD to Xhtml. See Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. http://foo.bar/baz/

METHODS

Top

Nested blocks

Pod::Xhtml now supports nested over/item/back blocks:

  • Point 1
  • Point Number 2
  • Item three
  • Point four

    Still point four 

      This is verbatim text in a bulleted list



  This is verbatim test in a regular list

TOP

This should NOT reference #TOP, unless the top of the page has had its id changed, somehow, for some reason.

EXAMPLE

This is the first example block.

ATTRIBUTES

Top

Lorem

Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny.

Ipsum

Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny.

Dolor( $foo )

Lorem ipsum dolor sit amet consectueur .... elit. Sed diam nomumny.

EXAMPLE

This is the second example block.

ISSUES

Top

KNOWN ISSUES

There are some issues known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. SPACES   ARE  IMPORTANT

UNKNOWN ISSUES

There are also some issues not known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny.

EXAMPLE

This is the third example block.

Pod-Xhtml-1.60/t/b.xhtml0000644016522100007720000000456511424067054016304 0ustar jamielengineers00000000000000

Index

NAME

Top

B - Some demo POD

SYNOPSIS

Top

	use Pod::Xhtml;
	my $px = new Pod::Xhtml;

SUB-SYNOPSIS

To test returning back to head1.

DESCRIPTION

Top

This is a module to translate POD to Xhtml. Lorem ipsum Dolor in Dolor sit amet consectueur adipscing elit. Sed diam nomumny.

LINKS

Top

@ARGV should link to the as-yet undefined "@ARGV" section

Whereas $ARGV shouldn't. It should link to the undefined "$ARGV" section

ISSUES

Top

KNOWN ISSUES

$ARGV

Is sometimes undefined

@ARGV

Is occasionally populated with the numbers 1, 2, 3, 4, 5, 6, 7, 8, 9 and 10

%ARGV

Does not exist

Test for Escaped HTML in Marked text

<meta />

R&R

"hello"

Pod-Xhtml-1.60/t/a.pod0000644016522100007720000000373611424067054015730 0ustar jamielengineers00000000000000=head1 NAME A - Some demo POD =head1 SYNOPSIS use Pod::Xhtml; my $px = new Pod::Xhtml; =head1 DESCRIPTION This is a module to translate POD to Xhtml. Lorem ipsum L sit amet consectueur adipscing elit. Sed diam nomumny. This is a module to translate POD to Xhtml. L ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. This is a module to translate F to Xhtml. B ipsum I sit amet C elit. X. This is a module to translate POD to Xhtml. See L ipsum dolor sit amet consectueur adipscing elit. Sed diam L. L =head1 METHODS =over 4 =item Nested blocks Pod::Xhtml now supports nested over/item/back blocks: =over 4 =item * Point 1 =item * Point Number 2 =item * Item three =item * Point four Still point four This is verbatim text in a bulleted list =back This is verbatim test in a regular list =back =head2 TOP This should NOT reference #TOP, unless the top of the page has had its id changed, somehow, for some reason. =head2 EXAMPLE This is the first example block. =head1 ATTRIBUTES =over 4 =item Lorem Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. =item Ipsum Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. =item Dolor( $foo ) Lorem ipsum dolor sit amet consectueur ..Z<>.. elit. Sed diam nomumny. =back =head2 EXAMPLE This is the second example block. =head1 ISSUES =head2 KNOWN ISSUES There are some issues known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. S =head2 UNKNOWN ISSUES There are also some issues not known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. =head3 EXAMPLE This is the third example block. =cut Pod-Xhtml-1.60/t/FH.xhtml0000644016522100007720000000755011424067054016355 0ustar jamielengineers00000000000000

Index

NAME

Top

A - Some demo POD

SYNOPSIS

Top

	use Pod::Xhtml;
	my $px = new Pod::Xhtml;

DESCRIPTION

Top

This is a module to translate POD to Xhtml. Lorem ipsum Dolor in Dolor sit amet consectueur adipscing elit. Sed diam nomumny. This is a module to translate POD to Xhtml. The Lorem entry ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. This is a module to translate POD to Xhtml. Lorem ipsum dolor sit amet consectueur adipscing elit. . This is a module to translate POD to Xhtml. See Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. http://foo.bar/baz/

METHODS

Top

Nested blocks

Pod::Xhtml now supports nested over/item/back blocks:

  • Point 1
  • Point Number 2
  • Item three
  • Point four

    Still point four 

      This is verbatim text in a bulleted list



  This is verbatim test in a regular list

TOP

This should NOT reference #TOP, unless the top of the page has had its id changed, somehow, for some reason.

EXAMPLE

This is the first example block.

ATTRIBUTES

Top

Lorem

Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny.

Ipsum

Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny.

Dolor( $foo )

Lorem ipsum dolor sit amet consectueur .... elit. Sed diam nomumny.

EXAMPLE

This is the second example block.

ISSUES

Top

KNOWN ISSUES

There are some issues known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. SPACES   ARE  IMPORTANT

UNKNOWN ISSUES

There are also some issues not known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny.

EXAMPLE

This is the third example block.

Pod-Xhtml-1.60/t/01defaults.t0000644016522100007720000000734411424067054017140 0ustar jamielengineers00000000000000#!/usr/local/bin/perl -w #$Id: 01defaults.t,v 1.24 2007/07/16 11:09:29 andreww Exp $ use strict; use lib qw(./lib ../lib); use Test::More; use Getopt::Std; use File::Basename; getopts('tTs', \my %opt); if ($opt{t} || $opt{T}) { require Log::Trace; import Log::Trace print => {Deep => $opt{T}}; } chdir ( dirname ( $0 ) ); require Test_LinkParser; my $pod_links = Test_LinkParser->new(); plan tests => 21; eval { require Pod::Xhtml }; ok( $Pod::Xhtml::VERSION, "Pod::Xhtml compiled" ); for my $tdata (['a'], ['b'], ['c', MakeIndex => 2], ['e'], ['FH'], # parsing from filehandle ) { my($tname, %options) = @$tdata; my $podi = "$tname.pod"; my $podo = "$tname.pod.xhtml"; my $podg = "$tname.xhtml"; my $parser = Pod::Xhtml->new(LinkParser => $pod_links, %options); unlink $podo if -e $podo; ok( ! -f $podo, "output file ($podo) doesn't exist"); if($tname eq 'FH') { # test parsing from filehandles open(OUT, '>'.$podo) or die("Can't open out $podo: $!"); $parser->parse_from_filehandle( \*DATA, \*OUT ); close OUT; } else { # try parsing from file $parser->parse_from_file( $podi, $podo ); } ok( -f $podo, "output file ($podo) created" ); my $filecont = readfile( $podo ); my $goodcont = readfile( $podg ); DUMP("filecont ($podo)", \$filecont); DUMP("goodcont ($podg)", \$goodcont); ok( $filecont, "output file contains content $tname" ); ok( $filecont =~ /\Q$goodcont\E/, "content $tname matches expected data" ); undef $filecont; unlink $podo unless $opt{'s'}; } sub readfile { my $filename = shift; local *IN; open(IN, '< ' . $filename) or die("Can't open $filename: $!"); local $/ = undef; my $x = ; close IN; return $x; } # Log::Trace stubs sub TRACE {} sub DUMP {} # this pod is for testing only! __DATA__ =head1 NAME A - Some demo POD =head1 SYNOPSIS use Pod::Xhtml; my $px = new Pod::Xhtml; =head1 DESCRIPTION This is a module to translate POD to Xhtml. Lorem ipsum L sit amet consectueur adipscing elit. Sed diam nomumny. This is a module to translate POD to Xhtml. L ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. This is a module to translate F to Xhtml. B ipsum I sit amet C elit. X. This is a module to translate POD to Xhtml. See L ipsum dolor sit amet consectueur adipscing elit. Sed diam L. L =head1 METHODS =over 4 =item Nested blocks Pod::Xhtml now supports nested over/item/back blocks: =over 4 =item * Point 1 =item * Point Number 2 =item * Item three =item * Point four Still point four This is verbatim text in a bulleted list =back This is verbatim test in a regular list =back =head2 TOP This should NOT reference #TOP, unless the top of the page has had its id changed, somehow, for some reason. =head2 EXAMPLE This is the first example block. =head1 ATTRIBUTES =over 4 =item Lorem Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. =item Ipsum Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. =item Dolor( $foo ) Lorem ipsum dolor sit amet consectueur ..Z<>.. elit. Sed diam nomumny. =back =head2 EXAMPLE This is the second example block. =head1 ISSUES =head2 KNOWN ISSUES There are some issues known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. S =head2 UNKNOWN ISSUES There are also some issues not known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. =head3 EXAMPLE This is the third example block. =cut Pod-Xhtml-1.60/t/Pod_Hyperlink_BounceURL.t0000644016522100007720000000200711424067054021604 0ustar jamielengineers00000000000000#!/usr/local/bin/perl # $Revision: 1.4 $ use strict; use Test::Assertions::TestScript; use Pod::Hyperlink::BounceURL; use Pod::Xhtml; ASSERT($Pod::Hyperlink::BounceURL::VERSION, "Loaded $Pod::Hyperlink::BounceURL::VERSION"); my $lp = new Pod::Hyperlink::BounceURL; $lp->configure( URL => '/apps/trampoline.rb?p=%s&n=%s&s=1' ); DUMP($lp); ASSERT($lp, "created linkparser object"); my $px = new Pod::Xhtml(StringMode => 1, LinkParser => $lp); DUMP($px); ASSERT($px, "created pod parser object"); $px->parse_from_file( 'd.pod' ); my $xhtml = $px->asString; $xhtml =~ s/^.*.*!!s; DUMP("Made this XHTML >>>$xhtml<<<"); # Newer versions of URI::Escape escape more than what older versions did. # Check to see if either baseline matches. We don't care which since they are # functionally equivalent bits of XHTML. my $match = ""; foreach my $f (qw/d.xhtml d.new.uriescape.xhtml/) { $match = $f if(EQUALS_FILE($xhtml, $f)); } ASSERT($match, "Generated XHTML matched expected XHTML ($match)"); Pod-Xhtml-1.60/t/b.pod0000644016522100007720000000137111424067054015722 0ustar jamielengineers00000000000000=head1 NAME B - Some demo POD =head1 SYNOPSIS use Pod::Xhtml; my $px = new Pod::Xhtml; =head2 SUB-SYNOPSIS To test returning back to head1. =head1 DESCRIPTION This is a module to translate POD to Xhtml. Lorem ipsum L sit amet consectueur adipscing elit. Sed diam nomumny. =head1 LINKS L<@ARGV> should link to the as-yet undefined EI<@ARGV>E section Whereas L<$ARGV> shouldn't. It should link to the undefined EI<$ARGV>E section =head1 ISSUES =head2 KNOWN ISSUES =head3 $ARGV Is sometimes undefined =head3 @ARGV Is occasionally populated with the numbers 1, 2, 3, 4, 5, 6, 7, 8, 9 and 10 =head3 %ARGV Does not exist =head3 Test for Escaped HTML in Marked text C<< >> B I<"hello"> =cut Pod-Xhtml-1.60/t/d.new.uriescape.xhtml0000644016522100007720000000472411424067054021052 0ustar jamielengineers00000000000000

Index

OFF PAGE

Top

name X Net::Ping X crontab(5) X

sec in name X For Loops in perlsyn X Apple Juice in Net::Ping X BUGS in crontab(5) X

text X Perl Error Messages X Is the host up? X User Crontab X

text X SWITCH statements X

ON PAGE

Top

BUGS X Constructor Options X

text X the various attributes X

HYPERLINK

Top

http://www.bbc.co.uk/ X

Pod-Xhtml-1.60/t/c.pod0000644016522100007720000000377711424067054015737 0ustar jamielengineers00000000000000=head1 NAME An overly complicated POD to test out the indexing system when both lists and various head sections are involved. =head1 SYNOPSIS Foo bar. =head1 DESCRIPTION Description. =head1 METHODS =over 4 =item I should be included This should be included =over 4 =item * These should not be included. =item * These should not be included =back =item This should be included Foo foo foo. =item As should this Foo foo foo. =back =head2 TOP This should NOT reference #TOP, unless the top of the page has had its id changed, somehow, for some reason. =head2 EXAMPLE This is the first example block. =over 4 =item I should be included This should be included =over 4 =item * These should not be included. =item * These should not be included =back =item This should be included Foo foo foo. =item As should this Foo foo foo. =back =head1 ATTRIBUTES =over 4 =item Lorem Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. =item Ipsum Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. =item Dolor( $foo ) Lorem ipsum dolor sit amet consectueur ..Z<>.. elit. Sed diam nomumny. =back =head2 EXAMPLE This is the second example block. =head1 ISSUES =head2 KNOWN ISSUES There are some issues known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. S =head2 UNKNOWN ISSUES There are also some issues not known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. =head3 EXAMPLE This is the third example block. =over 4 =item * I will NOT be included. =over 4 =item I should be included This should be included =over 4 =item * These should not be included. =item * These should not be included =back =item This should be included Foo foo foo. =item As should this Foo foo foo. =back =item * Not I! =back =cut Pod-Xhtml-1.60/t/Test_LinkParser.pm0000644016522100007720000000244411424067054020406 0ustar jamielengineers00000000000000#$Revision: 1.5 $ package Test_LinkParser; use Pod::ParseUtils; use strict; use vars '@ISA', '$VERSION'; @ISA = 'Pod::Hyperlink'; $VERSION = ('$Revision: 1.5 $' =~ /([\d\.]+)/)[0]; # Override Pod::Hyperlink for the unit tests since different versions behave # differently WRT decorating links (e.g. '... elsewhere in this document') TRACE("\$Pod::ParseUtils::VERSION: " . $Pod::ParseUtils::VERSION); if (1) { # Set to '0' to test against Pod::Hyperlink *markup = *markup = \&_markup; *text = *text = \&_text; } sub _markup { my $self = shift; my $page = $self->page; my $node = $self->node; my $type = $self->type; $self->SUPER::markup(@_); my $text = $self->text(@_); DUMP($self); return $type eq 'hyperlink' ? $text : $self->alttext ? "Q<" . $self->alttext . ">" : $page && $node ? "Q<$node> in P<$page>" : !$page ? "Q<$node>" : $page && ! $node ? $page =~ /^(\w+)\((\d)\)/ ? "P<$1>($2)" # manpages : "P<$page>" : 'XXX'; } sub _text { my $self = shift; my $page = $self->page; my $node = $self->node; my $type = $self->type; my $text = $self->SUPER::text(@_); DUMP($self); return $type eq 'hyperlink' ? $text : $self->alttext ? $self->alttext : $page && $node ? "$node in $page" : !$page ? "$node" : $page && ! $node ? $page : 'XXX'; } sub TRACE {} sub DUMP {} Pod-Xhtml-1.60/t/pod.t0000644016522100007720000000020111424067055015734 0ustar jamielengineers00000000000000use Test::More; eval "use Test::Pod 1.00"; plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; all_pod_files_ok(); Pod-Xhtml-1.60/t/d.pod0000644016522100007720000000076711424067054015734 0ustar jamielengineers00000000000000=head1 OFF PAGE L X L X L X L X L X L X L X L X L X L X L X L X L X =head1 ON PAGE L X L X L X L X =head1 HYPERLINK L X =cut Pod-Xhtml-1.60/t/c.xhtml0000644016522100007720000001211311424067054016271 0ustar jamielengineers00000000000000

Index

NAME

Top

An overly complicated POD to test out the indexing system when both lists and various head sections are involved.

SYNOPSIS

Top

	Foo bar.

DESCRIPTION

Top

Description.

METHODS

Top

I should be included

This should be included

  • These should not be included.
  • These should not be included

This should be included

Foo foo foo.

As should this

Foo foo foo.

TOP

This should NOT reference #TOP, unless the top of the page has had its id changed, somehow, for some reason.

EXAMPLE

This is the first example block.

I should be included

This should be included

  • These should not be included.
  • These should not be included

This should be included

Foo foo foo.

As should this

Foo foo foo.

ATTRIBUTES

Top

Lorem

Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny.

Ipsum

Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny.

Dolor( $foo )

Lorem ipsum dolor sit amet consectueur .... elit. Sed diam nomumny.

EXAMPLE

This is the second example block.

ISSUES

Top

KNOWN ISSUES

There are some issues known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. SPACES   ARE  IMPORTANT

UNKNOWN ISSUES

There are also some issues not known about. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny. Lorem ipsum dolor sit amet consectueur adipscing elit. Sed diam nomumny.

EXAMPLE

This is the third example block.

  • I will NOT be included.
  • I should be included

    This should be included

    • These should not be included.
    • These should not be included

    This should be included

    Foo foo foo.

    As should this

    Foo foo foo.

  • Not I!
Pod-Xhtml-1.60/t/e.pod0000644016522100007720000000050011424067054015716 0ustar jamielengineers00000000000000 =head1 NAME test POD =begin xhtml

This is some text/html

=end xhtml =head1 DESCRIPTION =for pod2xhtml Woo! =begin html This should be omitted from the output.
It may be possible in future to run HTML blocks through tidy, to convert to xhtml, but this is not yet implemented. =end html =cut Pod-Xhtml-1.60/COPYING0000644016522100007720000004313111424067054015565 0ustar jamielengineers00000000000000 GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License. Pod-Xhtml-1.60/Changes0000644016522100007720000000503411424067054016025 0ustar jamielengineers00000000000000Wed Jul 28 18:17:36 2010 - 1.60 Index entries e.g. X should not be rendered Check for both old and new URI::Escape behaviour (RT #56324) Fri Sep 21 16:43:17 2007 - 1.59 honour xhtml content from =begin -> =end blocks, and =for lines Tue May 15 10:50:27 2007 - 1.56 * new TopHeading feature contributed by Jonathan Rockway * added support for Pod::Hyperlink::BounceURL link parser Wed Jul 12 13:08:01 2006 - 1.52 * generated markup now handles lists in index (via MakeIndex => 2) correctly * all head section content is enclosed within a
with an id attribute related to the name of the head section it belongs to (e.g. NAME-CONTENT). * several identical id attributes will no longer be generated, instead a number will be appended (ie. NAME-2). Thu Apr 13 11:09:33 2006 - 1.51 Updated misc. unit tests to reflect new output formatting. Generation of definition lists now using single
for each
and various block level elements within. Generated XHTML standards compliant. Thu Dec 8 16:49:30 2005 - 1.44 - Minor fix to POD in t/a.pod Fri July 15 12:00:00 2005 - 1.43 - Fix double html-escaping of links (reported by Lasse Makholm) - Fix =begin/=end behaviour so processor to skip over POD commands, not just data paragraphs. Wed June 13 16:50:00 2005 - 1.41 - Fixes for index & internal links prompted by Offer Kaye: - Ensure unique IDs on headings (which can occur more than once) - Ensure that links point to the correct headings where possible (if duplicates are involved) Wed June 01 15:30:00 2005 - 1.40 - Correctly nest bulleted lists within non-bulleted lists & vice versa - Apply patch from Shlomi Fish to nest the TOC by heading level Tue May 31 18:00:00 2005 - 1.38 - The following changes from Shlomi Fish via RT Ticket #12718: - Improved index - Replace empty named anchor elements with the 'id' attribute - Fix escaping of HTML metacharacters within markup commands - Switch to XHTML 1.1 - Remove obsolete 'lang' attribute (HTML 4) Wed Apr 27 14:58:54 2005 - 1.37 - Add DOCTYPE (XHTML 1.0 Transitional) (Thanks to Brian Cassidy) - Fix XHTML validity - some of the list types were incorrectly nested (Brian Cassidy) - Fix index listing - nested lists must be in an
  • (Brian Cassidy) - Fixed index generation - it no longer creates empty lists - Add content-wrapper (pod & toc, like search.cpan) (Brian Cassidy) Fri Dec 10 17:38:22 2004 - 1.36 (no public release) - supports =for/=begin/=end Fri Oct 22 15:49:15 2004 - 1.35 - Public release (CPAN) Pod-Xhtml-1.60/MANIFEST0000644016522100007720000000070211424067100015650 0ustar jamielengineers00000000000000Changes COPYING Makefile.PL MANIFEST MANIFEST.SKIP README lib/Pod/Xhtml.pm lib/Pod/Hyperlink/BounceURL.pm scripts/pod2xhtml cgi-bin/pod2xhtml.pl t/Test_LinkParser.pm t/01defaults.t t/a.pod t/a.xhtml t/b.pod t/b.xhtml t/c.pod t/c.xhtml t/d.pod t/d.xhtml t/d.new.uriescape.xhtml t/e.pod t/e.xhtml t/02links.t t/pod_coverage.t t/FH.xhtml t/Pod_Hyperlink_BounceURL.t t/pod.t META.yml Module meta-data (added by MakeMaker) Pod-Xhtml-1.60/MANIFEST.SKIP0000644016522100007720000000016511424067054016430 0ustar jamielengineers00000000000000^blib ^bak ~$ (?:^|/)[Mm]akefile(?:\.old)?$ (?:^|/)pm_to_blib$ ^Pod-Xhtml-\d+\.\d+\.(zip|tar\.gz|tgz)$ [Cc][Vv][Ss]/ Pod-Xhtml-1.60/lib/0000755016522100007720000000000011424067100015266 5ustar jamielengineers00000000000000Pod-Xhtml-1.60/lib/Pod/0000755016522100007720000000000011424067100016010 5ustar jamielengineers00000000000000Pod-Xhtml-1.60/lib/Pod/Hyperlink/0000755016522100007720000000000011424067100017755 5ustar jamielengineers00000000000000Pod-Xhtml-1.60/lib/Pod/Hyperlink/BounceURL.pm0000644016522100007720000000661011424067054022124 0ustar jamielengineers00000000000000package Pod::Hyperlink::BounceURL; use Pod::ParseUtils; use URI::Escape; use vars qw($VERSION @ISA); $VERSION = ('$Revision: 1.7 $' =~ /([\d\.]+)/)[0]; @ISA = 'Pod::Hyperlink'; sub configure { my $self = shift; my %opts = @_; if ($opts{'URL'}) { $self->{'___url'} = $opts{'URL'}; } } sub type { my $self = shift; # very special case - if we are called explicitly (rather than by our superclass) and with other conditions # 1) a page type with a page value # 2) an item type with a page value # We don't care about any other cases my ($callpack) = caller(); if ($callpack ne $ISA[0]) { DUMP(__PACKAGE__."::type", [ $self, @_ ]); } else { DUMP(" indirect call of ".__PACKAGE__."::type", [ $self, @_ ]); } if ( ($callpack ne $ISA[0]) && (($self->{'-type'} eq 'page') || ($self->{'-type'} eq 'item')) && $self->{'-page'} ) { my $page_esc = uri_escape( $self->{'-page'} ); my $node_esc = uri_escape( $self->{'-node'} ); my $url = sprintf( $self->{'___url'}, $page_esc, $node_esc ); return "bounceurl:$url"; } # in all other cases, let the superclass handle the work return $self->SUPER::type(@_); } # debug hooks sub TRACE {} sub DUMP {} 1; =head1 NAME Pod::Hyperlink::BounceURL - Allow off-page links in POD to point to a URL =head1 SYNOPSIS use Pod::Hyperlink::BounceURL; my $linkparser = new Pod::Hyperlink::BounceURL; $linkparser->configure( URL => '/cgi-perl/support/bounce.pl?page=%s' ); my $pod2xhtml = new Pod::Xhtml( LinkParser => $linkparser ); =head1 DESCRIPTION Some links in your pod may not be resolveable by Pod::Hyperlink, e.g. CSome::ModuleE> - this module allows you to detect such links and generate a hyperlink instead of some static text. The target URL will probably be some kind of dynamic webpage or CGI application which can then serve up the relevant page or send a redirect to the page, hence the "bounce" in this module's name. This module overrides the type() method and, for relevant links, will return a string which is "bounceurl:" followed by the URL, instead of returning "page" or "item". Your pod-conversion module can then switch on this case and emit the correct kind of markup. L supports the use of this module. =head1 METHODS =over 4 =item configure( %OPTIONS ) Set persistent configuration for this object. See L. =item type() Behaves as L's type() method except for the unresolveable links, where the string returned is as described in L. =back =head1 OPTIONS =over 4 =item URL The URL to handle the link, which may be absolute or relative, of any protocol - it's just treated as a string and is passed through sprintf(), with two string arguments that are both already URL-escaped. The first argument is the page name, and will always exist. The second argument is the "node" within the page, and may be empty. Insert '%s' where you wish the arguments to be interpolated. The string goes through sprintf() so you should have '%%' where you want an actual percent sign. If you need the arguments in a different order, see the perl-specific features of L. =back =head1 VERSION $Revision: 1.7 $ =head1 AUTHOR P Kent Ecpan _at_ bbc _dot_ co _dot_ ukE =head1 COPYRIGHT (c) BBC 2007. This program is free software; you can redistribute it and/or modify it under the GNU GPL. See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt =cut Pod-Xhtml-1.60/lib/Pod/Xhtml.pm0000644016522100007720000006501211424067054017456 0ustar jamielengineers00000000000000# $Id: Xhtml.pm,v 1.60 2007/12/21 10:52:27 andreww Exp $ package Pod::Xhtml; use strict; use Pod::Parser; use Pod::ParseUtils; use Carp; use vars qw/@ISA %COMMANDS %SEQ $VERSION $FirstAnchorId $ContentSuffix/; use constant P2X_REGION => qr/(?:pod2)?xhtml/; $FirstAnchorId = "TOP"; $ContentSuffix = "-CONTENT"; @ISA = qw(Pod::Parser); ($VERSION) = ('$Revision: 1.60 $' =~ m/([\d\.]+)/); # recognized commands %COMMANDS = map { $_ => 1 } qw(pod head1 head2 head3 head4 item over back for begin end); # recognized special sequences %SEQ = ( B => \&seqB, C => \&seqC, E => \&seqE, F => \&seqF, I => \&seqI, L => \&seqL, S => \&seqS, X => \&seqX, Z => \&seqZ, ); ########## New PUBLIC methods for this class sub asString { my $self = shift; return $self->{buffer}; } sub asStringRef { my $self = shift; return \$self->{buffer}; } sub addHeadText { my $self = shift; $self->{HeadText} .= shift; } sub addBodyOpenText { my $self = shift; $self->{BodyOpenText} .= shift; } sub addBodyCloseText { my $self = shift; $self->{BodyCloseText} .= shift; } ########## Override methods in Pod::Parser ########## PUBLIC INTERFACE sub parse_from_file { my $self = shift; $self->resetMe; $self->SUPER::parse_from_file(@_); } sub parse_from_filehandle { my $self = shift; $self->resetMe; $self->SUPER::parse_from_filehandle(@_); } ########## INTERNALS sub initialize { my $self = shift; $self->{TopLinks} = qq(

    Top

    ) unless defined $self->{TopLinks}; $self->{MakeIndex} = 1 unless defined $self->{MakeIndex}; $self->{MakeMeta} = 1 unless defined $self->{MakeMeta}; $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(); } sub command { my ($parser, $command, $paragraph, $line_num, $pod_para) = @_; my $ptree = $parser->parse_text( $paragraph, $line_num ); $pod_para->parse_tree( $ptree ); $parser->parse_tree->append( $pod_para ); } sub verbatim { my ($parser, $paragraph, $line_num, $pod_para) = @_; $parser->parse_tree->append( $pod_para ); } sub textblock { my ($parser, $paragraph, $line_num, $pod_para) = @_; my $ptree = $parser->parse_text( $paragraph, $line_num ); $pod_para->parse_tree( $ptree ); $parser->parse_tree->append( $pod_para ); } sub end_pod { my $self = shift; my $ptree = $self->parse_tree; # clean up tree ready for parse foreach my $para (@$ptree) { if ($para->{'-prefix'} eq '=') { $para->{'TYPE'} = 'COMMAND'; } elsif (! @{$para->{'-ptree'}}) { $para->{'-ptree'}->[0] = $para->{'-text'}; $para->{'TYPE'} = 'VERBATIM'; } else { $para->{'TYPE'} = 'TEXT'; } foreach (@{$para->{'-ptree'}}) { unless (ref $_) { s/\n\s+$//; } } } # now loop over each para and expand any html escapes or sequences $self->_paraExpand( $_ ) foreach (@$ptree); $self->{buffer} =~ s/(\n?)<\/pre>\s*
    /$1/sg; # concatenate 'pre' blocks
	1 while $self->{buffer} =~ s/
    (\s+)<\/pre>/$1/sg;
	$self->{buffer} = $self->_makeIndex . $self->{buffer} if $self->{MakeIndex};
	$self->{buffer} =~ s/<<>>/$1/ge;
	$self->{buffer} = join "\n", qq[
    ], $self->{buffer},
		( @{ $self->{sections} } > 1 && "
    " ), "
    • "; # Expand internal L<> links to the correct sections $self->{buffer} =~ s/#<<<(.*?)>>>/'#' . $self->_findSection($1)/eg; die "gotcha" if $self->{buffer} =~ /#<<%s\n", qq(), qq(), qq(\n), _htmlEscape( $self->{doctitle} ); $headblock .= $self->_makeMeta if $self->{MakeMeta}; unless ($self->{FragmentOnly}) { $self->{buffer} = $headblock . $self->{HeadText} . "\n\n" . $self->{BodyOpenText} . $self->{buffer}; $self->{buffer} .= $self->{BodyCloseText} . "\n\n"; } # in stringmode we only accumulate the XHTML else we print it to the # filehandle unless ($self->{StringMode}) { my $out_fh = $self->output_handle; print $out_fh $self->{buffer}; } } ########## Everything else is PRIVATE sub resetMe { my $self = shift; $self->{'-ptree'} = new Pod::ParseTree; $self->{'sections'} = []; $self->{'listKind'} = []; $self->{'listHasItems'} = []; $self->{'dataSections'} = []; $self->{'section_names'} = {}; $self->{'section_ids'} = {}; $self->{'tagStack'} = []; foreach (qw(inList titleflag )) { $self->{$_} = 0; } foreach (qw(buffer doctitle)) { $self->{$_} = ''; } # add the "$FirstAnchor" section into the sections $self->_addSection ( '', $FirstAnchorId ); } sub parse_tree { return $_[0]->{'-ptree'}; } sub _paraExpand { my $self = shift; my $para = shift; # skip data region unless its ident matches P2X_REGION (eg xhtml) my $in_dsection = !!(@{$self->{dataSections}}); my $p2x_region = $in_dsection && $self->{dataSections}->[-1] =~ P2X_REGION; my $skip_region = $in_dsection && !$p2x_region; # collapse interior sequences and strings # escape html unless it's a html data region foreach ( @{$para->{'-ptree'}} ) { $_ = (ref $_) ? $self->_handleSequence($_, $p2x_region) : $p2x_region ? $_ : _htmlEscape($_); } # the parse tree has now been collapsed into a list of strings my $string = join('', @{$para->{'-ptree'}}); if ($para->{TYPE} eq 'TEXT') { return if $skip_region; $self->_addTextblock($string, $p2x_region); } elsif ($para->{TYPE} eq 'VERBATIM') { return if $skip_region; my $paragraph = "
    $string\n\n
    "; $self->_addTextblock( $paragraph, 1 ); # no wrap if ($self->{titleflag} != 0) { $self->_setTitle( $paragraph ); warn "NAME followed by verbatim paragraph"; } } elsif ($para->{TYPE} eq 'COMMAND') { $self->_addCommand($para->{'-name'}, $string, $para->{'-text'}, $para->{'-line'} ) } else { warn "Unrecognized paragraph type $para->{TYPE} found at $self->{_INFILE} line $para->{'-line'}\n"; } } sub _addCommand { my $self = shift; my ($command, $paragraph, $raw_para, $line) = @_; my $anchor; unless (exists $COMMANDS{$command}) { warn "Unrecognized command '$command' skipped at $self->{_INFILE} line $line\n"; return; } 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\n" unless ( @{ $self->{sections} } == 1 ); $anchor = $self->_addSection( 'head1', $paragraph ); my $anchorContent = $self->_addSection( '', $paragraph . $ContentSuffix); $self->{buffer} .= qq(<$top_heading id="$anchor">$paragraph) .($self->{TopLinks} ? $self->{TopLinks} : '')."\n" ."
    \n"; if ($anchor eq 'NAME') { $self->{titleflag} = 1; } last; }; /^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
    \n" unless ( @{ $self->{sections} } == 1 ); $anchor = $self->_addSection( "head${head_level}", $paragraph ); my $anchorContent = $self->_addSection( '', $paragraph . $ContentSuffix); $self->{buffer} .= "$paragraph\n" . "
    \n"; last; }; /^item/ && !$data_para && do { unless ($self->{inList}) { warn "Not in list at $self->{_INFILE} line $line\n"; last; } $self->{listHasItems}[-1]++; $self->{listCurrentParas}[-1] = 0; # is this the first item in the list? if (@{$self->{listKind}} && $self->{listKind}[-1] == 0) { my $parent_list = $self->{listKind}[-2]; # this is a sub-list if ($parent_list && $parent_list == 1) { #
      sub lists must be in an
    • [BEGIN] $self->{buffer} .= $self->_tagLevel () . "
    • \n"; push @{$self->{tagStack}}, "li"; } elsif ($parent_list && $parent_list == 2) { #
      sub lists must be in a

      [BEGIN] $self->{buffer} .= $self->_tagLevel () . "

      \n"; push @{$self->{tagStack}}, "p"; } if ($paragraph eq '*') { $self->{listKind}[-1] = 1; $self->{buffer} .= $self->_tagLevel () . "

        \n"; push @{$self->{tagStack}}, "ul"; } else { $self->{listKind}[-1] = 2; $self->{buffer} .= $self->_tagLevel () . "
        \n"; push @{$self->{tagStack}}, "dl"; } } else { # close last list item's tag# if ($self->{listKind}[-1] == 1) { my $o = pop @{$self->{tagStack}}; warn "expected 'li' to be on the tag stack but got '$o'\n" if $o ne 'li'; $self->{buffer} .= $self->_tagLevel () . "\n"; } } if (@{$self->{listKind}} && $self->{listKind}[-1] == 2) { if (@{$self->{tagStack}} && $self->{tagStack}[-1] eq "dd") { my $o = pop @{$self->{tagStack}}; warn "expected 'dd' to be on the tag stack but got '$o'\n" if $o ne 'dd'; $self->{buffer} .= $self->_tagLevel () . "\n"; } $self->{buffer} .= $self->_tagLevel () . qq({tagStack}}, "dt"; if ($self->{MakeIndex} >= 2) { $anchor = $self->_addSection( 'item', $paragraph ); $self->{buffer} .= qq( id="$anchor"); } $self->{buffer} .= ">"; $self->{buffer} .= qq($paragraph\n); my $o = pop @{$self->{tagStack}}; warn "expected 'dt' to be on the tag stack but got '$o'\n" if $o ne 'dt'; } last; }; /^over/ && !$data_para && do { $self->{inList}++; push @{$self->{listKind}}, 0; push @{$self->{listHasItems}}, 0; push @{$self->{sections}}, 'over' if $self->{MakeIndex} >= 2; push @{$self->{listCurrentParas}}, 0; }; /^back/ && !$data_para && do { my $listItems = pop @{$self->{listHasItems}}; if (--$self->{inList} < 0) { warn "=back commands don't balance =overs at $self->{_INFILE} line $line\n"; last; } elsif ($listItems == 0) { warn "empty list at $self->{_INFILE} line $line\n"; last; } elsif (@{$self->{listKind}} && $self->{listKind}[-1] == 1) { my $o = pop @{$self->{tagStack}}; warn "expected 'li' to be on the tag stack but got '$o'\n" if $o ne 'li'; $o = pop @{$self->{tagStack}}; warn "expected 'ul' to be on the tag stack but got '$o'\n" if $o ne 'ul'; $self->{buffer} .= "\n
      \n\n"; } else { while (@{$self->{tagStack}} && $self->{tagStack}[-1] eq "dd") { pop @{$self->{tagStack}}; $self->{buffer} .=$self->_tagLevel () . "\n"; } my $o = pop @{$self->{tagStack}}; warn "expected 'dl' to be on the tag stack but got '$o'\n" if $o ne 'dl'; $self->{buffer} .= $self->_tagLevel () . "
      \n"; } my $parent_list = $self->{listKind}[-2]; # this is a sub-list if ($parent_list && $parent_list == 1) { my $o = pop @{$self->{tagStack}}; warn "expected 'li' to be on the tag stack but got '$o'\n" if $o ne 'li'; #
        sub lists must be in an
      • [END] $self->{buffer} .= $self->_tagLevel () . "
        • \n"; } if ($parent_list && $parent_list == 2) { my $o = pop @{$self->{tagStack}}; warn "expected 'p' to be on the tag stack but got '$o'\n" if $o ne 'p'; #
        sub lists must be in a

        [END] $self->{buffer} .= $self->_tagLevel () . "

        \n"; } if ( $self->{MakeIndex} >= 2 ) { if ( ! ref $self->{sections}->[ -1 ] ) { if ( $self->{sections}->[ -1 ] =~ /^over$/i ) { pop @{ $self->{sections} }; } } else { if ( $self->{sections}->[ -1 ] [ 0 ] =~ /^item$/i ) { push @{ $self->{sections} }, 'back'; } } } pop @{$self->{listKind}}; pop @{$self->{listCurrentParas}}; last; }; /^for/ && !$data_para && do { my($ident, $html) = $raw_para =~ /^\s*(\S+)\s+(.*)/; $html = undef unless $ident =~ P2X_REGION; $self->{buffer} .= $html if $html; }; /^begin/ && !$data_para && do { my ($ident) = $paragraph =~ /(\S+)/; push @{$self->{dataSections}}, $ident; last; }; /^end/ && do { my ($ident) = $paragraph =~ /(\S+)/; unless (@{$self->{dataSections}}) { warn "no corresponding '=begin $ident' marker at $self->{_INFILE} line $line\n"; last; } my $current_section = $self->{dataSections}[-1]; unless ($current_section eq $ident) { warn "'=end $ident' doesn't match '=begin $current_section' at $self->{_INFILE} line $line\n"; last; } pop @{$self->{dataSections}}; last; }; } } sub _addTextblock { my $self = shift; my($paragraph, $no_wrap) = @_; if ($self->{titleflag} != 0) { $self->_setTitle( $paragraph ); } # DON'T wrap a paragraph in a

        if it's a 

        !
	$no_wrap = 1 if $paragraph =~ m/^\s*
        /im;

	if (! @{$self->{listKind}} || $self->{listKind}[-1] == 0) {
		if (!$no_wrap) {
			$self->{buffer} .= $self->_tagLevel () . "
        $paragraph
        \n";
		} else {
			$self->{buffer} .= "$paragraph\n";
		}
	} elsif (@{$self->{listKind}} && $self->{listKind}[-1] == 1) {
		if ($self->{listCurrentParas}[-1]++ == 0) {
			# should this list item be closed?
			push @{$self->{tagStack}}, "li";
			$self->{buffer} .= $self->_tagLevel () . "
      • $paragraph";
		} else {
			$self->{buffer} .= "\n

        $paragraph";
		}
	} else {
		if ($self->{listCurrentParas}[-1]++ == 0) {
			$self->{buffer} .= $self->_tagLevel () . "
        \n";
			push @{$self->{tagStack}}, "dd";
		}

		if (!$no_wrap) {
			$self->{buffer} .= $self->_tagLevel () . "
        $paragraph
        \n";
		} else {
			$self->{buffer} .= "$paragraph\n";
		}
	}
}

sub _tagLevel {
	my $self = shift;
	return ( "\t" x scalar @{$self->{tagStack}} );
}

# expand interior sequences recursively, bottom up
sub _handleSequence {
	my $self = shift;
	my($seq, $no_escape) = @_;
	my $buffer = '';

	foreach (@{$seq->{'-ptree'}}) {
		if (ref $_) {
			$buffer .= $self->_handleSequence($_);
		} else {
			$buffer .= $no_escape ? $_ : _htmlEscape($_);
		}
	}

	unless (exists $SEQ{$seq->{'-name'}}) {
		warn "Unrecognized special sequence '$seq->{'-name'}' skipped at $self->{_INFILE} line $seq->{'-line'}\n";
		return $buffer;
	}
	return $SEQ{$seq->{'-name'}}->($self, $buffer);
}

sub _makeIndexId {
	my $arg = shift;

	$arg =~ s/\W+/_/g;
	$arg =~ s/^_+|_+$//g;
	$arg =~ s/__+/_/g;
	$arg = substr($arg, 0, 36);
	return $arg;
}

sub _addSection {
	my $self = shift;
	my ($type, $htmlarg) = @_;
	return unless defined $htmlarg;

	my $index_id;
	if ($self->{section_names}{$htmlarg}) {
		$index_id = $self->{section_names}{$htmlarg};
	} else {
		$index_id = _makeIndexId($htmlarg);
	}
	
	if ($self->{section_ids}{$index_id}++) {
		$index_id .= "-" . $self->{section_ids}{$index_id};
	}
	
	# if {section_names}{$htmlarg} is already set then this is a duplicate 'id',
	# so keep the reference to the first one
	$self->{section_names}{$htmlarg} = $index_id
		unless exists $self->{section_names}{$htmlarg};

	push( @{$self->{sections}}, [$type, $index_id, $htmlarg]);
	return $index_id;
}

sub _findSection {
	my $self = shift;
	my ($htmlarg) = @_;

	my $index_id;
	if ($index_id = $self->{section_names}{$htmlarg}) {
		return $index_id;
	} else {
		return _makeIndexId($htmlarg);
	}
}

sub _get_elem_level {
	my $elem = shift;
	if (ref($elem)) {
		my $type = $elem->[0];
		if ($type =~ /^head(\d+)$/) {
			return $1;
		} else {
			return 0;
		}
	} else {
		return 0;
	}
}

sub _makeTabbing {
	my $level = shift || 0;

	return "\n" . ( "\t" x $level );
}

sub _makeIndex {
	my $self = shift;

	my $string = "\n
        Index
        \n";

	my $previous_level = 0;
	my $previous_section = '';
	
	SECTION: foreach my $section ( @{ $self->{sections} } )
	{
		my $this_level = 0;

		if ( ! ref $section )
		{
			for ( $section )
			{
				if ( $section =~ m/^over$/i )
				{
					$previous_level++;
					$string .= ( $previous_section ne 'over' && "
        • \n" ) .
						"
      • \n
          \n";
				}
				elsif ( $section =~ m/^back$/i )
				{
					$previous_level--;
					$string .= "\n\n
        ";
				}
			}

			$previous_section = $section;
		}
		else
		{
			my ( $type, $href, $name ) = @$section;
			
			if ( $section->[ 0 ] =~ m/^item$/i )
			{
				$this_level = $previous_level;
			}
			else
			{
				$this_level = _get_elem_level ( $section );
			}

			next SECTION if $this_level == 0;
			
			if ( $this_level > $previous_level )
			{
				# open new list(s)
				$string .= "\n
          " .
					( "\n
        • \n
            " ) x ( $this_level - $previous_level - 1 );
			}
			elsif ( $this_level < $previous_level )
			{
				# close list(s)
				$string .= "\n" .
					( "
          \n
          • \n" ) x ( $previous_level - $this_level );
			}
			else
			{
				$string .= "\n" unless $previous_section =~ /^over$/i;
			}

			$string .= '
        • ' . $name . '';

			$previous_level = $this_level;

			$previous_section = ( ref $section ? $section->[ 0 ] : $section );
		}
	}

	$string .= ( "\n
          • \n
        " x $previous_level );
	$string .= "
        \n\n\n";
	
	return $string;
}

sub _makeMeta {
	my $self = shift;
	return
		qq(\t\n)
		. qq(\t\n)
		. qq(\t\n)
		. qq(\t\n)
		. qq(\t\n);
}

sub _setTitle {
	my $self = shift;
	my $paragraph = shift;

	if ($paragraph =~ m/^(.+?) - /) {
		$self->{doctitle} = $1;
	} elsif ($paragraph =~ m/^(.+?): /) {
		$self->{doctitle} = $1;
	} elsif ($paragraph =~ m/^(.+?)\.pm/) {
		$self->{doctitle} = $1;
	} else {
		$self->{doctitle} = substr($paragraph, 0, 80);
	}
	$self->{titleflag} = 0;
}

sub _htmlEscape {
	my $txt = shift;
	$txt =~ s/&/&/g;
	$txt =~ s//>/g;
	$txt =~ s/\"/"/g;
	return $txt;
}

########## Sequence handlers
sub seqI { return '' . $_[1] . ''; }
sub seqB { return '' . $_[1] . ''; }
sub seqC { return '' . $_[1] . ''; }
sub seqF { return '' . $_[1] . ''; }
sub seqZ { return ''; }

sub seqL {
	my ($self, $link) = @_;
	$self->{LinkParser}->parse( $link );

	my $page = $self->{LinkParser}->page;
	my $kind = $self->{LinkParser}->type;
	my $string = '';

	if ($kind eq 'hyperlink') {	#easy, a hyperlink
		my $targ = $self->{LinkParser}->node;
		my $text = $self->{LinkParser}->text;
		$string = qq($text);
	} elsif ($kind =~ m/^bounceurl:(.+)$/) {
		# Our link-parser has decided that the link should be handled by a particular URL
		my $url = $1;
		$url = _htmlEscape( $url ); # since the URL may contain ampersands
		$string = $self->{LinkParser}->markup;
		if ($string =~ m/P<.+>/) {	# when there's no alternative text we get P, and maybe Q
			$string =~ s|Q<(.+?)>|$1|;
			$string =~ s|P<(.+?)>|$1|;
		} else {
			$string =~ s|Q<(.+?)>|$1|;
		}
	} elsif ($page eq '') {	# a link to this page
		# Post-process these links so we can things up to the correct sections
		my $targ = $self->{LinkParser}->node;
		$string = $self->{LinkParser}->markup;
		$string =~ s|Q<(.+?)>|$1|;
	} elsif ($link !~ /\|/) {	# a link off-page with _no_ alt text
		$string = $self->{LinkParser}->markup;
		$string =~ s|Q<(.+?)>|$1|;
		$string =~ s|P<(.+?)>|$1|;
	} else {	# a link off-page with alt text
		my $text = _htmlEscape( $self->{LinkParser}->text );
		my $targ = _htmlEscape( $self->{LinkParser}->node );
		$string = "$text (";
		$string .= "$targ in " if $targ;
		$string .= "$page)";
	}
	return $string;
}

sub seqS {
	my $text = $_[1];
	$text =~ s/\s/ /g;
	return $text;
}

sub seqX {
	my $self = shift;
	my $arg = shift;
	return qq[];
}

sub seqE {
	my $self = shift;
	my $arg = shift;
	my $rv;

	if ($arg eq 'sol') {
		$rv = '/';
	} elsif ($arg eq 'verbar') {
		$rv = '|';
	} elsif ($arg =~ /^\d$/) {
		$rv = "&#$arg;";
	} elsif ($arg =~ /^0?x(\d+)$/) {
		$rv = $1;
	} else {
		$rv = "&$arg;";
	}
	return $rv;
}
1;
__END__

=head1 NAME

Pod::Xhtml - Generate well-formed XHTML documents from POD format documentation

=head1 SYNOPSIS

This module inherits from Pod::Parser, hence you can use this familiar
interface:

	use Pod::Xhtml;
	my $parser = new Pod::Xhtml;
	$parser->parse_from_file( $infile, $outfile );

	# or use filehandles instead
	$parser->parse_from_filehandle($in_fh, $out_fh);

	# or get the XHTML as a scalar
	my $parsertoo = new Pod::Xhtml( StringMode => 1 );
	$parsertoo->parse_from_file( $infile, $outfile );
	my $xhtml = $parsertoo->asString;

	# or get a reference to the XHTML string
	my $xhtmlref = $parsertoo->asStringRef;

	# to parse some other pod file to another output file all you need to do is...
	$parser->parse_from_file( $anotherinfile, $anotheroutfile );

There are options specific to Pod::Xhtml that you can pass in at construction
time, e.g.:

	my $parser = new Pod::Xhtml(StringMode => 1, MakeIndex => 0);

See L<"OPTIONS">. For more information also see L which this
module inherits from.

=head1 DESCRIPTION

=over 4

=item new Pod::Xhtml( [ OPTIONS ] )

Create a new object. Optionally pass in some options in the form
C<'new Pod::Xhtml( StringMode =E 1);'>

=item $parser->parse_from_file( INPUTFILE, [OUTPUTFILE] )

Read POD from the input file, output to the output file (or STDOUT if no
file is given). See Pod::Parser docs for more.
Note that you can parse multiple files with the same object. All your options
will be preserved, as will any text you added with the add*Text methods.

=item $parser->parse_from_filehandle( [INPUTFILEHANDLE, [OUTPUTFILEHANDLE]] )

Read POD from the input filehandle, output to the output filehandle
(STDIN/STDOUT if no filehandle(s) given). See Pod::Parser docs for more.  Note
that you can parse multiple files with the same object. All your options will
be preserved, as will any text you added with the add*Text methods.

=item $parser->asString

Get the XHTML as a scalar. You'll probably want to use this with the
StringMode option.

=item $parser->asStringRef

As above, but you get a reference to the string, not the string itself.

=item $parser->addHeadText( $text )

Inserts some text just before the closing head tag. For example you can add a
link to a stylesheet. May be called many times to add lots of text. Note: you
need to call this some time B any output is done, e.g. straight after
new(). Make sure that you only insert valid XHTML fragments.

=item $parser->addBodyOpenText( $text ) / $parser->addBodyCloseText( $text )

Inserts some text right at the beginning (or ending) of the body element. For
example you can add a navigation header and footer.  May be called many times
to add lots of text. Note: you need to call this some time B any output
is done, e.g. straight after new(). Make sure that you only insert valid XHTML
fragments.

=back

=head1 OPTIONS

=over 4

=item StringMode

Default: 0. If set to 1 this does no output at all, even if filenames/handles
are supplied. Use asString or asStringRef to access the text if you set this
option.

=item MakeIndex

Default: 1. If set to 1 then an index of sections is created at the top of the
body. If set to 2 then the index includes non-bulleted list items

=item MakeMeta

Default: 1. If set to 1 then some meta tags are created, recording things like
input file, description, etc.

=item FragmentOnly

Default: 0. If 1, we only produce an XHTML fragment (suitable for use as a
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 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.
Set to 0 or '' to inhibit links, or define your own.

	Default: 
        Top
        

=item LinkParser

An object that parses links in the POD document. By default, this is a regular
Pod::Hyperlink object. Any user-supplied link parser must conform the the
Pod::Hyperlink API.

This module works with a L link parser and generates
hyperlinks as 'a' elements with a class of 'pod_xhtml_bounce_url'. The optional
text giving the "node" is enclosed in a 'strong' element with a class of 'pod_xhtml_bounce_url_text'

=back

=head1 RATIONALE

There's Pod::PXML and Pod::XML, so why do we need Pod::Xhtml? You need an XSLT
to transform XML into XHTML and many people don't have the time or inclination
to do this. But they want to make sure that the pages they put on their web
site are well-formed, they want those pages to use stylesheets easily, and
possibly they want to squirt the XHTML through some kind of filter for more
processing.

By generating well-formed XHTML straight away we allow anyone to just use the
output files as-is. For those who want to use XML tools or transformations they
can use the XHTML as a source, because it's a well-formed XML document.

=head1 CAVEATS

This module outputs well-formed XHTML if the POD is well-formed. To check this
you can use something like:

	use Pod::Checker;
	my $syn = podchecker($defaultIn);

If $syn is 0 there are no syntax errors. If it's -1 then no POD was found. Any
positive number indicates that that number of errors were found. If the input
POD has errors then the output XHTML I be well-formed but will probably
omit information, and in addition Pod::Xhtml will emit warnings. Note that
Pod::Parser seems to be sensitive to the current setting of $/ so ensure it's
the end-of-line character when the parsing is done.

=head1 AUTHOR

P Kent E Simon Flack  Ecpan _at_ bbc _dot_ co _dot_ ukE

=head1 COPYRIGHT

(c) BBC 2004, 2005. This program is free software; you can redistribute it
and/or modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt

=cut

# vim:noet
Pod-Xhtml-1.60/scripts/0000755016522100007720000000000011424067100016207 5ustar  jamielengineers00000000000000Pod-Xhtml-1.60/scripts/pod2xhtml0000644016522100007720000000333211424067054020064 0ustar  jamielengineers00000000000000#!/usr/bin/perl

use strict;
use Pod::Xhtml;
use Pod::Usage;
use Getopt::Long;

# Default options
my %opt = (index => 1, toplink => 'Top');
GetOptions(\%opt, qw(css=s toplink|backlink=s help index! infile:s outfile:s))
    || pod2usage();
pod2usage(-verbose => 2) if $opt{help};

my $toplink = $opt{toplink} ?
    sprintf '
        %s
        ', $opt{toplink} : '';

my $parser = new Pod::Xhtml(
    MakeIndex  => $opt{index},
    TopLinks   => $toplink,
);
if ($opt{css}) {
    $parser->addHeadText(qq[]);
}

$parser->parse_from_file($opt{infile}, $opt{outfile});

__DATA__

=pod

=head1 NAME

pod2xhtml - convert .pod files to .xhtml files

=head1 SYNOPSIS

    pod2xhtml [--help] [--infile INFILE] [--outfile OUTFILE] [OPTIONS]

=head1 DESCRIPTION

Converts files from pod format (see L) to XHTML format.

=head1 OPTIONS

pod2xhtml takes the following arguments:

=over 4

=item *

--help - display help

=item *

--infile FILENAME
- the input filename. STDIN is used otherwise

=item *

--outfile FILENAME
- the output filename. STDOUT is used otherwise

=item *

--css URL
- Stylesheet URL

=item *

--index/--noindex
- generate an index, or not. The default is to create an index.

=item *

--toplink LINK TEXT
- set text for "back to top" links. The default is 'Top'.

=back

=head1 BUGS

See L for a list of known bugs in the translator.

=head1 AUTHOR

P Kent Ecpan _at_ bbc _dot_ co _dot_ ukE

=head1 COPYRIGHT

(c) BBC 2004. This program is free software; you can redistribute it and/or
modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt

=head1 SEE ALSO

L, L

=cut
Pod-Xhtml-1.60/README0000644016522100007720000000101011424067055015401 0ustar  jamielengineers00000000000000Pod::Xhtml v1.60

(c) BBC 2004. This program is free software; you can redistribute it and/or
modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt

QUICK START:

Install Pod::Xhtml by unpacking the tarball and running the following
commands in the source directory:

    perl Makefile.PL
    make
    make test
    make install
    Then delete the source directory tree since it's no longer needed.

    run 'perldoc Pod::Xhtml' to read the full documentation.
Pod-Xhtml-1.60/Makefile.PL0000644016522100007720000000111411424067054016477 0ustar  jamielengineers00000000000000use ExtUtils::MakeMaker;

WriteMakefile(
              NAME          => 'Pod::Xhtml',
              VERSION_FROM  => 'lib/Pod/Xhtml.pm',
              EXE_FILES     => ['scripts/pod2xhtml'],
              PREREQ_PM => {
                            Pod::Parser => 0,
                            Pod::ParseUtils => 0,
                            Test::More => 0,
                            Test::Assertions::TestScript => 0,
                           },
              ABSTRACT_FROM => 'lib/Pod/Xhtml.pm',
              AUTHOR        => 'British Broadcasting Corporation',
             );
Pod-Xhtml-1.60/cgi-bin/0000755016522100007720000000000011424067100016030 5ustar  jamielengineers00000000000000Pod-Xhtml-1.60/cgi-bin/pod2xhtml.pl0000644016522100007720000000575711424067054020334 0ustar  jamielengineers00000000000000#!/usr/local/bin/perl

use strict;
use CGI;
use Pod::Xhtml;

#Inputs
my @css = CGI::param('css');
my $file = (CGI::param('file') =~ m|^([\w\-/]+\.\w+)$|)[0]; #Only allow sensibly named files (no ../ etc)
my $module = (CGI::param('module') =~ m|^([\w:]+)$|)[0];    #Only allow sensible module names
my $docroot = $ENV{DOCROOT} || $ENV{DOCUMENT_ROOT};

#Deduce filename
if(defined $module)
{
	$file = $module;
	$file =~ s|::|/|g;
 MODULESEARCH:
	foreach my $inc_path (@INC)
	{
		foreach my $ext (qw(pm pod)) {
			my $candidate = "$inc_path/$file.$ext";
			if(-f $candidate) {
				$file = $candidate;
				last MODULESEARCH;
			}
		}
	}
}
elsif(defined $file)
{
	$file = $docroot.$file;
}
elsif(defined $ENV{PATH_TRANSLATED})
{
	$file = $ENV{PATH_TRANSLATED};
}

#Render
print CGI::header();
if(not defined $file)
{
	print "No recognisable filename\n";
}
elsif(not -f $file)
{
	print "$file does not exist\n";
}
else
{
	#Render the XHTML
	my $link_parser = new LinkResolver(\@css);
	my $parser = new Pod::Xhtml(StringMode => 1, LinkParser => $link_parser);
	$parser->addHeadText(qq[\n]) for @css;
	$parser->parse_from_file($file);
	print $parser->asString();
}

#
# Subclass Pod::Hyperlink to create self-referring links
#

package LinkResolver;
use Pod::ParseUtils;
use base qw(Pod::Hyperlink);

sub new
{
	my $class = shift;
	my $css = shift;
	my $self = $class->SUPER::new();
	$self->{css} = $css;
	return $self;
}

sub node
{
	my $self = shift;
	if($self->SUPER::type() eq 'page')
	{
		my $url = "?module=".$self->SUPER::page();
		$url.=";css=".$_ for @{$self->{css}};
		return $url;
	}
	$self->SUPER::node(@_);
}

sub text
{
	my $self = shift;
	return $self->SUPER::page() if($self->SUPER::type() eq 'page');
	$self->SUPER::text(@_);
}

sub type
{
	my $self = shift;
	return "hyperlink" if($self->SUPER::type() eq 'page');
	$self->SUPER::type(@_);
}

1;

=head1 NAME

pod2xhtml - CGI to display POD as XHTML

=head1 SYNOPSIS

	http://localhost/cgi-bin/pod2xhtml.pl?file=/cgi-bin/pod2xhtml.pl
	http://localhost/cgi-bin/pod2xhtml.pl?module=Pod::Xhtml

=head1 DESCRIPTION

Displays POD of scripts within the web server's document root and modules within @INC.
If you keep your CGIs in a directory parallel to your web content, you can use the $DOCROOT environment variable to allow this script access.
For example if your web server layout is:

	/var/wwwroot/www
	/var/wwwroot/cgi-bin

You can add:

	SetEnv DOCROOT /var/wwwroot

to your Apache config to allow the script access to all the files below /var/wwwroot.

=head1 CGI PARAMETERS

 css - URL of stylesheet to apply
 file - name of file relative to document root
 module - name of module in @INC

=head1 VERSION

$Revision: 1.8 $ on $Date: 2004/10/22 14:44:05 $ by $Author: simonf $

=head1 AUTHOR

John Alden Ecpan _at_ bbc _dot_ co _dot_ ukE

=head1 COPYRIGHT

(c) BBC 2004. This program is free software; you can redistribute it and/or
modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt

=cut
Pod-Xhtml-1.60/META.yml0000644016522100007720000000125411424067100015773 0ustar  jamielengineers00000000000000--- #YAML:1.0
name:               Pod-Xhtml
version:            1.60
abstract:           Generate well-formed XHTML documents from POD format documentation
author:
    - British Broadcasting Corporation
license:            unknown
distribution_type:  module
configure_requires:
    ExtUtils::MakeMaker:  0
build_requires:
    ExtUtils::MakeMaker:  0
requires:
    Pod::Parser:          0
    Pod::ParseUtils:      0
    Test::Assertions::TestScript:  0
    Test::More:           0
no_index:
    directory:
        - t
        - inc
generated_by:       ExtUtils::MakeMaker version 6.56
meta-spec:
    url:      http://module-build.sourceforge.net/META-spec-v1.4.html
    version:  1.4