Upgrade to podlators 1.14.
Jarkko Hietaniemi [Fri, 23 Nov 2001 15:38:04 +0000 (15:38 +0000)]
p4raw-id: //depot/perl@13201

13 files changed:
MANIFEST
lib/Pod/Man.pm
lib/Pod/ParseLink.pm
lib/Pod/Text.pm
lib/Pod/Text/Overstrike.pm
lib/Pod/t/basic.cap [new file with mode: 0644]
lib/Pod/t/basic.clr [new file with mode: 0644]
lib/Pod/t/basic.man [new file with mode: 0644]
lib/Pod/t/basic.ovr [new file with mode: 0644]
lib/Pod/t/basic.pod [new file with mode: 0644]
lib/Pod/t/basic.t [new file with mode: 0644]
lib/Pod/t/basic.txt [new file with mode: 0644]
lib/Pod/t/parselink.t [new file with mode: 0644]

index d8f522e..4f827e4 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -139,17 +139,17 @@ ext/Devel/Peek/Makefile.PL        Data debugging tool, makefile writer
 ext/Devel/Peek/Peek.pm         Data debugging tool, module and pod
 ext/Devel/Peek/Peek.t          See if Devel::Peek works
 ext/Devel/Peek/Peek.xs         Data debugging tool, externals
-ext/Devel/PPPort/Makefile.PL   Devel::PPPort makefile writer
-ext/Devel/PPPort/PPPort.pm     Devel::PPPort
-ext/Devel/PPPort/README                Devel::PPPort Readme
-ext/Devel/PPPort/TODO          Devel::PPPort Todo
 ext/Devel/PPPort/harness/Harness.pm    Devel::PPPort test harness
 ext/Devel/PPPort/harness/Harness.xs    Devel::PPPort test harness
 ext/Devel/PPPort/harness/Makefile.PL   Devel::PPPort::harness makefile writer
 ext/Devel/PPPort/harness/module2.c     Devel::PPPort test file
 ext/Devel/PPPort/harness/module3.c     Devel::PPPort test file
 ext/Devel/PPPort/harness/t/test.t      See if Devel::PPPort works
+ext/Devel/PPPort/Makefile.PL   Devel::PPPort makefile writer
+ext/Devel/PPPort/PPPort.pm     Devel::PPPort
+ext/Devel/PPPort/README                Devel::PPPort Readme
 ext/Devel/PPPort/soak                  Test Harness to run Devel::PPPort other Perls
+ext/Devel/PPPort/TODO          Devel::PPPort Todo
 ext/Digest/MD5/Changes         Digest::MD5 extension changes
 ext/Digest/MD5/hints/irix_6.pl Hints for named architecture
 ext/Digest/MD5/Makefile.PL     Digest::MD5 extension makefile writer
@@ -1167,7 +1167,15 @@ lib/Pod/Parser.pm                Pod-Parser - define base class for parsing POD
 lib/Pod/ParseUtils.pm          Pod-Parser - pod utility functions
 lib/Pod/Plainer.pm             Pod migration utility module
 lib/Pod/Select.pm              Pod-Parser - select portions of POD docs
+lib/Pod/t/basic.cap            podlators test
+lib/Pod/t/basic.clr            podlators test
+lib/Pod/t/basic.man            podlators test
+lib/Pod/t/basic.ovr            podlators test
+lib/Pod/t/basic.pod            podlators test
+lib/Pod/t/basic.t              podlators test
+lib/Pod/t/basic.txt            podlators test
 lib/Pod/t/latex.t              Test for Pod::LaTeX
+lib/Pod/t/parselink.t          podlators test
 lib/Pod/t/utils.t              Test for Pod::ParseUtils
 lib/Pod/Text.pm                        Pod-Parser - convert POD data to formatted ASCII text
 lib/Pod/Text/Color.pm          Convert POD data to color ASCII text
@@ -1958,8 +1966,8 @@ pp.sym                            Push/Pop code symbols
 pp_ctl.c                       Push/Pop code for control flow
 pp_hot.c                       Push/Pop code for heavily used opcodes
 pp_pack.c                      Push/Pop code for pack/unpack
-pp_sort.c                      Push/Pop code for sort
 pp_proto.h                     C++ definitions for Push/Pop code
+pp_sort.c                      Push/Pop code for sort
 pp_sys.c                       Push/Pop code for system interaction
 proto.h                                Prototypes
 qnx/ar                         QNX implementation of "ar" utility
@@ -2495,5 +2503,5 @@ x2p/str.h                 Public declarations for the above
 x2p/util.c                     Utility routines
 x2p/util.h                     Public declarations for the above
 x2p/walk.c                     Parse tree walker
-XSUB.h                 Include file for extension subroutines
+XSUB.h                         Include file for extension subroutines
 xsutils.c                      Additional bundled package methods not in UNIVERSAL::
index 037f427..6ddbe13 100644 (file)
@@ -1,5 +1,5 @@
 # Pod::Man -- Convert POD data to formatted *roff input.
-# $Id: Man.pm,v 1.26 2001/11/15 09:02:06 eagle Exp $
+# $Id: Man.pm,v 1.28 2001/11/23 08:13:16 eagle Exp $
 #
 # Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>
 #
@@ -38,7 +38,7 @@ use vars qw(@ISA %ESCAPES $PREAMBLE $VERSION);
 # Don't use the CVS revision as the version, since this module is also in Perl
 # core and too many things could munge CVS magic revision strings.  This
 # number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 1.26;
+$VERSION = 1.28;
 
 
 ##############################################################################
@@ -363,12 +363,6 @@ sub initialize {
     $$self{LQUOTE} =~ s/\"/\"\"/;
     $$self{RQUOTE} =~ s/\"/\"\"/;
 
-    $$self{INDENT}    = 0;      # Current indentation level.
-    $$self{INDENTS}   = [];     # Stack of indentations.
-    $$self{INDEX}     = [];     # Index keys waiting to be printed.
-    $$self{ITEMS}     = 0;      # The number of consecutive =items.
-    $$self{NEWINDENT} = 0;      # Whether we've seen =over without =item.
-
     $self->SUPER::initialize;
 }
 
@@ -420,7 +414,7 @@ sub begin_pod {
                 splice (@dirs, 0, $cut);
                 shift @dirs if ($dirs[0] =~ /^site(_perl)?$/);
                 shift @dirs if ($dirs[0] =~ /^[\d.]+$/);
-                shift @dirs if ($dirs[0] =~ /^(.*-$^O|$^O-.*)$/);
+                shift @dirs if ($dirs[0] =~ /^(.*-$^O|$^O-.*|$^O)$/);
             }
             shift @dirs if $dirs[0] eq 'lib';
             splice (@dirs, 0, 2) if ($dirs[0] eq 'blib' && $dirs[1] eq 'lib');
@@ -474,8 +468,12 @@ $_
 ----END OF HEADER----
 
     # Initialize a few per-file variables.
-    $$self{INDENT} = 0;
-    $$self{NEEDSPACE} = 0;
+    $$self{INDENT}    = 0;      # Current indentation level.
+    $$self{INDENTS}   = [];     # Stack of indentations.
+    $$self{INDEX}     = [];     # Index keys waiting to be printed.
+    $$self{ITEMS}     = 0;      # The number of consecutive =items.
+    $$self{SHIFTWAIT} = 0;      # Whether there is a shift waiting.
+    $$self{SHIFTS}    = [];     # Stack of .RS shifts.
 }
 
 
