Upgrade to podlators-2.1.0

p4raw-id: //depot/perl@33987

18 files changed, 182 insertions, 52 deletions

diff --git a/MANIFEST b/MANIFEST
index debd070ced..ef8dd37513 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -2591,6 +2591,7 @@ lib/Pod/t/htmlview.pod		pod2html render test input data
 lib/Pod/t/htmlview.t		pod2html render test
 lib/Pod/t/InputObjects.t	See if Pod::InputObjects works
 lib/Pod/t/man.t			podlators test
+lib/Pod/t/man-options.t		podlators test
 lib/Pod/t/parselink.t		podlators test
 lib/Pod/t/pod2html-lib.pl	pod2html testing library
 lib/Pod/t/pod2latex.t		See if Pod::LaTeX works
diff --git a/lib/Pod/Man.pm b/lib/Pod/Man.pm
index 451ecc80f0..00b1f1b5a0 100644
--- a/lib/Pod/Man.pm
+++ b/lib/Pod/Man.pm
@@ -1,7 +1,6 @@
 # Pod::Man -- Convert POD data to formatted *roff input.
-# $Id: Man.pm,v 2.16 2007-11-29 01:35:53 eagle Exp $
 #
-# Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
+# Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
 #     Russ Allbery <rra@stanford.edu>
 # Substantial contributions by Sean Burke <sburke@cpan.org>
 #
@@ -40,7 +39,7 @@ use POSIX qw(strftime);
 # 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.16';
+$VERSION = '2.17';
 
 # Set the debugging level.  If someone has inserted a debug function into this
 # class already, use that.  Otherwise, use any Pod::Simple debug function