@@ -544,10 +542,10 @@ sub textblock {
     # handle creation of the indent here.  Set WEIRDINDENT so that it will be
     # cleaned up on =back.
     $self->makespace;
-    if ($$self{NEWINDENT}) {
+    if ($$self{SHIFTWAIT}) {
         $self->output (".RS $$self{INDENT}\n");
-        $$self{WEIRDINDENT} = 1;
-        $$self{NEWINDENT} = 0;
+        push (@{ $$self{SHIFTS} }, $$self{INDENT});
+        $$self{SHIFTWAIT} = 0;
     }
     $self->output (protect $self->textmapfonts ($text));
     $self->outindex;
@@ -689,7 +687,7 @@ sub cmd_head3 {
         $self->output (".PD\n");
     }
     $self->makespace;
-    $self->output ($self->switchquotes ('.I', $self->mapfonts ($_)));
+    $self->output ($self->textmapfonts ('\f(IS' . $_ . '\f(IE') . "\n");
     $self->outindex ('Subsection', $_);
     $$self{NEEDSPACE} = 1;
 }
@@ -716,12 +714,13 @@ sub cmd_over {
     my $self = shift;
     local $_ = shift;
     unless (/^[-+]?\d+\s+$/) { $_ = $$self{indent} }
-    if (@{ $$self{INDENTS} } > 0 && !$$self{WEIRDINDENT}) {
+    if (@{ $$self{SHIFTS} } < @{ $$self{INDENTS} }) {
         $self->output (".RS $$self{INDENT}\n");
+        push (@{ $$self{SHIFTS} }, $$self{INDENT});
     }
     push (@{ $$self{INDENTS} }, $$self{INDENT});
     $$self{INDENT} = ($_ + 0);
-    $$self{NEWINDENT} = 1;
+    $$self{SHIFTWAIT} = 1;
 }
 
 # End a list.  If we've closed an embedded indent, we've mangled the hanging
@@ -736,17 +735,16 @@ sub cmd_back {
         warn "$file:$line: Unmatched =back\n";
         $$self{INDENT} = 0;
     }
-    if ($$self{WEIRDINDENT}) {
+    if (@{ $$self{SHIFTS} } > @{ $$self{INDENTS} }) {
         $self->output (".RE\n");
-        $$self{WEIRDINDENT} = 0;
+        pop @{ $$self{SHIFTS} };
     }
     if (@{ $$self{INDENTS} } > 0) {
         $self->output (".RE\n");
         $self->output (".RS $$self{INDENT}\n");
-        $$self{WEIRDINDENT} = 1;
     }
     $$self{NEEDSPACE} = 1;
-    $$self{NEWINDENT} = 0;
+    $$self{SHIFTWAIT} = 0;
 }
 
 # An individual list item.  Emit an index entry for anything that's
@@ -766,9 +764,9 @@ sub cmd_item {
     }
     $_ = '*' unless $_;
     s/^\*(\s|\Z)/\\\(bu$1/;
-    if ($$self{WEIRDINDENT}) {
+    if (@{ $$self{SHIFTS} } == @{ $$self{INDENTS} }) {
         $self->output (".RE\n");
-        $$self{WEIRDINDENT} = 0;
+        pop @{ $$self{SHIFTS} };
     }
     $_ = $self->textmapfonts ($_);
     $self->output (".PD 0\n") if ($$self{ITEMS} == 1);
@@ -776,7 +774,7 @@ sub cmd_item {
     $self->outindex ($index ? ('Item', $index) : ());
     $$self{NEEDSPACE} = 0;
     $$self{ITEMS}++;
-    $$self{NEWINDENT} = 0;
+    $$self{SHIFTWAIT} = 0;
 }
 
 # Begin a block for a particular translator.  Setting VERBATIM triggers
@@ -1039,19 +1037,20 @@ sub outindex {
     my @entries = map { split m%\s*/\s*% } @{ $$self{INDEX} };
     return unless ($section || @entries);
     $$self{INDEX} = [];
-    my $output;
+    my @output;
     if (@entries) {
-        $output = '.IX Xref "'
-            . join (' ', map { s/\"/\"\"/; $_ } @entries)
-            . '"' . "\n";
+        push (@output, [ 'Xref', join (' ', @entries) ]);
     }
     if ($section) {
-        $index =~ s/\"/\"\"/;
         $index =~ s/\\-/-/g;
         $index =~ s/\\(?:s-?\d|.\(..|.)//g;
-        $output .= ".IX $section " . '"' . $index . '"' . "\n";
+        push (@output, [ $section, $index ]);
+    }
+    for (@output) {
+        my ($type, $entry) = @$_;
+        $entry =~ s/\"/\"\"/g;
+        $self->output (".IX $type " . '"' . $entry . '"' . "\n");
     }
-    $self->output ($output);
 }
 
 # Output text to the output device.
@@ -1073,12 +1072,14 @@ sub switchquotes {
 
     # We also have to deal with \*C` and \*C', which are used to add the
     # quotes around C<> text, since they may expand to " and if they do this
-    # confuses the .SH macros and the like no end.  Expand them ourselves.  If
-    # $extra is set, we're dealing with =item, which in most nroff macro sets
-    # requires an extra level of quoting of double quotes because it passes
-    # the argument off to .TP.
+    # confuses the .SH macros and the like no end.  Expand them ourselves.
+    # Also separate troff from nroff if there are any fixed-width fonts in use
+    # to work around problems with Solaris nroff.
     my $c_is_quote = ($$self{LQUOTE} =~ /\"/) || ($$self{RQUOTE} =~ /\"/);
-    if (/\"/ || /\\f\(CW/) {
+    my $fixedpat = join ('|', @{ $$self{FONTS} }{'100', '101', '110', '111'});
+    $fixedpat =~ s/\\/\\\\/g;
+    $fixedpat =~ s/\(/\\\(/g;
+    if (/\"/ || /$fixedpat/) {
         s/\"/\"\"/g;
         my $nroff = $_;
         my $troff = $_;
@@ -1094,10 +1095,11 @@ sub switchquotes {
         # Work around the Solaris nroff bug where \f(CW\fP leaves the font set
         # to Roman rather than the actual previous font when used in headings.
         # troff output may still be broken, but at least we can fix nroff by
-        # just stripping out the font changes since fixed-width fonts don't
-        # mean anything for nroff.  While we're at it, also remove the font
-        # changes for nroff in =item tags, since they're unnecessary.
-        $nroff =~ s/\\f\(CW(.*)\\f[PR]/$1/g;
+        # just switching the font changes to the non-fixed versions.
+        $nroff =~ s/\Q$$self{FONTS}{100}\E(.*)\\f[PR]/$1/g;
+        $nroff =~ s/\Q$$self{FONTS}{101}\E(.*)\\f([PR])/\\fI$1\\f$2/g;
+        $nroff =~ s/\Q$$self{FONTS}{110}\E(.*)\\f([PR])/\\fB$1\\f$2/g;
+        $nroff =~ s/\Q$$self{FONTS}{111}\E(.*)\\f([PR])/\\f\(BI$1\\f$2/g;
 
         # Now finally output the command.  Only bother with .ie if the nroff
         # and troff output isn't the same.
index cced975..1832559 100644 (file)
@@ -1,5 +1,5 @@
 # Pod::ParseLink -- Parse an L<> formatting code in POD text.
-# $Id: ParseLink.pm,v 1.1 2001/11/15 07:58:57 eagle Exp $
+# $Id: ParseLink.pm,v 1.4 2001/11/23 06:19:00 eagle Exp $
 #
 # Copyright 2001 by Russ Allbery <rra@stanford.edu>
 #
@@ -34,7 +34,7 @@ use Exporter;
 # Don't use the CVS revision as the version, since this module is also in Perl
 # core and too many things could munge CVS magic revision strings.  This
 # number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 1.01;
+$VERSION = 1.04;
 
 
 ##############################################################################
@@ -49,7 +49,7 @@ sub _parse_section {
 
     # If the whole link is enclosed in quotes, interpret it all as a section
     # even if it contains a slash.
-    return (undef, $1) if (/^"\s*(.*?)\s*"$/);
+    return (undef, $1) if ($link =~ /^"\s*(.*?)\s*"$/);
 
     # Split into page and section on slash, and then clean up quoting in the
     # section.  If there is no section and the name contains spaces, also
@@ -95,7 +95,7 @@ sub parselink {
         }
         my ($name, $section) = _parse_section ($link);
         my $inferred = $text || _infer_text ($name, $section);
-        my $type = ($name =~ /\(\S*\)/) ? 'man' : 'pod';
+        my $type = ($name && $name =~ /\(\S*\)/) ? 'man' : 'pod';
         return ($text, $inferred, $name, $section, $type);
     }
 }
@@ -140,12 +140,28 @@ The inferred anchor text is implemented per L<perlpodspec>:
 
 The name may contain embedded EE<lt>E<gt> and ZE<lt>E<gt> formatting codes,
 and the section, anchor text, and inferred anchor text may contain any
-formatting codes.  Any double quotes around the name or section are removed
-as part of the parsing, as are any leading or trailing whitespace.
-
-No attempt is made to resolve formatting codes.  The caller must be prepared
-to do that either before or after calling parselink().  (This is because
-interpretation of EE<lt>E<gt> formatting codes may vary by formatter.)
+formatting codes.  Any double quotes around the section are removed as part
+of the parsing, as is any leading or trailing whitespace.
+
+If the text of the LE<lt>E<gt> escape is entirely enclosed in double quotes,
+it's interpreted as a link to a section for backwards compatibility.
+
+No attempt is made to resolve formatting codes.  This must be done after
+calling parselink (since EE<lt>E<gt> formatting codes can be used to escape
+characters that would otherwise be significant to the parser and resolving
+them before parsing would result in an incorrect parse of a formatting code
+like:
+
+    L<verticalE<verbar>barE<sol>slash>
+
+which should be interpreted as a link to the C<vertical|bar/slash> POD page
+and not as a link to the C<slash> section of the C<bar> POD page with an
+anchor text of C<vertical>.  Note that not only the anchor text will need to
+have formatting codes expanded, but so will the target of the link (to deal
+with EE<lt>E<gt> and ZE<lt>E<gt> formatting codes), and special handling of
+the section may be necessary depending on whether the translator wants to
+consider markup in sections to be significant when resolving links.  See
+L<perlpodspec> for more information.
 
 =head1 AUTHOR
 
index 4f8a222..e62e7c2 100644 (file)
@@ -1,5 +1,5 @@
 # Pod::Text -- Convert POD data to formatted ASCII text.
-# $Id: Text.pm,v 2.14 2001/11/15 08:03:18 eagle Exp $
+# $Id: Text.pm,v 2.15 2001/11/23 06:14:10 eagle Exp $
 #
 # Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>
 #
@@ -42,7 +42,7 @@ use vars qw(@ISA @EXPORT %ESCAPES $VERSION);
 # Don't use the CVS revision as the version, since this module is also in Perl
 # core and too many things could munge CVS magic revision strings.  This
 # number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 2.14;
+$VERSION = 2.15;
 
 
 ##############################################################################
@@ -217,7 +217,6 @@ sub command {
     my $command = shift;
     return if $command eq 'pod';
     return if ($$self{EXCLUDE} && $command ne 'end');
-    $self->item ("\n") if defined $$self{ITEM};
     if ($self->can ('cmd_' . $command)) {
         $command = 'cmd_' . $command;
         $self->$command (@_);
@@ -343,61 +342,33 @@ sub preprocess_paragraph {
 
 # First level heading.
 sub cmd_head1 {
-    my $self = shift;
-    local $_ = shift;
-    s/\s+$//;
-    $_ = $self->interpolate ($_, shift);
-    if ($$self{alt}) {
-        $self->output ("\n==== $_ ====\n\n");
-    } else {
-        $_ .= "\n" if $$self{loose};
-        $self->output ($_ . "\n");
-    }
+    my ($self, $text, $line) = @_;
+    $self->heading ($text, $line, 0, '====');
 }
 
 # Second level heading.
 sub cmd_head2 {
-    my $self = shift;
-    local $_ = shift;
-    s/\s+$//;
-    $_ = $self->interpolate ($_, shift);
-    if ($$self{alt}) {
-        $self->output ("\n==   $_   ==\n\n");
-    } else {
-        $self->output (' ' x ($$self{indent} / 2) . $_ . "\n\n");
-    }
+    my ($self, $text, $line) = @_;
+    $self->heading ($text, $line, $$self{indent} / 2, '==  ');
 }
 
 # Third level heading.
 sub cmd_head3 {
-    my $self = shift;
-    local $_ = shift;
-    s/\s+$//;
-    $_ = $self->interpolate ($_, shift);
-    if ($$self{alt}) {
-        $self->output ("\n=    $_    =\n\n");
-    } else {
-        $self->output (' ' x ($$self{indent} * 2 / 3 + 0.5) . $_ . "\n\n");
-    }
+    my ($self, $text, $line) = @_;
+    $self->heading ($text, $line, $$self{indent} * 2 / 3 + 0.5, '=   ');
 }
 
 # Third level heading.
 sub cmd_head4 {
-    my $self = shift;
-    local $_ = shift;
-    s/\s+$//;
-    $_ = $self->interpolate ($_, shift);
-    if ($$self{alt}) {
-        $self->output ("\n-    $_    -\n\n");
-    } else {
-        $self->output (' ' x ($$self{indent} * 3 / 4 + 0.5) . $_ . "\n\n");
-    }
+    my ($self, $text, $line) = @_;
+    $self->heading ($text, $line, $$self{indent} * 3 / 4 + 0.5, '-   ');
 }
 
 # Start a list.
 sub cmd_over {
     my $self = shift;
     local $_ = shift;
+    $self->item ("\n\n") if defined $$self{ITEM};
     unless (/^[-+]?\d+\s+$/) { $_ = $$self{indent} }
     push (@{ $$self{INDENTS} }, $$self{MARGIN});
     $$self{MARGIN} += ($_ + 0);
@@ -406,6 +377,7 @@ sub cmd_over {
 # End a list.
 sub cmd_back {
     my ($self, $text, $line, $paragraph) = @_;
+    $self->item ("\n\n") if defined $$self{ITEM};
     $$self{MARGIN} = pop @{ $$self{INDENTS} };
     unless (defined $$self{MARGIN}) {
         my $file;
@@ -421,7 +393,7 @@ sub cmd_item {
     if (defined $$self{ITEM}) { $self->item }
     local $_ = shift;
     s/\s+$//;
-    $$self{ITEM} = $self->interpolate ($_);
+    $$self{ITEM} = $_ ? $self->interpolate ($_) : '*';
 }
 
 # Begin a block for a particular translator.  Setting VERBATIM triggers
@@ -512,6 +484,28 @@ sub seq_l {
 
 
 ##############################################################################
+# Header handling
+##############################################################################
+
+# The common code for handling all headers.  Takes the interpolated header
+# text, the line number, the indentation, and the surrounding marker for the
+# alt formatting method.
+sub heading {
+    my ($self, $text, $line, $indent, $marker) = @_;
+    $self->item ("\n\n") if defined $$self{ITEM};
+    $text =~ s/\s+$//;
+    $text = $self->interpolate ($text, $line);
+    if ($$self{alt}) {
+        my $closemark = reverse (split (//, $marker));
+        $self->output ("\n" . "$marker $text $closemark" . "\n\n");
+    } else {
+        $text .= "\n" if $$self{loose};
+        $self->output (' ' x $indent . $text . "\n");
+    }
+}
+
+
+##############################################################################
 # List handling
 ##############################################################################
 
@@ -540,9 +534,16 @@ sub item {
         $$self{MARGIN} = $indent;
         my $output = $self->reformat ($tag);
         $output =~ s/\n*$/\n/;
+
+        # If the text is just whitespace, we have an empty item paragraph;
+        # this can result from =over/=item/=back without any intermixed
+        # paragraphs.  Insert some whitespace to keep the =item from merging
+        # into the next paragraph.
+        $output .= "\n" if $_ && $_ =~ /^\s*$/;
+
         $self->output ($output);
         $$self{MARGIN} = $margin;
-        $self->output ($self->reformat ($_)) if /\S/;
+        $self->output ($self->reformat ($_)) if $_ && /\S/;
     } else {
         $_ = $self->reformat ($_);
         s/^ /:/ if ($$self{alt} && $indent > 0);
index 12ceee5..a20aa4b 100644 (file)
@@ -1,5 +1,5 @@
 # Pod::Text::Overstrike -- Convert POD data to formatted overstrike text
-# $Id: Overstrike.pm,v 1.4 2001/11/15 08:04:18 eagle Exp $
+# $Id: Overstrike.pm,v 1.5 2001/11/23 09:57:15 eagle Exp $
 #
 # Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000
 #   (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>)
@@ -36,7 +36,7 @@ use vars qw(@ISA $VERSION);
 # Don't use the CVS revision as the version, since this module is also in Perl
 # core and too many things could munge CVS magic revision strings.  This
 # number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 1.04;
+$VERSION = 1.05;
 
 
 ##############################################################################
@@ -45,41 +45,53 @@ $VERSION = 1.04;
 
 # Make level one headings bold, overridding any existing formatting.
 sub cmd_head1 {
-    my $self = shift;
-    local $_ = shift;
-    s/\s+$//;
-    s/(.)\cH\1//g;
-    s/_\cH//g;
-    s/(.)/$1\b$1/g;
-    $self->SUPER::cmd_head1 ($_);
+    my ($self, $text, $line) = @_;
+    $text =~ s/\s+$//;
+    $text = $self->strip_format ($self->interpolate ($text, $line));
+    $text =~ s/(.)/$1\b$1/g;
+    $self->SUPER::cmd_head1 ($text);
 }
 
 # Make level two headings bold, overriding any existing formatting.
 sub cmd_head2 {
-    my $self = shift;
-    local $_ = shift;
-    s/\s+$//;
-    s/(.)\cH\1//g;
-    s/_\cH//g;
-    s/(.)/$1\b$1/g;
-    $self->SUPER::cmd_head2 ($_);
+    my ($self, $text, $line) = @_;
+    $text =~ s/\s+$//;
+    $text = $self->strip_format ($self->interpolate ($text, $line));
+    $text =~ s/(.)/$1\b$1/g;
+    $self->SUPER::cmd_head2 ($text);
 }
 
 # Make level three headings underscored, overriding any existing formatting.
 sub cmd_head3 {
-    my $self = shift;
-    local $_ = shift;
-    s/\s+$//;
-    s/(.)\cH\1//g;
-    s/_\cH//g;
-    s/(.)/_\b$1/g;
-    $self->SUPER::cmd_head3 ($_);
+    my ($self, $text, $line) = @_;
+    $text =~ s/\s+$//;
+    $text = $self->strip_format ($self->interpolate ($text, $line));
+    $text =~ s/(.)/_\b$1/g;
+    $self->SUPER::cmd_head3 ($text);
+}
+
+# Level four headings look like level three headings.
+sub cmd_head4 {
+    my ($self, $text, $line) = @_;
+    $text =~ s/\s+$//;
+    $text = $self->strip_format ($self->interpolate ($text, $line));
+    $text =~ s/(.)/_\b$1/g;
+    $self->SUPER::cmd_head4 ($text);
+}
+
+# The common code for handling all headers.  We have to override to avoid
+# interpolating twice and because we don't want to honor alt.
+sub heading {
+    my ($self, $text, $line, $indent, $marker) = @_;
+    $self->item ("\n\n") if defined $$self{ITEM};
+    $text .= "\n" if $$self{loose};
+    $self->output (' ' x $indent . $text . "\n");
 }
 
 # Fix the various interior sequences.
-sub seq_b { local $_ = $_[1]; s/(.)\cH\1//g; s/_\cH//g; s/(.)/$1\b$1/g; $_ }
-sub seq_f { local $_ = $_[1]; s/(.)\cH\1//g; s/_\cH//g; s/(.)/_\b$1/g; $_ }
-sub seq_i { local $_ = $_[1]; s/(.)\cH\1//g; s/_\cH//g; s/(.)/_\b$1/g; $_ }
+sub seq_b { local $_ = strip_format (@_); s/(.)/$1\b$1/g; $_ }
+sub seq_f { local $_ = strip_format (@_); s/(.)/_\b$1/g; $_ }
+sub seq_i { local $_ = strip_format (@_); s/(.)/_\b$1/g; $_ }
 
 # Output any included code in bold.
 sub output_code {
@@ -110,6 +122,19 @@ sub wrap {
 }
 
 ##############################################################################
+# Utility functions
+##############################################################################
+
+# Strip all of the formatting from a provided string, returning the stripped
+# version.
+sub strip_format {
+    my ($self, $text) = @_;
+    $text =~ s/(.)\cH\1/$1/g;
+    $text =~ s/_\cH//g;
+    return $text;
+}
+
+##############################################################################
 # Module return value and documentation
 ##############################################################################
 
diff --git a/lib/Pod/t/basic.cap b/lib/Pod/t/basic.cap
new file mode 100644 (file)
index 0000000..21f38ba
--- /dev/null
@@ -0,0 +1,283 @@
+\e[1mNAME\e[m
+    basic.pod - Test of various basic POD features in translators.
+
+\e[1mHEADINGS\e[m
+    Try a few different levels of headings, with embedded formatting codes and
+    other interesting bits.
+
+\e[1mThis "is" a "level 1" heading\e[m
+  \e[1m``Level'' "2 \e[4mheading\e[m\e[m
+   Level 3 \e[1mheading \e[4mwith "weird stuff "" (double quote)"\e[m\e[m
+   Level "4 "heading"
+    Now try again with \e[1mintermixed\e[m text.
+
+\e[1mThis "is" a "level 1" heading\e[m
+    Text.
+
+  \e[1m``Level'' 2 \e[4mheading\e[m\e[m
+    Text.
+
+   Level 3 \e[1mheading \e[4mwith "weird stuff"\e[m\e[m
+    Text.
+
+   Level "4 "heading"
+    Text.
+
+\e[1mLINKS\e[m
+    These are all taken from the Pod::Parser tests.
+
+    Try out \e[4mLOTS\e[m of different ways of specifying references:
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "manpage/section"
+
+    Reference the "section" in "manpage"
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Now try it using the new "|" stuff ...
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    And then throw in a few new ones of my own.
+
+    foo
+
+    foo
+
+    "bar" in foo
+
+    "baz boo" in foo
+
+    "bar"
+
+    "baz boo"
+
+    "baz boo"
+
+    "baz boo" in foo bar
+
+    "baz boo" in foo bar
+
+    "boo" in foo bar baz
+
+    "boo var baz"
+
+    "bar baz"
+
+    "boo bar baz / baz boo"
+
+    "boo", "bar", and "baz"
+
+    foobar
+
+    Testing \e[4mitalics\e[m
+
+    "\e[4mItalic\e[m text" in foo
+
+    "Section "with" \e[4m\e[1mother\e[m markup\e[m" in foo|bar
+
+    Nested <http://www.perl.org/>
+
+\e[1mOVER AND ITEMS\e[m
+    Taken from Pod::Parser tests, this is a test to ensure that multiline
+    =item paragraphs get indented appropriately.
+
+    This is a test.
+
+    There should be whitespace now before this line.
+
+    Taken from Pod::Parser tests, this is a test to ensure the nested =item
+    paragraphs get indented appropriately.
+
+    1 First section.
+
+      a this is item a
+
+      b this is item b
+
+    2 Second section.
+
+      a this is item a
+
+      b this is item b
+
+      c
+      d This is item c & d.
+
+    Now some additional weirdness of our own. Make sure that multiple tags for
+    one paragraph are properly compacted.
+
+    "foo"
+    \e[1mbar\e[m
+    "baz"
+        There shouldn't be any spaces between any of these item tags; this
+        idiom is used in perlfunc.
+
+    Some longer item text
+        Just to make sure that we test paragraphs where the item text doesn't
+        fit in the margin of the paragraph (and make sure that this paragraph
+        fills a few lines).
+
+        Let's also make it multiple paragraphs to be sure that works.
+
+    Test use of =over without =item as a block "quote" or block paragraph.
+
+        This should be indented four spaces but otherwise formatted the same
+        as any other regular text paragraph. Make sure it's long enough to see
+        the results of the formatting.....
+
+    Now try the same thing nested, and make sure that the indentation is reset
+    back properly.
+
+            This paragraph should be doubly indented.
+
+        This paragraph should only be singly indented.
+
+        *   This is an item in the middle of a block-quote, which should be
+            allowed.
+
+        *   We're also testing tagless item commands.
+
+        Should be back to the single level of indentation.
+
+    Should be back to regular indentation.
+
+    Now also check the transformation of * into real bullets for man pages.
+
+    *   An item. We're also testing using =over without a number, and making
+        sure that item text wraps properly.
+
+    *   Another item.
+
+    and now test the numbering of item blocks.
+
+    1.  First item.
+
+    2.  Second item.
+
+\e[1mFORMATTING CODES\e[m
+    Another test taken from Pod::Parser.
+
+    This is a test to see if I can do not only $self and "method()", but also
+    "$self->method()" and "$self->{FIELDNAME}" and "$Foo <=> $Bar" without
+    resorting to escape sequences. If I want to refer to the right-shift
+    operator I can do something like "$x >> 3" or even "$y >> 5".
+
+    Now for the grand finale of "$self->method()->{FIELDNAME} = {FOO=>BAR}".
+    And I also want to make sure that newlines work like this "$self->{FOOBAR}
+    >> 3 and [$b => $a]->[$a <=> $b]"
+
+    Of course I should still be able to do all this \e[4mwith\e[m escape sequences too:
+    "$self->method()" and "$self->{FIELDNAME}" and "{FOO=>BAR}".
+
+    Dont forget "$self->method()->{FIELDNAME} = {FOO=>BAR}".
+
+    And make sure that 0 works too!
+
+    Now, if I use << or >> as my delimiters, then I have to use whitespace. So
+    things like "<$self-"method()>> and "<$self-"{FIELDNAME}>> wont end up
+    doing what you might expect since the first > will still terminate the
+    first < seen.
+
+    Lets make sure these work for empty ones too, like and ">>" (just to be
+    obnoxious)
+
+    The statement: "This is dog kind's \e[4mfinest\e[m hour!" is a parody of a
+    quotation from Winston Churchill.
+
+    The following tests are added to those:
+
+    Make sure that a few other odd \e[4mthings\e[m still work. This should be a
+    vertical bar: |. Here's a test of a few more special escapes that have to
+    be supported:
+
+    &  An ampersand.
+
+    '  An apostrophe.
+
+    <  A less-than sign.
+
+    >  A greater-than sign.
+
+    "  A double quotation mark.
+
+    /  A forward slash.
+
+    Try to get this bit of text over towards the edge so
+    |that all of this text inside S<> won't| be wrapped. Also test the
+    |same thing with non-breaking spaces.|
+
+    There is a soft hyphen in hyphen at hy-phen.
+
+    This is a test of an index entry.
+
+\e[1mVERBATIM\e[m
+    Throw in a few verbatim paragraphs.
+
+        use Term::ANSIColor;
+        print color 'bold blue';
+        print "This text is bold blue.\n";
+        print color 'reset';
+        print "This text is normal.\n";
+        print colored ("Yellow on magenta.\n", 'yellow on_magenta');
+        print "This text is normal.\n";
+        print colored ['yellow on_magenta'], "Yellow on magenta.\n";
+
+        use Term::ANSIColor qw(uncolor);
+        print uncolor '01;31', "\n";
+
+    But this isn't verbatim (make sure it wraps properly), and the next
+    paragraph is again:
+
+        use Term::ANSIColor qw(:constants);
+        print BOLD, BLUE, "This text is in bold blue.\n", RESET;
+
+        use Term::ANSIColor qw(:constants); $Term::ANSIColor::AUTORESET = 1; print BOLD BLUE "This text is in bold blue.\n"; print "This text is normal.\n";
+
+    (Ugh, that's obnoxiously long.) Try different spacing:
+
+            Starting with a tab.
+    Not
+    starting
+    with
+    a
+    tab.  But this should still be verbatim.
+     As should this.
+
+    This isn't.
+
+     This is.  And this:    is an internal tab.  It should be:
+                        |--| <= lined up with that.
+
+    (Tricky, but tabs should be expanded before the translator starts in on
+    the text since otherwise text with mixed tabs and spaces will get messed
+    up.)
+
diff --git a/lib/Pod/t/basic.clr b/lib/Pod/t/basic.clr
new file mode 100644 (file)
index 0000000..b9d1cad
--- /dev/null
@@ -0,0 +1,284 @@
+\e[1mNAME\e[0m
+    basic.pod - Test of various basic POD features in translators.
+
+\e[1mHEADINGS\e[0m
+    Try a few different levels of headings, with embedded formatting codes
+    and other interesting bits.
+
+\e[1mThis "is" a "level 1" heading\e[0m
+  \e[1m``Level'' "2 \e[33mheading\e[0m\e[0m
+   Level 3 \e[1mheading \e[33mwith "weird \e[36mstuff "" (double quote)\e[0m"\e[0m\e[0m
+   Level "4 "heading"
+    Now try again with \e[1mintermixed\e[0m \e[36mtext\e[0m.
+
+\e[1mThis "is" a "level 1" heading\e[0m
+    Text.
+
+  \e[1m``Level'' 2 \e[33mheading\e[0m\e[0m
+    Text.
+
+   Level 3 \e[1mheading \e[33mwith "weird \e[36mstuff\e[0m"\e[0m\e[0m
+    Text.
+
+   Level "4 "heading"
+    Text.
+
+\e[1mLINKS\e[0m
+    These are all taken from the Pod::Parser tests.
+
+    Try out \e[33mLOTS\e[0m of different ways of specifying references:
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "manpage/section"
+
+    Reference the "section" in "manpage"
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Now try it using the new "|" stuff ...
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    And then throw in a few new ones of my own.
+
+    foo
+
+    foo
+
+    "bar" in foo
+
+    "baz boo" in foo
+
+    "bar"
+
+    "baz boo"
+
+    "baz boo"
+
+    "baz boo" in foo bar
+
+    "baz boo" in foo bar
+
+    "boo" in foo bar baz
+
+    "boo var baz"
+
+    "bar baz"
+
+    "boo bar baz / baz boo"
+
+    "boo", "bar", and "baz"
+
+    foobar
+
+    Testing \e[33mitalics\e[0m
+
+    "\e[33mItalic\e[0m text" in foo
+
+    "Section "with" \e[33m\e[1mother\e[0m markup\e[0m" in foo|bar
+
+    Nested <http://www.perl.org/>
+
+\e[1mOVER AND ITEMS\e[0m
+    Taken from Pod::Parser tests, this is a test to ensure that multiline
+    =item paragraphs get indented appropriately.
+
+    This is a test.
+
+    There should be whitespace now before this line.
+
+    Taken from Pod::Parser tests, this is a test to ensure the nested =item
+    paragraphs get indented appropriately.
+
+    1 First section.
+
+      a this is item a
+
+      b this is item b
+
+    2 Second section.
+
+      a this is item a
+
+      b this is item b
+
+      c
+      d This is item c & d.
+
+    Now some additional weirdness of our own. Make sure that multiple tags
+    for one paragraph are properly compacted.
+
+    "foo"
+    \e[1mbar\e[0m
+    "baz"
+        There shouldn't be any spaces between any of these item tags; this
+        idiom is used in perlfunc.
+
+    Some longer item text
+        Just to make sure that we test paragraphs where the item text
+        doesn't fit in the margin of the paragraph (and make sure that this
+        paragraph fills a few lines).
+
+        Let's also make it multiple paragraphs to be sure that works.
+
+    Test use of =over without =item as a block "quote" or block paragraph.
+
+        This should be indented four spaces but otherwise formatted the same
+        as any other regular text paragraph. Make sure it's long enough to
+        see the results of the formatting.....
+
+    Now try the same thing nested, and make sure that the indentation is
+    reset back properly.
+
+            This paragraph should be doubly indented.
+
+        This paragraph should only be singly indented.
+
+        *   This is an item in the middle of a block-quote, which should be
+            allowed.
+
+        *   We're also testing tagless item commands.
+
+        Should be back to the single level of indentation.
+
+    Should be back to regular indentation.
+
+    Now also check the transformation of * into real bullets for man pages.
+
+    *   An item. We're also testing using =over without a number, and making
+        sure that item text wraps properly.
+
+    *   Another item.
+
+    and now test the numbering of item blocks.
+
+    1.  First item.
+
+    2.  Second item.
+
+\e[1mFORMATTING CODES\e[0m
+    Another test taken from Pod::Parser.
+
+    This is a test to see if I can do not only $self and "method()", but
+    also "$self->method()" and "$self->{FIELDNAME}" and "$Foo <=> $Bar"
+    without resorting to escape sequences. If I want to refer to the
+    right-shift operator I can do something like "$x >> 3" or even "$y >>
+    5".
+
+    Now for the grand finale of "$self->method()->{FIELDNAME} = {FOO=>BAR}".
+    And I also want to make sure that newlines work like this
+    "$self->{FOOBAR} >> 3 and [$b => $a]->[$a <=> $b]"
+
+    Of course I should still be able to do all this \e[33mwith\e[0m escape sequences
+    too: "$self->method()" and "$self->{FIELDNAME}" and "{FOO=>BAR}".
+
+    Dont forget "$self->method()->{FIELDNAME} = {FOO=>BAR}".
+
+    And make sure that 0 works too!
+
+    Now, if I use << or >> as my delimiters, then I have to use whitespace.
+    So things like "<$self-"method()>> and "<$self-"{FIELDNAME}>> wont end
+    up doing what you might expect since the first > will still terminate
+    the first < seen.
+
+    Lets make sure these work for empty ones too, like and ">>" (just to be
+    obnoxious)
+
+    The statement: "This is dog kind's \e[33mfinest\e[0m hour!" is a parody of a
+    quotation from Winston Churchill.
+
+    The following tests are added to those:
+
+    Make sure that a few other odd \e[33mthings\e[0m still work. This should be a
+    vertical bar: |. Here's a test of a few more special escapes that have
+    to be supported:
+
+    &  An ampersand.
+
+    '  An apostrophe.
+
+    <  A less-than sign.
+
+    >  A greater-than sign.
+
+    "  A double quotation mark.
+
+    /  A forward slash.
+
+    Try to get this bit of text over towards the edge so
+    |that all of this text inside S<> won't| be wrapped. Also test the
+    |same thing with non-breaking spaces.|
+
+    There is a soft hyphen in hyphen at hy-phen.
+
+    This is a test of an index entry.
+
+\e[1mVERBATIM\e[0m
+    Throw in a few verbatim paragraphs.
+
+        use Term::ANSIColor;
+        print color 'bold blue';
+        print "This text is bold blue.\n";
+        print color 'reset';
+        print "This text is normal.\n";
+        print colored ("Yellow on magenta.\n", 'yellow on_magenta');
+        print "This text is normal.\n";
+        print colored ['yellow on_magenta'], "Yellow on magenta.\n";
+
+        use Term::ANSIColor qw(uncolor);
+        print uncolor '01;31', "\n";
+
+    But this isn't verbatim (make sure it wraps properly), and the next
+    paragraph is again:
+
+        use Term::ANSIColor qw(:constants);
+        print BOLD, BLUE, "This text is in bold blue.\n", RESET;
+
+        use Term::ANSIColor qw(:constants); $Term::ANSIColor::AUTORESET = 1; print BOLD BLUE "This text is in bold blue.\n"; print "This text is normal.\n";
+
+    (Ugh, that's obnoxiously long.) Try different spacing:
+
+            Starting with a tab.
+    Not
+    starting
+    with
+    a
+    tab.  But this should still be verbatim.
+     As should this.
+
+    This isn't.
+
+     This is.  And this:    is an internal tab.  It should be:
+                        |--| <= lined up with that.
+
+    (Tricky, but tabs should be expanded before the translator starts in on
+    the text since otherwise text with mixed tabs and spaces will get messed
+    up.)
+
diff --git a/lib/Pod/t/basic.man b/lib/Pod/t/basic.man
new file mode 100644 (file)
index 0000000..68434f3
--- /dev/null
@@ -0,0 +1,335 @@
+.UC
+.SH "NAME"
+basic.pod \- Test of various basic \s-1POD\s0 features in translators.
+.SH "HEADINGS"
+.IX Header "HEADINGS"
+Try a few different levels of headings, with embedded formatting codes and
+other interesting bits.
+.ie n .SH "This ""is"" a ""level 1"" heading"
+.el .SH "This \f(CWis\fP a ``level 1'' heading"
+.IX Header "This is a level 1 heading"
+.Sh "``Level'' ""2 \fIheading\fP"
+.IX Subsection "``Level'' ""2 heading"
+\fILevel 3 \f(BIheading \f(BIwith \f(CB\*(C`weird \f(CBstuff "" (double quote)\f(CB\*(C'\f(BI\f(BI\fI\fR
+.IX Subsection "Level 3 heading with weird stuff """" (double quote)"
+.PP
+Level "4 \f(CW\*(C`heading\*(C'\fR
+.IX Subsection "Level ""4 heading"
+.PP
+Now try again with \fBintermixed\fR \fItext\fR.
+.ie n .SH "This ""is"" a ""level 1"" heading"
+.el .SH "This \f(CWis\fP a ``level 1'' heading"
+.IX Header "This is a level 1 heading"
+Text.
+.Sh "``Level'' 2 \fIheading\fP"
+.IX Subsection "``Level'' 2 heading"
+Text.
+.PP
+\fILevel 3 \f(BIheading \f(BIwith \f(CB\*(C`weird \f(CBstuff\f(CB\*(C'\f(BI\f(BI\fI\fR
+.IX Subsection "Level 3 heading with weird stuff"
+.PP
+Text.
+.PP
+Level "4 \f(CW\*(C`heading\*(C'\fR
+.IX Subsection "Level ""4 heading"
+.PP
+Text.
+.SH "LINKS"
+.IX Header "LINKS"
+These are all taken from the Pod::Parser tests.
+.PP
+Try out \fI\s-1LOTS\s0\fR of different ways of specifying references:
+.PP
+Reference the \*(L"section\*(R" in manpage
+.PP
+Reference the \*(L"section\*(R" in manpage
+.PP
+Reference the \*(L"section\*(R" in manpage
+.PP
+Reference the \*(L"section\*(R" in manpage
+.PP
+Reference the \*(L"manpage/section\*(R"
+.PP
+Reference the \*(L"section\*(R" in \*(L"manpage\*(R"
+.PP
+Reference the \*(L"section\*(R" in manpage
+.PP
+Reference the \*(L"section\*(R" in manpage
+.PP
+Reference the \*(L"section\*(R" in manpage
+.PP
+Now try it using the new \*(L"|\*(R" stuff ...
+.PP
+Reference the thistext|
+.PP
+Reference the thistext |
+.PP
+Reference the thistext|
+.PP
+Reference the thistext |
+.PP
+Reference the thistext|
+.PP
+Reference the thistext |
+.PP
+Reference the thistext|
+.PP
+Reference the thistext|
+.PP
+Reference the thistext |
+.PP
+And then throw in a few new ones of my own.
+.PP
+foo
+.PP
+foo
+.PP
+\&\*(L"bar\*(R" in foo
+.PP
+\&\*(L"baz boo\*(R" in foo
+.PP
+\&\*(L"bar\*(R"
+.PP
+\&\*(L"baz boo\*(R"
+.PP
+\&\*(L"baz boo\*(R"
+.PP
+\&\*(L"baz boo\*(R" in foo bar
+.PP
+\&\*(L"baz boo\*(R" in foo bar
+.PP
+\&\*(L"boo\*(R" in foo bar baz
+.PP
+\&\*(L"boo var baz\*(R"
+.PP
+\&\*(L"bar baz\*(R"
+.PP
+\&\*(L"boo bar baz / baz boo\*(R"
+.PP
+\&\*(L"boo\*(R", \*(L"bar\*(R", and \*(L"baz\*(R"
+.PP
+foo\&bar
+.PP
+Testing \fIitalics\fR
+.PP
+"\fIItalic\fR text" in foo
+.PP
+"Section \f(CW\*(C`with\*(C'\fR \fI\f(BIother\fI markup\fR" in foo|bar\&
+.PP
+Nested <http://www.perl.org/>
+.SH "OVER AND ITEMS"
+.IX Header "OVER AND ITEMS"
+Taken from Pod::Parser tests, this is a test to ensure that multiline
+=item paragraphs get indented appropriately.
+.IP "This is a test." 4
+.IX Item "This is a test."
+.PP
+There should be whitespace now before this line.
+.PP
+Taken from Pod::Parser tests, this is a test to ensure the nested =item
+paragraphs get indented appropriately.
+.IP "1" 2
+.IX Item "1"
+First section.
+.RS 2
+.IP "a" 2
+.IX Item "a"
+this is item a
+.IP "b" 2
+.IX Item "b"
+this is item b
+.RE
+.RS 2
+.RE
+.IP "2" 2
+.IX Item "2"
+Second section.
+.RS 2
+.IP "a" 2
+.IX Item "a"
+this is item a
+.IP "b" 2
+.IX Item "b"
+this is item b
+.IP "c" 2
+.IX Item "c"
+.PD 0
+.IP "d" 2
+.IX Item "d"
+.PD
+This is item c & d.
+.RE
+.RS 2
+.RE
+.PP
+Now some additional weirdness of our own.  Make sure that multiple tags
+for one paragraph are properly compacted.
+.ie n .IP """foo""" 4
+.el .IP "``foo''" 4
+.IX Item "foo"
+.PD 0
+.IP "\fBbar\fR" 4
+.IX Item "bar"
+.ie n .IP """baz""" 4
+.el .IP "\f(CWbaz\fR" 4
+.IX Item "baz"
+.PD
+There shouldn't be any spaces between any of these item tags; this idiom
+is used in perlfunc.
+.IP "Some longer item text" 4
+.IX Item "Some longer item text"
+Just to make sure that we test paragraphs where the item text doesn't fit
+in the margin of the paragraph (and make sure that this paragraph fills a
+few lines).
+.Sp
+Let's also make it multiple paragraphs to be sure that works.
+.PP
+Test use of =over without =item as a block \*(L"quote\*(R" or block paragraph.
+.Sp
+.RS 4
+This should be indented four spaces but otherwise formatted the same as
+any other regular text paragraph.  Make sure it's long enough to see the
+results of the formatting.....
+.RE
+.PP
+Now try the same thing nested, and make sure that the indentation is reset
+back properly.
+.RS 4
+.Sp
+.RS 4
+This paragraph should be doubly indented.
+.RE
+.RE
+.RS 4
+.Sp
+This paragraph should only be singly indented.
+.IP "\(bu" 4
+This is an item in the middle of a block\-quote, which should be allowed.
+.IP "\(bu" 4
+We're also testing tagless item commands.
+.RE
+.RS 4
+.Sp
+Should be back to the single level of indentation.
+.RE
+.PP
+Should be back to regular indentation.
+.PP
+Now also check the transformation of * into real bullets for man pages.
+.IP "\(bu" 4
+An item.  We're also testing using =over without a number, and making sure
+that item text wraps properly.
+.IP "\(bu" 4
+Another item.
+.PP
+and now test the numbering of item blocks.
+.IP "1." 4
+First item.
+.IP "2." 4
+Second item.
+.SH "FORMATTING CODES"
+.IX Header "FORMATTING CODES"
+Another test taken from Pod::Parser.
+.PP
+This is a test to see if I can do not only \f(CW$self\fR and \f(CW\*(C`method()\*(C'\fR, but
+also \f(CW\*(C`$self\->method()\*(C'\fR and \f(CW\*(C`$self\->{FIELDNAME}\*(C'\fR and
+\&\f(CW\*(C`$Foo <=> $Bar\*(C'\fR without resorting to escape sequences. If 
+I want to refer to the right-shift operator I can do something
+like \f(CW\*(C`$x >> 3\*(C'\fR or even \f(CW\*(C`$y >> 5\*(C'\fR.
+.PP
+Now for the grand finale of \f(CW\*(C`$self\->method()\->{FIELDNAME} = {FOO=>BAR}\*(C'\fR.
+And I also want to make sure that newlines work like this
+\&\f(CW\*(C`$self\->{FOOBAR} >> 3 and [$b => $a]\->[$a <=> $b]\*(C'\fR
+.PP
+Of course I should still be able to do all this \fIwith\fR escape sequences
+too: \f(CW\*(C`$self\->method()\*(C'\fR and \f(CW\*(C`$self\->{FIELDNAME}\*(C'\fR and
+\&\f(CW\*(C`{FOO=>BAR}\*(C'\fR.
+.PP
+Dont forget \f(CW\*(C`$self\->method()\->{FIELDNAME} = {FOO=>BAR}\*(C'\fR.
+.PP
+And make sure that \f(CW0\fR works too!
+.PP
+Now, if I use << or >> as my delimiters, then I have to use whitespace.
+So things like \f(CW\*(C`<$self\-\*(C'\fR\fImethod()\fR>> and \f(CW\*(C`<$self\-\*(C'\fR{\s-1FIELDNAME\s0}>> wont end
+up doing what you might expect since the first > will still terminate
+the first < seen.
+.PP
+Lets make sure these work for empty ones too, like  and \f(CW\*(C`>>\*(C'\fR
+(just to be obnoxious)
+.PP
+The statement: \f(CW\*(C`This is dog kind's \f(CIfinest\f(CW hour!\*(C'\fR is a parody of a
+quotation from Winston Churchill.
+.PP
+The following tests are added to those:
+.PP
+Make sure that a few oth\&er odd \fI\&things\fR still work.  This should be
+a vertical bar:  |.  Here's a test of a few more special escapes
+that have to be supported:
+.IP "&" 3
+An ampersand.
+.IP "'" 3
+An apostrophe.
+.IP "<" 3
+A less-than sign.
+.IP ">" 3
+A greater-than sign.
+.IP """" 3
+A double quotation mark.
+.IP "/" 3
+A forward slash.
+.PP
+Try to get this bit of text over towards the edge so |that\ all\ of\ this\ text\ inside\ S<>\ won't| be wrapped.  Also test the
+|same\ thing\ with\ non-breaking\ spaces.|
+.PP
+There is a soft hyphen in hyphen at hy\-phen.
+.PP
+This is a test of an index entry.
+.IX Xref "index entry"
+.SH "VERBATIM"
+.IX Header "VERBATIM"
+Throw in a few verbatim paragraphs.
+.PP
+.Vb 8
+\&    use Term::ANSIColor;
+\&    print color 'bold blue';
+\&    print "This text is bold blue.\en";
+\&    print color 'reset';
+\&    print "This text is normal.\en";
+\&    print colored ("Yellow on magenta.\en", 'yellow on_magenta');
+\&    print "This text is normal.\en";
+\&    print colored ['yellow on_magenta'], "Yellow on magenta.\en";
+.Ve
+.Vb 2
+\&    use Term::ANSIColor qw(uncolor);
+\&    print uncolor '01;31', "\en";
+.Ve
+But this isn't verbatim (make sure it wraps properly), and the next
+paragraph is again:
+.PP
+.Vb 2
+\&    use Term::ANSIColor qw(:constants);
+\&    print BOLD, BLUE, "This text is in bold blue.\en", RESET;
+.Ve
+.Vb 1
+\&    use Term::ANSIColor qw(:constants); $Term::ANSIColor::AUTORESET = 1; print BOLD BLUE "This text is in bold blue.\en"; print "This text is normal.\en";
+.Ve
+(Ugh, that's obnoxiously long.)  Try different spacing:
+.PP
+.Vb 7
+\&        Starting with a tab.
+\&Not
+\&starting
+\&with
+\&a
+\&tab.  But this should still be verbatim.
+\& As should this.
+.Ve
+This isn't.
+.PP
+.Vb 2
+\& This is.  And this:    is an internal tab.  It should be:
+\&                    |--| <= lined up with that.
+.Ve
+(Tricky, but tabs should be expanded before the translator starts in on
+the text since otherwise text with mixed tabs and spaces will get messed
+up.)
diff --git a/lib/Pod/t/basic.ovr b/lib/Pod/t/basic.ovr
new file mode 100644 (file)
index 0000000..b20ca08
--- /dev/null
@@ -0,0 +1,284 @@
+N\bNA\bAM\bME\bE
+    basic.pod - Test of various basic POD features in translators.
+
+H\bHE\bEA\bAD\bDI\bIN\bNG\bGS\bS
+    Try a few different levels of headings, with embedded formatting codes
+    and other interesting bits.
+
+T\bTh\bhi\bis\b\b "\b"i\bis\bs"\b\b a\b\b "\b"l\ble\bev\bve\bel\b\b 1\b1"\b\b h\bhe\bea\bad\bdi\bin\bng\bg
+  `\b``\b`L\bLe\bev\bve\bel\bl'\b''\b\b "\b"2\b\b h\bhe\bea\bad\bdi\bin\bng\bg
+   _\bL_\be_\bv_\be_\bl_\b _\b3_\b _\bh_\be_\ba_\bd_\bi_\bn_\bg_\b _\bw_\bi_\bt_\bh_\b _\b"_\bw_\be_\bi_\br_\bd_\b _\bs_\bt_\bu_\bf_\bf_\b _\b"_\b"_\b _\b(_\bd_\bo_\bu_\bb_\bl_\be_\b _\bq_\bu_\bo_\bt_\be_\b)_\b"
+   _\bL_\be_\bv_\be_\bl_\b _\b"_\b4_\b _\b"_\bh_\be_\ba_\bd_\bi_\bn_\bg_\b"
+    Now try again with i\bin\bnt\bte\ber\brm\bmi\bix\bxe\bed\bd _\bt_\be_\bx_\bt.
+
+T\bTh\bhi\bis\b\b "\b"i\bis\bs"\b\b a\b\b "\b"l\ble\bev\bve\bel\b\b 1\b1"\b\b h\bhe\bea\bad\bdi\bin\bng\bg
+    Text.
+
+  `\b``\b`L\bLe\bev\bve\bel\bl'\b''\b\b 2\b\b h\bhe\bea\bad\bdi\bin\bng\bg
+    Text.
+
+   _\bL_\be_\bv_\be_\bl_\b _\b3_\b _\bh_\be_\ba_\bd_\bi_\bn_\bg_\b _\bw_\bi_\bt_\bh_\b _\b"_\bw_\be_\bi_\br_\bd_\b _\bs_\bt_\bu_\bf_\bf_\b"
+    Text.
+
+   _\bL_\be_\bv_\be_\bl_\b _\b"_\b4_\b _\b"_\bh_\be_\ba_\bd_\bi_\bn_\bg_\b"
+    Text.
+
+L\bLI\bIN\bNK\bKS\bS
+    These are all taken from the Pod::Parser tests.
+
+    Try out _\bL_\bO_\bT_\bS of different ways of specifying references:
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "manpage/section"
+
+    Reference the "section" in "manpage"
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Now try it using the new "|" stuff ...
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    And then throw in a few new ones of my own.
+
+    foo
+
+    foo
+
+    "bar" in foo
+
+    "baz boo" in foo
+
+    "bar"
+
+    "baz boo"
+
+    "baz boo"
+
+    "baz boo" in foo bar
+
+    "baz boo" in foo bar
+
+    "boo" in foo bar baz
+
+    "boo var baz"
+
+    "bar baz"
+
+    "boo bar baz / baz boo"
+
+    "boo", "bar", and "baz"
+
+    foobar
+
+    Testing _\bi_\bt_\ba_\bl_\bi_\bc_\bs
+
+    "_\bI_\bt_\ba_\bl_\bi_\bc text" in foo
+
+    "Section "with" _\bo_\bt_\bh_\be_\br_\b _\bm_\ba_\br_\bk_\bu_\bp" in foo|bar
+
+    Nested <http://www.perl.org/>
+
+O\bOV\bVE\bER\b\b A\bAN\bND\b\b I\bIT\bTE\bEM\bMS\bS
+    Taken from Pod::Parser tests, this is a test to ensure that multiline
+    =item paragraphs get indented appropriately.
+
+    This is a test.
+
+    There should be whitespace now before this line.
+
+    Taken from Pod::Parser tests, this is a test to ensure the nested =item
+    paragraphs get indented appropriately.
+
+    1 First section.
+
+      a this is item a
+
+      b this is item b
+
+    2 Second section.
+
+      a this is item a
+
+      b this is item b
+
+      c
+      d This is item c & d.
+
+    Now some additional weirdness of our own. Make sure that multiple tags
+    for one paragraph are properly compacted.
+
+    "foo"
+    b\bba\bar\br
+    "baz"
+        There shouldn't be any spaces between any of these item tags; this
+        idiom is used in perlfunc.
+
+    Some longer item text
+        Just to make sure that we test paragraphs where the item text
+        doesn't fit in the margin of the paragraph (and make sure that this
+        paragraph fills a few lines).
+
+        Let's also make it multiple paragraphs to be sure that works.
+
+    Test use of =over without =item as a block "quote" or block paragraph.
+
+        This should be indented four spaces but otherwise formatted the same
+        as any other regular text paragraph. Make sure it's long enough to
+        see the results of the formatting.....
+
+    Now try the same thing nested, and make sure that the indentation is
+    reset back properly.
+
+            This paragraph should be doubly indented.
+
+        This paragraph should only be singly indented.
+
+        *   This is an item in the middle of a block-quote, which should be
+            allowed.
+
+        *   We're also testing tagless item commands.
+
+        Should be back to the single level of indentation.
+
+    Should be back to regular indentation.
+
+    Now also check the transformation of * into real bullets for man pages.
+
+    *   An item. We're also testing using =over without a number, and making
+        sure that item text wraps properly.
+
+    *   Another item.
+
+    and now test the numbering of item blocks.
+
+    1.  First item.
+
+    2.  Second item.
+
+F\bFO\bOR\bRM\bMA\bAT\bTT\bTI\bIN\bNG\b\b C\bCO\bOD\bDE\bES\bS
+    Another test taken from Pod::Parser.
+
+    This is a test to see if I can do not only $self and "method()", but
+    also "$self->method()" and "$self->{FIELDNAME}" and "$Foo <=> $Bar"
+    without resorting to escape sequences. If I want to refer to the
+    right-shift operator I can do something like "$x >> 3" or even "$y >>
+    5".
+
+    Now for the grand finale of "$self->method()->{FIELDNAME} = {FOO=>BAR}".
+    And I also want to make sure that newlines work like this
+    "$self->{FOOBAR} >> 3 and [$b => $a]->[$a <=> $b]"
+
+    Of course I should still be able to do all this _\bw_\bi_\bt_\bh escape sequences
+    too: "$self->method()" and "$self->{FIELDNAME}" and "{FOO=>BAR}".
+
+    Dont forget "$self->method()->{FIELDNAME} = {FOO=>BAR}".
+
+    And make sure that 0 works too!
+
+    Now, if I use << or >> as my delimiters, then I have to use whitespace.
+    So things like "<$self-"method()>> and "<$self-"{FIELDNAME}>> wont end
+    up doing what you might expect since the first > will still terminate
+    the first < seen.
+
+    Lets make sure these work for empty ones too, like and ">>" (just to be
+    obnoxious)
+
+    The statement: "This is dog kind's _\bf_\bi_\bn_\be_\bs_\bt hour!" is a parody of a
+    quotation from Winston Churchill.
+
+    The following tests are added to those:
+
+    Make sure that a few other odd _\bt_\bh_\bi_\bn_\bg_\bs still work. This should be a
+    vertical bar: |. Here's a test of a few more special escapes that have
+    to be supported:
+
+    &  An ampersand.
+
+    '  An apostrophe.
+
+    <  A less-than sign.
+
+    >  A greater-than sign.
+
+    "  A double quotation mark.
+
+    /  A forward slash.
+
+    Try to get this bit of text over towards the edge so
+    |that all of this text inside S<> won't| be wrapped. Also test the
+    |same thing with non-breaking spaces.|
+
+    There is a soft hyphen in hyphen at hy-phen.
+
+    This is a test of an index entry.
+
+V\bVE\bER\bRB\bBA\bAT\bTI\bIM\bM
+    Throw in a few verbatim paragraphs.
+
+        use Term::ANSIColor;
+        print color 'bold blue';
+        print "This text is bold blue.\n";
+        print color 'reset';
+        print "This text is normal.\n";
+        print colored ("Yellow on magenta.\n", 'yellow on_magenta');
+        print "This text is normal.\n";
+        print colored ['yellow on_magenta'], "Yellow on magenta.\n";
+
+        use Term::ANSIColor qw(uncolor);
+        print uncolor '01;31', "\n";
+
+    But this isn't verbatim (make sure it wraps properly), and the next
+    paragraph is again:
+
+        use Term::ANSIColor qw(:constants);
+        print BOLD, BLUE, "This text is in bold blue.\n", RESET;
+
+        use Term::ANSIColor qw(:constants); $Term::ANSIColor::AUTORESET = 1; print BOLD BLUE "This text is in bold blue.\n"; print "This text is normal.\n";
+
+    (Ugh, that's obnoxiously long.) Try different spacing:
+
+            Starting with a tab.
+    Not
+    starting
+    with
+    a
+    tab.  But this should still be verbatim.
+     As should this.
+
+    This isn't.
+
+     This is.  And this:    is an internal tab.  It should be:
+                        |--| <= lined up with that.
+
+    (Tricky, but tabs should be expanded before the translator starts in on
+    the text since otherwise text with mixed tabs and spaces will get messed
+    up.)
+
diff --git a/lib/Pod/t/basic.pod b/lib/Pod/t/basic.pod
new file mode 100644 (file)
index 0000000..de76060
--- /dev/null
@@ -0,0 +1,407 @@
+=head1 NAME
+
+basic.pod - Test of various basic POD features in translators.
+
+=head1 HEADINGS
+
+Try a few different levels of headings, with embedded formatting codes and
+other interesting bits.
+
+=head1 This C<is> a "level 1" heading
+
+=head2 ``Level'' "2 I<heading>
+
+=head3 Level 3 B<heading I<with C<weird F<stuff "" (double quote)>>>>
+
+=head4 Level "4 C<heading>
+
+Now try again with B<intermixed> F<text>.
+
+=head1 This C<is> a "level 1" heading
+
+Text.
+
+=head2 ``Level'' 2 I<heading>
+
+Text.
+
+=head3 Level 3 B<heading I<with C<weird F<stuff>>>>
+
+Text.
+
+=head4 Level "4 C<heading>
+
+Text.
+
+=head1 LINKS
+
+These are all taken from the Pod::Parser tests.
+
+Try out I<LOTS> of different ways of specifying references:
+
+Reference the L<manpage/section>
+
+Reference the L<manpage / section>
+
+Reference the L<manpage/ section>
+
+Reference the L<manpage /section>
+
+Reference the L<"manpage/section">
+
+Reference the L<"manpage"/section>
+
+Reference the L<manpage/"section">
+
+Reference the L<manpage/
+section>
+
+Reference the L<manpage
+/section>
+
+Now try it using the new "|" stuff ...
+
+Reference the L<thistext|manpage/section>|
+
+Reference the L<thistext | manpage / section>|
+
+Reference the L<thistext| manpage/ section>|
+
+Reference the L<thistext |manpage /section>|
+
+Reference the L<thistext|
+"manpage/section">|
+
+Reference the L<thistext
+|"manpage"/section>|
+
+Reference the L<thistext|manpage/"section">|
+
+Reference the L<thistext|
+manpage/
+section>|
+
+Reference the L<thistext
+|manpage
+/section>|
+
+And then throw in a few new ones of my own.
+
+L<foo>
+
+L<foo|bar>
+
+L<foo/bar>
+
+L<foo/"baz boo">
+
+L</bar>
+
+L</"baz boo">
+
+L</baz boo>
+
+L<foo bar/baz boo>
+
+L<foo bar  /  baz boo>
+
+L<foo
+bar
+baz
+/
+boo>
+
+L<"boo var baz">
+
+L<bar baz>
+
+L<"boo bar baz / baz boo">
+
+L</boo>, L</bar>, and L</baz>
+
+L<fooZ<>bar>
+
+L<Testing I<italics>|foo/bar>
+
+L<foo/I<Italic> text>
+
+L<fooE<verbar>barZ<>/Section C<with> I<B<other> markup>>
+
+L<Nested L<http://www.perl.org/>|fooE<sol>bar>
+
+=head1 OVER AND ITEMS
+
+Taken from Pod::Parser tests, this is a test to ensure that multiline
+=item paragraphs get indented appropriately.
+
+=over 4 
+
+=item This 
+is
+a
+test.
+
+=back
+
+There should be whitespace now before this line.
+
+Taken from Pod::Parser tests, this is a test to ensure the nested =item
+paragraphs get indented appropriately.
+
+=over 2
+
+=item 1
+
+First section.
+
+=over 2
+
+=item a
+
+this is item a
+
+=item b
+
+this is item b
+
+=back
+
+=item 2
+
+Second section.
+
+=over 2
+
+=item a
+
+this is item a
+
+=item b
+
+this is item b
+
+=item c
+
+=item d
+
+This is item c & d.
+
+=back
+
+=back
+
+Now some additional weirdness of our own.  Make sure that multiple tags
+for one paragraph are properly compacted.
+
+=over 4
+
+=item "foo"
+
+=item B<bar>
+
+=item C<baz>
+
+There shouldn't be any spaces between any of these item tags; this idiom
+is used in perlfunc.
+
+=item Some longer item text
+
+Just to make sure that we test paragraphs where the item text doesn't fit
+in the margin of the paragraph (and make sure that this paragraph fills a
+few lines).
+
+Let's also make it multiple paragraphs to be sure that works.
+
+=back
+
+Test use of =over without =item as a block "quote" or block paragraph.
+
+=over 4
+
+This should be indented four spaces but otherwise formatted the same as
+any other regular text paragraph.  Make sure it's long enough to see the
+results of the formatting.....
+
+=back
+
+Now try the same thing nested, and make sure that the indentation is reset
+back properly.
+
+=over 4
+
+=over 4
+
+This paragraph should be doubly indented.
+
+=back
+
+This paragraph should only be singly indented.
+
+=over 4
+
+=item
+
+This is an item in the middle of a block-quote, which should be allowed.
+
+=item
+
+We're also testing tagless item commands.
+
+=back
+
+Should be back to the single level of indentation.
+
+=back
+
+Should be back to regular indentation.
+
+Now also check the transformation of * into real bullets for man pages.
+
+=over
+
+=item *
+
+An item.  We're also testing using =over without a number, and making sure
+that item text wraps properly.
+
+=item *
+
+Another item.
+
+=back
+
+and now test the numbering of item blocks.
+
+=over 4
+
+=item 1.
+
+First item.
+
+=item 2.
+
+Second item.
+
+=back
+
+=head1 FORMATTING CODES
+
+Another test taken from Pod::Parser.
+
+This is a test to see if I can do not only C<$self> and C<method()>, but
+also C<< $self->method() >> and C<< $self->{FIELDNAME} >> and
+C<< $Foo <=> $Bar >> without resorting to escape sequences. If 
+I want to refer to the right-shift operator I can do something
+like C<<< $x >> 3 >>> or even C<<<< $y >> 5 >>>>.
+
+Now for the grand finale of C<< $self->method()->{FIELDNAME} = {FOO=>BAR} >>.
+And I also want to make sure that newlines work like this
+C<<<
+$self->{FOOBAR} >> 3 and [$b => $a]->[$a <=> $b]
+>>>
+
+Of course I should still be able to do all this I<with> escape sequences
+too: C<$self-E<gt>method()> and C<$self-E<gt>{FIELDNAME}> and
+C<{FOO=E<gt>BAR}>.
+
+Dont forget C<$self-E<gt>method()-E<gt>{FIELDNAME} = {FOO=E<gt>BAR}>.
+
+And make sure that C<0> works too!
+
+Now, if I use << or >> as my delimiters, then I have to use whitespace.
+So things like C<<$self->method()>> and C<<$self->{FIELDNAME}>> wont end
+up doing what you might expect since the first > will still terminate
+the first < seen.
+
+Lets make sure these work for empty ones too, like C<<  >> and C<< >> >>
+(just to be obnoxious)
+
+The statement: C<This is dog kind's I<finest> hour!> is a parody of a
+quotation from Winston Churchill.
+
+The following tests are added to those:
+
+Make sure that a few othZ<>er odd I<Z<>things> still work.  This should be
+a vertical bar:  E<verbar>.  Here's a test of a few more special escapes
+that have to be supported:
+
+=over 3
+
+=item E<amp>
+
+An ampersand.
+
+=item E<apos>
+
+An apostrophe.
+
+=item E<lt>
+
+A less-than sign.
+
+=item E<gt>
+
+A greater-than sign.
+
+=item E<quot>
+
+A double quotation mark.
+
+=item E<sol>
+
+A forward slash.
+
+=back
+
+Try to get this bit of text over towards the edge so S<|that all of this
+text inside SE<lt>E<gt> won't|> be wrapped.  Also test the
+|sameE<nbsp>thingE<nbsp>withE<nbsp>non-breakingS< spaces>.|
+
+There is a soft hyE<shy>phen in hyphen at hy-phen.
+
+This is a test of an X<index entry>index entry.
+
+=head1 VERBATIM
+
+Throw in a few verbatim paragraphs.
+
+    use Term::ANSIColor;
+    print color 'bold blue';
+    print "This text is bold blue.\n";
+    print color 'reset';
+    print "This text is normal.\n";
+    print colored ("Yellow on magenta.\n", 'yellow on_magenta');
+    print "This text is normal.\n";
+    print colored ['yellow on_magenta'], "Yellow on magenta.\n";
+
+    use Term::ANSIColor qw(uncolor);
+    print uncolor '01;31', "\n";
+
+But this isn't verbatim (make sure it wraps properly), and the next
+paragraph is again:
+
+    use Term::ANSIColor qw(:constants);
+    print BOLD, BLUE, "This text is in bold blue.\n", RESET;
+
+    use Term::ANSIColor qw(:constants); $Term::ANSIColor::AUTORESET = 1; print BOLD BLUE "This text is in bold blue.\n"; print "This text is normal.\n";
+
+(Ugh, that's obnoxiously long.)  Try different spacing:
+
+       Starting with a tab.
+Not
+starting
+with
+a
+tab.  But this should still be verbatim.
+ As should this.
+
+This isn't.
+
+ This is.  And this:   is an internal tab.  It should be:
+                    |--| <= lined up with that.
+
+(Tricky, but tabs should be expanded before the translator starts in on
+the text since otherwise text with mixed tabs and spaces will get messed
+up.)
+
+=cut
diff --git a/lib/Pod/t/basic.t b/lib/Pod/t/basic.t
new file mode 100644 (file)
index 0000000..8e16719
--- /dev/null
@@ -0,0 +1,87 @@
+#!/usr/bin/perl -w
+# $Id: basic.t,v 1.1 2001/11/23 10:09:06 eagle Exp $
+#
+# basic.t -- Basic tests for podlators.
+#
+# Copyright 2001 by Russ Allbery <rra@stanford.edu>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+BEGIN {
+    chdir 't' if -d 't';
+    unshift (@INC, '../blib/lib');
+    $| = 1;
+    print "1..11\n";
+}
+
+END {
+    print "not ok 1\n" unless $loaded;
+}
+
+use Pod::Man;
+use Pod::Text;
+use Pod::Text::Color;
+use Pod::Text::Overstrike;
+use Pod::Text::Termcap;
+
+$loaded = 1;
+print "ok 1\n";
+
+# Hard-code a few values to try to get reproducible results.
+@ENV{qw(TERMCAP COLUMNS)} = ('co=80:do=^J:md=\E[1m:us=\E[4m:me=\E[m', 80);
+
+# Map of translators to file extensions to find the formatted output to
+# compare against.
+my %translators = ('Pod::Man'              => 'man',
+                   'Pod::Text'             => 'txt',
+                   'Pod::Text::Color'      => 'clr',
+                   'Pod::Text::Overstrike' => 'ovr',
+                   'Pod::Text::Termcap'    => 'cap');
+
+# Set default options to match those of pod2man and pod2text.
+%options = (sentence => 0);
+
+my $n = 2;
+for (sort keys %translators) {
+    my $parser = $_->new (%options);
+    print (($parser && ref ($parser) eq $_) ? "ok $n\n" : "not ok $n\n");
+    $n++;
+
+    # For Pod::Man, strip out the autogenerated header up to the .TH title
+    # line.  That means that we don't check those things; oh well.  The header
+    # changes with each version change or touch of the input file.
+    if ($_ eq 'Pod::Man') {
+        $parser->parse_from_file ('basic.pod', 'out.tmp');
+        open (TMP, 'out.tmp') or die "Cannot open out.tmp: $!\n";
+        open (OUTPUT, "> out.$translators{$_}")
+            or die "Cannot create out.$translators{$_}: $!\n";
+        local $_;
+        while (<TMP>) { last if /^\.TH/ }
+        print OUTPUT while <TMP>;
+        close OUTPUT;
+        close TMP;
+        unlink 'out.tmp';
+    } else {
+        $parser->parse_from_file ('basic.pod', "out.$translators{$_}");
+    }
+    {
+        local $/;
+        open (MASTER, "basic.$translators{$_}")
+            or die "Cannot open basic.$translators{$_}: $!\n";
+        open (OUTPUT, "out.$translators{$_}")
+            or die "Cannot open out.$translators{$_}: $!\n";
+        my $master = <MASTER>;
+        my $output = <OUTPUT>;
+        close MASTER;
+        close OUTPUT;
+        if ($master eq $output) {
+            print "ok $n\n";
+            unlink "out.$translators{$_}";
+        } else {
+            print "not ok $n\n";
+            print "# Non-matching output left in out.$translators{$_}\n";
+        }
+    }
+    $n++;
+}
diff --git a/lib/Pod/t/basic.txt b/lib/Pod/t/basic.txt
new file mode 100644 (file)
index 0000000..8052215
--- /dev/null
@@ -0,0 +1,284 @@
+NAME
+    basic.pod - Test of various basic POD features in translators.
+
+HEADINGS
+    Try a few different levels of headings, with embedded formatting codes
+    and other interesting bits.
+
+This "is" a "level 1" heading
+  ``Level'' "2 *heading*
+   Level 3 heading *with "weird stuff "" (double quote)"*
+   Level "4 "heading"
+    Now try again with intermixed text.
+
+This "is" a "level 1" heading
+    Text.
+
+  ``Level'' 2 *heading*
+    Text.
+
+   Level 3 heading *with "weird stuff"*
+    Text.
+
+   Level "4 "heading"
+    Text.
+
+LINKS
+    These are all taken from the Pod::Parser tests.
+
+    Try out *LOTS* of different ways of specifying references:
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "manpage/section"
+
+    Reference the "section" in "manpage"
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Reference the "section" in manpage
+
+    Now try it using the new "|" stuff ...
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    Reference the thistext|
+
+    Reference the thistext|
+
+    Reference the thistext |
+
+    And then throw in a few new ones of my own.
+
+    foo
+
+    foo
+
+    "bar" in foo
+
+    "baz boo" in foo
+
+    "bar"
+
+    "baz boo"
+
+    "baz boo"
+
+    "baz boo" in foo bar
+
+    "baz boo" in foo bar
+
+    "boo" in foo bar baz
+
+    "boo var baz"
+
+    "bar baz"
+
+    "boo bar baz / baz boo"
+
+    "boo", "bar", and "baz"
+
+    foobar
+
+    Testing *italics*
+
+    "*Italic* text" in foo
+
+    "Section "with" *other markup*" in foo|bar
+
+    Nested <http://www.perl.org/>
+
+OVER AND ITEMS
+    Taken from Pod::Parser tests, this is a test to ensure that multiline
+    =item paragraphs get indented appropriately.
+
+    This is a test.
+
+    There should be whitespace now before this line.
+
+    Taken from Pod::Parser tests, this is a test to ensure the nested =item
+    paragraphs get indented appropriately.
+
+    1 First section.
+
+      a this is item a
+
+      b this is item b
+
+    2 Second section.
+
+      a this is item a
+
+      b this is item b
+
+      c
+      d This is item c & d.
+
+    Now some additional weirdness of our own. Make sure that multiple tags
+    for one paragraph are properly compacted.
+
+    "foo"
+    bar
+    "baz"
+        There shouldn't be any spaces between any of these item tags; this
+        idiom is used in perlfunc.
+
+    Some longer item text
+        Just to make sure that we test paragraphs where the item text
+        doesn't fit in the margin of the paragraph (and make sure that this
+        paragraph fills a few lines).
+
+        Let's also make it multiple paragraphs to be sure that works.
+
+    Test use of =over without =item as a block "quote" or block paragraph.
+
+        This should be indented four spaces but otherwise formatted the same
+        as any other regular text paragraph. Make sure it's long enough to
+        see the results of the formatting.....
+
+    Now try the same thing nested, and make sure that the indentation is
+    reset back properly.
+
+            This paragraph should be doubly indented.
+
+        This paragraph should only be singly indented.
+
+        *   This is an item in the middle of a block-quote, which should be
+            allowed.
+
+        *   We're also testing tagless item commands.
+
+        Should be back to the single level of indentation.
+
+    Should be back to regular indentation.
+
+    Now also check the transformation of * into real bullets for man pages.
+
+    *   An item. We're also testing using =over without a number, and making
+        sure that item text wraps properly.
+
+    *   Another item.
+
+    and now test the numbering of item blocks.
+
+    1.  First item.
+
+    2.  Second item.
+
+FORMATTING CODES
+    Another test taken from Pod::Parser.
+
+    This is a test to see if I can do not only $self and "method()", but
+    also "$self->method()" and "$self->{FIELDNAME}" and "$Foo <=> $Bar"
+    without resorting to escape sequences. If I want to refer to the
+    right-shift operator I can do something like "$x >> 3" or even "$y >>
+    5".
+
+    Now for the grand finale of "$self->method()->{FIELDNAME} = {FOO=>BAR}".
+    And I also want to make sure that newlines work like this
+    "$self->{FOOBAR} >> 3 and [$b => $a]->[$a <=> $b]"
+
+    Of course I should still be able to do all this *with* escape sequences
+    too: "$self->method()" and "$self->{FIELDNAME}" and "{FOO=>BAR}".
+
+    Dont forget "$self->method()->{FIELDNAME} = {FOO=>BAR}".
+
+    And make sure that 0 works too!
+
+    Now, if I use << or >> as my delimiters, then I have to use whitespace.
+    So things like "<$self-"method()>> and "<$self-"{FIELDNAME}>> wont end
+    up doing what you might expect since the first > will still terminate
+    the first < seen.
+
+    Lets make sure these work for empty ones too, like and ">>" (just to be
+    obnoxious)
+
+    The statement: "This is dog kind's *finest* hour!" is a parody of a
+    quotation from Winston Churchill.
+
+    The following tests are added to those:
+
+    Make sure that a few other odd *things* still work. This should be a
+    vertical bar: |. Here's a test of a few more special escapes that have
+    to be supported:
+
+    &  An ampersand.
+
+    '  An apostrophe.
+
+    <  A less-than sign.
+
+    >  A greater-than sign.
+
+    "  A double quotation mark.
+
+    /  A forward slash.
+
+    Try to get this bit of text over towards the edge so
+    |that all of this text inside S<> won't| be wrapped. Also test the
+    |same thing with non-breaking spaces.|
+
+    There is a soft hyphen in hyphen at hy-phen.
+
+    This is a test of an index entry.
+
+VERBATIM
+    Throw in a few verbatim paragraphs.
+
+        use Term::ANSIColor;
+        print color 'bold blue';
+        print "This text is bold blue.\n";
+        print color 'reset';
+        print "This text is normal.\n";
+        print colored ("Yellow on magenta.\n", 'yellow on_magenta');
+        print "This text is normal.\n";
+        print colored ['yellow on_magenta'], "Yellow on magenta.\n";
+
+        use Term::ANSIColor qw(uncolor);
+        print uncolor '01;31', "\n";
+
+    But this isn't verbatim (make sure it wraps properly), and the next
+    paragraph is again:
+
+        use Term::ANSIColor qw(:constants);
+        print BOLD, BLUE, "This text is in bold blue.\n", RESET;
+
+        use Term::ANSIColor qw(:constants); $Term::ANSIColor::AUTORESET = 1; print BOLD BLUE "This text is in bold blue.\n"; print "This text is normal.\n";
+
+    (Ugh, that's obnoxiously long.) Try different spacing:
+
+            Starting with a tab.
+    Not
+    starting
+    with
+    a
+    tab.  But this should still be verbatim.
+     As should this.
+
+    This isn't.
+
+     This is.  And this:    is an internal tab.  It should be:
+                        |--| <= lined up with that.
+
+    (Tricky, but tabs should be expanded before the translator starts in on
+    the text since otherwise text with mixed tabs and spaces will get messed
+    up.)
+
diff --git a/lib/Pod/t/parselink.t b/lib/Pod/t/parselink.t
new file mode 100644 (file)
index 0000000..68bc351
--- /dev/null
@@ -0,0 +1,133 @@
+#!/usr/bin/perl -w
+# $Id: parselink.t,v 1.1 2001/11/23 10:09:06 eagle Exp $
+#
+# parselink.t -- Tests for Pod::ParseLink.
+#
+# Copyright 2001 by Russ Allbery <rra@stanford.edu>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+# The format of each entry in this array is the L<> text followed by the
+# five-element parse returned by parselink.  When adding a new test, also
+# increment the test count in the BEGIN block below.  We don't use any of the
+# fancy test modules intentionally for backward compatibility to older
+# versions of Perl.
+@TESTS = (
+    [ 'foo',
+      undef, 'foo', 'foo', undef, 'pod' ],
+
+    [ 'foo|bar',
+      'foo', 'foo', 'bar', undef, 'pod' ],
+
+    [ 'foo/bar',
+      undef, '"bar" in foo', 'foo', 'bar', 'pod' ],
+
+    [ 'foo/"baz boo"',
+      undef, '"baz boo" in foo', 'foo', 'baz boo', 'pod' ],
+
+    [ '/bar',
+      undef, '"bar"', undef, 'bar', 'pod' ],
+
+    [ '/"baz boo"',
+      undef, '"baz boo"', undef, 'baz boo', 'pod' ],
+
+    [ '/baz boo',
+      undef, '"baz boo"', undef, 'baz boo', 'pod' ],
+
+    [ 'foo bar/baz boo',
+      undef, '"baz boo" in foo bar', 'foo bar', 'baz boo', 'pod' ],
+
+    [ 'foo bar  /  baz boo',
+      undef, '"baz boo" in foo bar', 'foo bar', 'baz boo', 'pod' ],
+
+    [ "foo\nbar\nbaz\n/\nboo",
+      undef, '"boo" in foo bar baz', 'foo bar baz', 'boo', 'pod' ],
+
+    [ 'anchor|name/section',
+      'anchor', 'anchor', 'name', 'section', 'pod' ],
+
+    [ '"boo var baz"',
+      undef, '"boo var baz"', undef, 'boo var baz', 'pod' ],
+
+    [ 'bar baz',
+      undef, '"bar baz"', undef, 'bar baz', 'pod' ],
+
+    [ '"boo bar baz / baz boo"',
+      undef, '"boo bar baz / baz boo"', undef, 'boo bar baz / baz boo',
+      'pod' ],
+
+    [ 'fooZ<>bar',
+      undef, 'fooZ<>bar', 'fooZ<>bar', undef, 'pod' ],
+
+    [ 'Testing I<italics>|foo/bar',
+      'Testing I<italics>', 'Testing I<italics>', 'foo', 'bar', 'pod' ],
+
+    [ 'foo/I<Italic> text',
+      undef, '"I<Italic> text" in foo', 'foo', 'I<Italic> text', 'pod' ],
+
+    [ 'fooE<verbar>barZ<>/Section C<with> I<B<other> markup',
+      undef, '"Section C<with> I<B<other> markup" in fooE<verbar>barZ<>',
+      'fooE<verbar>barZ<>', 'Section C<with> I<B<other> markup', 'pod' ],
+
+    [ 'Nested L<http://www.perl.org/>|fooE<sol>bar',
+      'Nested L<http://www.perl.org/>', 'Nested L<http://www.perl.org/>',
+      'fooE<sol>bar', undef, 'pod' ],
+
+    [ 'ls(1)',
+      undef, 'ls(1)', 'ls(1)', undef, 'man' ],
+
+    [ '  perlfunc(1)/open  ',
+      undef, '"open" in perlfunc(1)', 'perlfunc(1)', 'open', 'man' ],
+
+    [ 'some manual page|perl(1)',
+      'some manual page', 'some manual page', 'perl(1)', undef, 'man' ],
+
+    [ 'http://www.perl.org/',
+      undef, 'http://www.perl.org/', 'http://www.perl.org/', undef, 'url' ],
+
+    [ 'news:yld72axzc8.fsf@windlord.stanford.edu',
+      undef, 'news:yld72axzc8.fsf@windlord.stanford.edu',
+      'news:yld72axzc8.fsf@windlord.stanford.edu', undef, 'url' ]
+);
+
+BEGIN {
+    chdir 't' if -d 't';
+    unshift (@INC, '../blib/lib');
+    $| = 1;
+    print "1..25\n";
+}
+
+END {
+    print "not ok 1\n" unless $loaded;
+}
+
+use Pod::ParseLink;
+$loaded = 1;
+print "ok 1\n";
+
+# Used for reporting test failures.
+my @names = qw(text inferred name section type);
+
+my $n = 2;
+for (@TESTS) {
+    my @expected = @$_;
+    my $link = shift @expected;
+    my @results = parselink ($link);
+    my $okay = 1;
+    for (0..4) {
+        # Make sure to check undef explicitly; we don't want undef to match
+        # the empty string because they're semantically different.
+        unless ((!defined ($results[$_]) && !defined ($expected[$_]))
+                || (defined ($results[$_]) && defined ($expected[$_])
+                    && $results[$_] eq $expected[$_])) {
+            print "not ok $n\n" if $okay;
+            print "# Incorrect $names[$_]:\n";
+            print "#   expected: $expected[$_]\n";
+            print "#       seen: $results[$_]\n";
+            $okay = 0;
+        }
+    }
+    print "ok $n\n" if $okay;
+    $n++;
+}