@@ -348,23 +347,22 @@ sub format_text {
     my $convert = $$options{convert};
     my $literal = $$options{literal};
 
-    # Normally we do character translation, but we won't even do that in
-    # <Data> blocks.
-    if ($convert) {
-        if (ASCII) {
-            $text =~ s/(\\|[^\x00-\x7F])/$ESCAPES{ord ($1)} || "X"/eg;
-        } else {
-            $text =~ s/(\\)/$ESCAPES{ord ($1)} || "X"/eg;
-        }
-    }
-
     # Cleanup just tidies up a few things, telling *roff that the hyphens are
-    # hard and putting a bit of space between consecutive underscores.
+    # hard, putting a bit of space between consecutive underscores, and
+    # escaping backslashes.  Be careful not to mangle our character
+    # translations by doing this before processing character translation.
     if ($cleanup) {
+        $text =~ s/\\/\\e/g;
         $text =~ s/-/\\-/g;
         $text =~ s/_(?=_)/_\\|/g;
     }
 
+    # Normally we do character translation, but we won't even do that in
+    # <Data> blocks or if UTF-8 output is desired.
+    if ($convert && !$$self{utf8} && ASCII) {
+        $text =~ s/([^\x00-\x7F])/$ESCAPES{ord ($1)} || "X"/eg;
+    }
+
     # Ensure that *roff doesn't convert literal quotes to UTF-8 single quotes,
     # but don't mess up our accept escapes.
     if ($literal) {
@@ -641,10 +639,10 @@ sub switchquotes {
         # 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 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;
+        $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.  Bother with .ie only if the nroff
         # and troff output aren't the same.
@@ -1294,9 +1292,6 @@ sub parse_from_filehandle {
     "o\\*/" , "u\\*`", "u\\*'", "u\\*^",   "u\\*:", "y\\*'", "\\*(th", "y\\*:",
 ) if ASCII;
 
-# Make sure that at least this works even outside of ASCII.
-$ESCAPES{ord("\\")} = "\\e";
-
 ##############################################################################
 # Premable
 ##############################################################################
@@ -1312,7 +1307,7 @@ sub preamble_template {
 .if t .Sp
 .ne 5
 .PP
-\fB\\$1\fR
+\fB\&\\$1\fR
 .PP
 ..
 .de Sp \" Vertical space (when we can't use .PP)
@@ -1582,6 +1577,22 @@ that are reliably consistent are 1, 2, and 3.
 By default, section 1 will be used unless the file ends in .pm in which case
 section 3 will be selected.
 
+=item utf8
+
+By default, Pod::Man produces the most conservative possible *roff output
+to try to ensure that it will work with as many different *roff
+implementations as possible.  Many *roff implementations cannot handle
+non-ASCII characters, so this means all non-ASCII characters are converted
+either to a *roff escape sequence that tries to create a properly accented
+character (at least for troff output) or to C<X>.
+
+If this option is set, Pod::Man will instead output UTF-8.  If your *roff
+implementation can handle it, this is the best output format to use and
+avoids corruption of documents containing non-ASCII characters.  However,
+be warned that *roff source with literal UTF-8 characters is not supported
+by many implementations and may even result in segfaults and other bad
+behavior.
+
 =back
 
 The standard Pod::Simple method parse_file() takes one argument naming the
@@ -1617,15 +1628,6 @@ invalid.  A quote specification must be one, two, or four characters long.
 
 =head1 BUGS
 
-Eight-bit input data isn't handled at all well at present.  The correct
-approach would be to map EE<lt>E<gt> escapes to the appropriate UTF-8
-characters and then do a translation pass on the output according to the
-user-specified output character set.  Unfortunately, we can't send eight-bit
-data directly to the output unless the user says this is okay, since some
-vendor *roff implementations can't handle eight-bit data.  If the *roff
-implementation can, however, that's far superior to the current hacked
-characters that only work under troff.
-
 There is currently no way to turn off the guesswork that tries to format
 unmarked text appropriately, and sometimes it isn't wanted (particularly
 when using POD to document something other than Perl).  Most of the work
diff --git a/lib/Pod/ParseLink.pm b/lib/Pod/ParseLink.pm
index 7e4153da3d..d1ce44b34c 100644
--- a/lib/Pod/ParseLink.pm
+++ b/lib/Pod/ParseLink.pm
@@ -1,5 +1,4 @@
 # Pod::ParseLink -- Parse an L<> formatting code in POD text.
-# $Id: ParseLink.pm,v 1.6 2002/07/15 05:46:00 eagle Exp $
 #
 # Copyright 2001 by Russ Allbery <rra@stanford.edu>
 #
diff --git a/lib/Pod/Text.pm b/lib/Pod/Text.pm
index 03a62bff56..d52bb53849 100644
--- a/lib/Pod/Text.pm
+++ b/lib/Pod/Text.pm
@@ -1,5 +1,4 @@
 # Pod::Text -- Convert POD data to formatted ASCII text.
-# $Id: Text.pm,v 3.8 2006-09-16 20:55:41 eagle Exp $
 #
 # Copyright 1999, 2000, 2001, 2002, 2004, 2006
 #     by Russ Allbery <rra@stanford.edu>
diff --git a/lib/Pod/Text/Color.pm b/lib/Pod/Text/Color.pm
index ce95dbe56f..52b96c3637 100644
--- a/lib/Pod/Text/Color.pm
+++ b/lib/Pod/Text/Color.pm
@@ -1,5 +1,4 @@
 # Pod::Text::Color -- Convert POD data to formatted color ASCII text
-# $Id: Color.pm,v 2.3 2006-01-25 23:56:54 eagle Exp $
 #
 # Copyright 1999, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>
 #
diff --git a/lib/Pod/Text/Overstrike.pm b/lib/Pod/Text/Overstrike.pm
index 4ec2fc046a..e2f7ccd287 100644
--- a/lib/Pod/Text/Overstrike.pm
+++ b/lib/Pod/Text/Overstrike.pm
@@ -1,5 +1,4 @@
 # Pod::Text::Overstrike -- Convert POD data to formatted overstrike text
-# $Id: Overstrike.pm,v 2.0 2004/06/09 04:51:20 eagle Exp $
 #
 # Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000
 #   (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>)
diff --git a/lib/Pod/Text/Termcap.pm b/lib/Pod/Text/Termcap.pm
index 0b3caf3436..f60cc95733 100644
--- a/lib/Pod/Text/Termcap.pm
+++ b/lib/Pod/Text/Termcap.pm
@@ -1,5 +1,4 @@
 # Pod::Text::Termcap -- Convert POD data to ASCII text with format escapes.
-# $Id: Termcap.pm,v 2.3 2006-01-25 23:56:54 eagle Exp $
 #
 # Copyright 1999, 2001, 2002, 2004, 2006 by Russ Allbery <rra@stanford.edu>
 #
diff --git a/lib/Pod/t/basic.t b/lib/Pod/t/basic.t
index 6d4b842bb0..603d108574 100644
--- a/lib/Pod/t/basic.t
+++ b/lib/Pod/t/basic.t
@@ -1,5 +1,4 @@
 #!/usr/bin/perl -w
-# $Id: basic.t,v 1.11 2006-09-16 20:25:25 eagle Exp $
 #
 # basic.t -- Basic tests for podlators.
 #
diff --git a/lib/Pod/t/color.t b/lib/Pod/t/color.t
index 0575b509cb..2f1668f88e 100755
--- a/lib/Pod/t/color.t
+++ b/lib/Pod/t/color.t
@@ -1,5 +1,4 @@
 #!/usr/bin/perl -w
-# $Id: color.t,v 1.3 2006-01-28 22:31:50 eagle Exp $
 #
 # color.t -- Additional specialized tests for Pod::Text::Color.
 #
diff --git a/lib/Pod/t/filehandle.t b/lib/Pod/t/filehandle.t
index 1b9b8d95bc..a53884d50d 100644
--- a/lib/Pod/t/filehandle.t
+++ b/lib/Pod/t/filehandle.t
@@ -1,5 +1,4 @@
 #!/usr/bin/perl -w
-# $Id: filehandle.t,v 1.2 2006-09-16 20:25:25 eagle Exp $
 #
 # filehandle.t -- Test the parse_from_filehandle interface.
 #
diff --git a/lib/Pod/t/man-options.t b/lib/Pod/t/man-options.t
new file mode 100644
index 0000000000..928d7542fa
--- /dev/null
+++ b/lib/Pod/t/man-options.t
@@ -0,0 +1,103 @@
+#!/usr/bin/perl -w
+#
+# man-options.t -- Additional tests for Pod::Man options.
+#
+# Copyright 2002, 2004, 2006, 2008 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';
+    if ($ENV{PERL_CORE}) {
+        @INC = '../lib';
+    } else {
+        unshift (@INC, '../blib/lib');
+    }
+    unshift (@INC, '../blib/lib');
+    $| = 1;
+    print "1..2\n";
+}
+
+END {
+    print "not ok 1\n" unless $loaded;
+}
+
+use Pod::Man;
+
+$loaded = 1;
+print "ok 1\n";
+
+my $n = 2;
+while (<DATA>) {
+    my %options;
+    next until $_ eq "###\n";
+    while (<DATA>) {
+        last if $_ eq "###\n";
+        my ($option, $value) = split;
+        $options{$option} = $value;
+    }
+    open (TMP, '> tmp.pod') or die "Cannot create tmp.pod: $!\n";
+    while (<DATA>) {
+        last if $_ eq "###\n";
+        print TMP $_;
+    }
+    close TMP;
+    my $parser = Pod::Man->new (%options) or die "Cannot create parser\n";
+    open (OUT, '> out.tmp') or die "Cannot create out.tmp: $!\n";
+    $parser->parse_from_file ('tmp.pod', \*OUT);
+    close OUT;
+    open (TMP, 'out.tmp') or die "Cannot open out.tmp: $!\n";
+    while (<TMP>) { last if /^\.nh/ }
+    my $output;
+    {
+        local $/;
+        $output = <TMP>;
+    }
+    close TMP;
+    unlink ('tmp.pod', 'out.tmp');
+    my $expected = '';
+    while (<DATA>) {
+        last if $_ eq "###\n";
+        $expected .= $_;
+    }
+    if ($output eq $expected) {
+        print "ok $n\n";
+    } else {
+        print "not ok $n\n";
+        print "Expected\n========\n$expected\nOutput\n======\n$output\n";
+    }
+    $n++;
+}
+
+# Below the marker are bits of POD and corresponding expected text output.
+# This is used to test specific features or problems with Pod::Man.  The
+# input and output are separated by lines containing only ###.
+
+__DATA__
+
+###
+utf8 1
+###
+=head1 BEYONCÉ
+
+Beyoncé!  Beyoncé!  Beyoncé!!
+
+    Beyoncé!  Beyoncé!
+      Beyoncé!  Beyoncé!
+        Beyoncé!  Beyoncé!
+
+Older versions did not convert Beyoncé in verbatim.
+###
+.SH "BEYONCÉ"
+.IX Header "BEYONCÉ"
+Beyoncé!  Beyoncé!  Beyoncé!!
+.PP
+.Vb 3
+\&    Beyoncé!  Beyoncé!
+\&      Beyoncé!  Beyoncé!
+\&        Beyoncé!  Beyoncé!
+.Ve
+.PP
+Older versions did not convert Beyoncé in verbatim.
+###
diff --git a/lib/Pod/t/man.t b/lib/Pod/t/man.t
index 5d4d2315b6..6b162177a5 100644
--- a/lib/Pod/t/man.t
+++ b/lib/Pod/t/man.t
@@ -1,9 +1,9 @@
 #!/usr/bin/perl -w
-# $Id: man.t,v 1.12 2007-11-29 01:35:54 eagle Exp $
 #
 # man.t -- Additional specialized tests for Pod::Man.
 #
-# Copyright 2002, 2003, 2004, 2006, 2007 by Russ Allbery <rra@stanford.edu>
+# Copyright 2002, 2003, 2004, 2006, 2007, 2008
+#     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.
@@ -17,7 +17,7 @@ BEGIN {
     }
     unshift (@INC, '../blib/lib');
     $| = 1;
-    print "1..22\n";
+    print "1..24\n";
 }
 
 END {
@@ -29,6 +29,9 @@ use Pod::Man;
 $loaded = 1;
 print "ok 1\n";
 
+# Test whether we can use binmode to set encoding.
+my $have_encoding = (eval { require PerlIO::encoding; 1 } and not $@);
+
 my $parser = Pod::Man->new or die "Cannot create parser\n";
 my $n = 2;
 while (<DATA>) {
@@ -38,7 +41,7 @@ while (<DATA>) {
     # We have a test in ISO 8859-1 encoding.  Make sure that nothing strange
     # happens if Perl thinks the world is Unicode.  Wrap this in eval so that
     # older versions of Perl don't croak.
-    eval { binmode (\*TMP, ':encoding(iso-8859-1)') };
+    eval { binmode (\*TMP, ':encoding(iso-8859-1)') if $have_encoding };
 
     while (<DATA>) {
         last if $_ eq "###\n";
@@ -431,3 +434,20 @@ Don't escape `this' but do escape C<`this'> (and don't surround it in quotes).
 .IX Header "Quote escaping"
 Don't escape `this' but do escape \f(CW\`this\*(Aq\fR (and don't surround it in quotes).
 ###
+
+###
+=pod
+
+E<eth>
+###
+.PP
+\&\*(d-
+###
+
+###
+=head1 C<one> and C<two>
+###
+.ie n .SH """one"" and ""two"""
+.el .SH "\f(CWone\fP and \f(CWtwo\fP"
+.IX Header "one and two"
+###
diff --git a/lib/Pod/t/parselink.t b/lib/Pod/t/parselink.t
index 68bc3514bb..c5c2bb660b 100644
--- a/lib/Pod/t/parselink.t
+++ b/lib/Pod/t/parselink.t
@@ -1,5 +1,4 @@
 #!/usr/bin/perl -w
-# $Id: parselink.t,v 1.1 2001/11/23 10:09:06 eagle Exp $
 #
 # parselink.t -- Tests for Pod::ParseLink.
 #
diff --git a/lib/Pod/t/pod-parser.t b/lib/Pod/t/pod-parser.t
index 7b0f8c1bcf..21817fea55 100644
--- a/lib/Pod/t/pod-parser.t
+++ b/lib/Pod/t/pod-parser.t
@@ -1,5 +1,4 @@
 #!/usr/bin/perl -w
-# $Id: pod-parser.t,v 1.2 2006-09-16 21:09:57 eagle Exp $
 #
 # pod-parser.t -- Tests for backward compatibility with Pod::Parser.
 #
diff --git a/lib/Pod/t/termcap.t b/lib/Pod/t/termcap.t
index f93b82e17e..5ec98288f6 100755
--- a/lib/Pod/t/termcap.t
+++ b/lib/Pod/t/termcap.t
@@ -1,5 +1,4 @@
 #!/usr/bin/perl -w
-# $Id: termcap.t,v 1.4 2006-01-28 22:31:50 eagle Exp $
 #
 # termcap.t -- Additional specialized tests for Pod::Text::Termcap.
 #
diff --git a/lib/Pod/t/text-options.t b/lib/Pod/t/text-options.t
index 2a62a1bc15..5eb05d302f 100644
--- a/lib/Pod/t/text-options.t
+++ b/lib/Pod/t/text-options.t
@@ -1,5 +1,4 @@
 #!/usr/bin/perl -w
-# $Id: text-options.t,v 1.6 2006-01-28 22:31:50 eagle Exp $
 #
 # text-options.t -- Additional tests for Pod::Text options.
 #
diff --git a/lib/Pod/t/text.t b/lib/Pod/t/text.t
index b1995f29e4..f5654eaf25 100644
--- a/lib/Pod/t/text.t
+++ b/lib/Pod/t/text.t
@@ -1,5 +1,4 @@
 #!/usr/bin/perl -w
-# $Id: text.t,v 1.6 2007-09-12 00:20:08 eagle Exp $
 #
 # text.t -- Additional specialized tests for Pod::Text.
 #
diff --git a/pod/pod2man.PL b/pod/pod2man.PL
index 9a8414ad92..6c1570da02 100644
--- a/pod/pod2man.PL
+++ b/pod/pod2man.PL
@@ -36,9 +36,9 @@ $Config{startperl}
 print OUT <<'!NO!SUBS!';
 
 # pod2man -- Convert POD data to formatted *roff input.
-# $Id: pod2man.PL,v 1.16 2006-01-21 01:53:55 eagle Exp $
 #
-# Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008
+#     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.
@@ -66,7 +66,7 @@ Getopt::Long::config ('bundling_override');
 GetOptions (\%options, 'section|s=s', 'release|r:s', 'center|c=s',
             'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s',
             'fixedbolditalic=s', 'name|n=s', 'official|o', 'quotes|q=s',
-            'lax|l', 'help|h', 'verbose|v') or exit 1;
+            'lax|l', 'help|h', 'verbose|v', 'utf8|u') or exit 1;
 pod2usage (0) if $options{help};
 
 # Official sets --center, but don't override things explicitly set.
@@ -243,6 +243,22 @@ that are reliably consistent are 1, 2, and 3.
 By default, section 1 will be used unless the file ends in .pm in which case
 section 3 will be selected.
 
+=item B<-u>, B<--utf8>
+
+By default, B<pod2man> produces the most conservative possible *roff
+output to try to ensure that it will work with as many different *roff
+implementations as possible.  Many *roff implementations cannot handle
+non-ASCII characters, so this means all non-ASCII characters are converted
+either to a *roff escape sequence that tries to create a properly accented
+character (at least for troff output) or to C<X>.
+
+This option says to instead output literal UTF-8 characters.  If your
+*roff implementation can handle it, this is the best output format to use
+and avoids corruption of documents containing non-ASCII characters.
+However, be warned that *roff source with literal UTF-8 characters is not
+supported by many implementations and may even result in segfaults and
+other bad behavior.
+
 =item B<-v>, B<--verbose>
 
 Print out the name of each output file as it is being generated.
@@ -537,7 +553,8 @@ page, are taken from the B<pod2man> documentation by Tom.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2004, 2006, 2008 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.