This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to podlators-1.19.
authorAbhijit Menon-Sen <ams@wiw.org>
Wed, 2 Jan 2002 13:43:58 +0000 (13:43 +0000)
committerAbhijit Menon-Sen <ams@wiw.org>
Wed, 2 Jan 2002 13:43:58 +0000 (13:43 +0000)
p4raw-id: //depot/perl@14013

12 files changed:
MANIFEST
lib/Pod/Man.pm
lib/Pod/Text.pm
lib/Pod/Text/Termcap.pm
lib/Pod/t/basic.cap
lib/Pod/t/basic.clr
lib/Pod/t/basic.man
lib/Pod/t/basic.ovr
lib/Pod/t/basic.pod
lib/Pod/t/basic.txt
lib/Pod/t/man.t [new file with mode: 0644]
lib/Pod/t/text-errors.t [new file with mode: 0644]

index a04c168..a091af9 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -1208,9 +1208,11 @@ 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/man.t                podlators test
 lib/Pod/t/InputObjects.t       See if Pod::InputObjects works
 lib/Pod/t/latex.t              Test for Pod::LaTeX
 lib/Pod/t/parselink.t          podlators test
+lib/Pod/t/text-errors.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
index 7fc578b..0f0eaab 100644 (file)
@@ -1,7 +1,7 @@
 # Pod::Man -- Convert POD data to formatted *roff input.
-# $Id: Man.pm,v 1.30 2001/11/28 01:14:28 eagle Exp $
+# $Id: Man.pm,v 1.32 2002/01/02 09:02:24 eagle Exp $
 #
-# Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2002 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.
@@ -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.30;
+$VERSION = 1.32;
 
 
 ##############################################################################
@@ -70,7 +70,6 @@ $PREAMBLE = <<'----END OF PREAMBLE----';
 ..
 .de Ve \" End verbatim text
 .ft R
-
 .fi
 ..
 .\" Set up some character translations and predefined strings.  \*(-- will
@@ -464,13 +463,13 @@ $_
 .\\"
 .IX Title "$name $section"
 .TH $name $section "$$self{date}" "$$self{release}" "$$self{center}"
-.UC
 ----END OF HEADER----
 
     # Initialize a few per-file variables.
     $$self{INDENT}    = 0;      # Current indentation level.
     $$self{INDENTS}   = [];     # Stack of indentations.
     $$self{INDEX}     = [];     # Index keys waiting to be printed.
+    $$self{IN_NAME}   = 0;      # Whether processing the NAME section.
     $$self{ITEMS}     = 0;      # The number of consecutive =items.
     $$self{SHIFTWAIT} = 0;      # Whether there is a shift waiting.
     $$self{SHIFTS}    = [];     # Stack of .RS shifts.
@@ -520,7 +519,7 @@ sub verbatim {
     s/^(\s*\S)/'\&' . $1/gme;
     $self->makespace;
     $self->output (".Vb $lines\n$_.Ve\n");
-    $$self{NEEDSPACE} = 0;
+    $$self{NEEDSPACE} = 1;
 }
 
 # Called for a regular text block.  Gets the paragraph, the line number, and a
@@ -639,9 +638,12 @@ sub sequence {
 
 # First level heading.  We can't output .IX in the NAME section due to a bug
 # in some versions of catman, so don't output a .IX for that section.  .SH
-# already uses small caps, so remove \s1 and \s-1.
+# already uses small caps, so remove \s1 and \s-1.  Maintain IN_NAME as
+# appropriate, but don't leave it set while calling parse() so as to not
+# override guesswork on section headings after NAME.
 sub cmd_head1 {
     my $self = shift;
+    $$self{IN_NAME} = 0;
     local $_ = $self->parse (@_);
     s/\s+$//;
     s/\\s-?\d//g;
@@ -653,6 +655,7 @@ sub cmd_head1 {
     $self->output ($self->switchquotes ('.SH', $self->mapfonts ($_)));
     $self->outindex (($_ eq 'NAME') ? () : ('Header', $_));
     $$self{NEEDSPACE} = 0;
+    $$self{IN_NAME} = ($_ eq 'NAME');
 }
 
 # Second level heading.
@@ -877,13 +880,24 @@ sub parse {
 # (not call guesswork on it), and a flag saying whether or not to clean some
 # things up for *roff, and returns the concatenation of all of the text
 # strings in that parse tree.  If the literal flag isn't true, guesswork()
-# will be called on all plain scalars in the parse tree.  Otherwise, just
-# escape backslashes in the normal case.  If collapse is being called on a C<>
-# code, $cleanup should be set to true and some additional cleanup will be
-# done.  Assumes that everything in the parse tree is either a scalar or a
-# reference to a scalar.
+# will be called on all plain scalars in the parse tree.  Otherwise, if
+# collapse is being called on a C<> code, $cleanup should be set to true and
+# some additional cleanup will be done.  Assumes that everything in the parse
+# tree is either a scalar or a reference to a scalar.
 sub collapse {
     my ($self, $ptree, $literal, $cleanup) = @_;
+
+    # If we're processing the NAME section, don't do normal guesswork.  This
+    # is because NAME lines are often extracted by utilities like catman that
+    # require plain text and don't understand *roff markup.  We still need to
+    # escape backslashes and hyphens for *roff (and catman expects \- instead
+    # of -).
+    if ($$self{IN_NAME}) {
+        $literal = 1;
+        $cleanup = 1;
+    }
+
+    # Do the collapse of the parse tree as described above.
     return join ('', map {
         if (ref $_) {
             join ('', @$_);
@@ -1369,7 +1383,7 @@ B<pod2man> by Tom Christiansen <tchrist@mox.perl.com>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2002 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.
index 96cfcfb..12a450b 100644 (file)
@@ -1,5 +1,5 @@
 # Pod::Text -- Convert POD data to formatted ASCII text.
-# $Id: Text.pm,v 2.16 2001/11/28 01:15:50 eagle Exp $
+# $Id: Text.pm,v 2.18 2002/01/01 02:40:51 eagle Exp $
 #
 # Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>
 #
@@ -43,7 +43,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.16;
+$VERSION = 2.18;
 
 
 ##############################################################################
@@ -227,7 +227,7 @@ sub command {
         ($file, $line) = $paragraph->file_line;
         $text =~ s/\n+\z//;
         $text = " $text" if ($text =~ /^\S/);
-        warn qq($file:$line: Unknown command paragraph "=$command$text"\n);
+        warn qq($file:$line: Unknown command paragraph: =$command$text\n);
         return;
     }
 }
@@ -291,7 +291,6 @@ sub interior_sequence {
             return chr;
         } else {
             return $ESCAPES{$_} if defined $ESCAPES{$_};
-            my $seq = shift;
             my ($file, $line) = $seq->file_line;
             warn "$file:$line: Unknown escape: E<$_>\n";
             return "E<$_>";
@@ -316,9 +315,8 @@ sub interior_sequence {
     elsif ($command eq 'I') { return $self->seq_i ($_) }
     elsif ($command eq 'L') { return $self->seq_l ($_, $seq) }
     else {
-        my $seq = shift;
         my ($file, $line) = $seq->file_line;
-        warn "$file:$line: Unknown formatting code $command<$_>\n";
+        warn "$file:$line: Unknown formatting code: $command<$_>\n";
     }
 }
 
@@ -771,7 +769,7 @@ and the input file it was given could not be opened.
 (F) The quote specification given (the quotes option to the constructor) was
 invalid.  A quote specification must be one, two, or four characters long.
 
-=item %s:%d: Unknown command paragraph "%s".
+=item %s:%d: Unknown command paragraph: %s
 
 (W) The POD source contained a non-standard command paragraph (something of
 the form C<=command args>) that Pod::Man didn't know about.  It was ignored.
index 38b2658..97523f9 100644 (file)
@@ -1,7 +1,7 @@
 # Pod::Text::Termcap -- Convert POD data to ASCII text with format escapes.
-# $Id: Termcap.pm,v 1.6 2001/11/28 05:44:09 eagle Exp $
+# $Id: Termcap.pm,v 1.9 2002/01/02 07:59:09 eagle Exp $
 #
-# Copyright 1999, 2001 by Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2001, 2002 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.
@@ -30,7 +30,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.06;
+$VERSION = 1.09;
 
 
 ##############################################################################
@@ -51,10 +51,10 @@ sub initialize {
     # available (such as on VMS).
     eval { $termios = POSIX::Termios->new };
     if ($@) {
-        $ospeed = '9600';
+        $ospeed = 9600;
     } else {
         $termios->getattr;
-        $ospeed = $termios->getospeed;
+        $ospeed = $termios->getospeed || 9600;
     }
 
     # Fall back on the ANSI escape sequences if Term::Cap doesn't work.
@@ -166,7 +166,7 @@ Russ Allbery <rra@stanford.edu>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2001 by Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2001, 2002 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.
index 21f38ba..d8f1ae2 100644 (file)
     the text since otherwise text with mixed tabs and spaces will get messed
     up.)
 
+        And now we test verbatim paragraphs right before a heading.  Older
+        versions of Pod::Man generated two spaces between paragraphs like this
+        and the heading.  (In order to properly test this, one may have to
+        visually inspect the nroff output when run on the generated *roff
+        text, unfortunately.)
+
+\e[1mCONCLUSION\e[m
+    That's all, folks!
+
index b9d1cad..acda09c 100644 (file)
     the text since otherwise text with mixed tabs and spaces will get messed
     up.)
 
+        And now we test verbatim paragraphs right before a heading.  Older
+        versions of Pod::Man generated two spaces between paragraphs like this
+        and the heading.  (In order to properly test this, one may have to
+        visually inspect the nroff output when run on the generated *roff
+        text, unfortunately.)
+
+\e[1mCONCLUSION\e[0m
+    That's all, folks!
+
index 68434f3..c5d8c14 100644 (file)
@@ -1,6 +1,5 @@
-.UC
 .SH "NAME"
-basic.pod \- Test of various basic \s-1POD\s0 features in translators.
+basic.pod \- Test of various basic POD features in translators.
 .SH "HEADINGS"
 .IX Header "HEADINGS"
 Try a few different levels of headings, with embedded formatting codes and
@@ -299,10 +298,12 @@ Throw in a few verbatim paragraphs.
 \&    print "This text is normal.\en";
 \&    print colored ['yellow on_magenta'], "Yellow on magenta.\en";
 .Ve
+.PP
 .Vb 2
 \&    use Term::ANSIColor qw(uncolor);
 \&    print uncolor '01;31', "\en";
 .Ve
+.PP
 But this isn't verbatim (make sure it wraps properly), and the next
 paragraph is again:
 .PP
@@ -310,9 +311,11 @@ paragraph is again:
 \&    use Term::ANSIColor qw(:constants);
 \&    print BOLD, BLUE, "This text is in bold blue.\en", RESET;
 .Ve
+.PP
 .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
+.PP
 (Ugh, that's obnoxiously long.)  Try different spacing:
 .PP
 .Vb 7
@@ -324,12 +327,25 @@ paragraph is again:
 \&tab.  But this should still be verbatim.
 \& As should this.
 .Ve
+.PP
 This isn't.
 .PP
 .Vb 2
 \& This is.  And this:    is an internal tab.  It should be:
 \&                    |--| <= lined up with that.
 .Ve
+.PP
 (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.)
+.PP
+.Vb 5
+\&    And now we test verbatim paragraphs right before a heading.  Older
+\&    versions of Pod::Man generated two spaces between paragraphs like this
+\&    and the heading.  (In order to properly test this, one may have to
+\&    visually inspect the nroff output when run on the generated *roff
+\&    text, unfortunately.)
+.Ve
+.SH "CONCLUSION"
+.IX Header "CONCLUSION"
+That's all, folks!
index b20ca08..d762930 100644 (file)
@@ -282,3 +282,12 @@ V\bVE\bER\bRB\bBA\bAT\bTI\bIM\bM
     the text since otherwise text with mixed tabs and spaces will get messed
     up.)
 
+        And now we test verbatim paragraphs right before a heading.  Older
+        versions of Pod::Man generated two spaces between paragraphs like this
+        and the heading.  (In order to properly test this, one may have to
+        visually inspect the nroff output when run on the generated *roff
+        text, unfortunately.)
+
+C\bCO\bON\bNC\bCL\bLU\bUS\bSI\bIO\bON\bN
+    That's all, folks!
+
index de76060..03e2a22 100644 (file)
@@ -404,4 +404,14 @@ This isn't.
 the text since otherwise text with mixed tabs and spaces will get messed
 up.)
 
+    And now we test verbatim paragraphs right before a heading.  Older
+    versions of Pod::Man generated two spaces between paragraphs like this
+    and the heading.  (In order to properly test this, one may have to
+    visually inspect the nroff output when run on the generated *roff
+    text, unfortunately.)
+
+=head1 CONCLUSION
+
+That's all, folks!
+
 =cut
index 8052215..f2fae9d 100644 (file)
@@ -282,3 +282,12 @@ VERBATIM
     the text since otherwise text with mixed tabs and spaces will get messed
     up.)
 
+        And now we test verbatim paragraphs right before a heading.  Older
+        versions of Pod::Man generated two spaces between paragraphs like this
+        and the heading.  (In order to properly test this, one may have to
+        visually inspect the nroff output when run on the generated *roff
+        text, unfortunately.)
+
+CONCLUSION
+    That's all, folks!
+
diff --git a/lib/Pod/t/man.t b/lib/Pod/t/man.t
new file mode 100644 (file)
index 0000000..5171cc6
--- /dev/null
@@ -0,0 +1,86 @@
+#!/usr/bin/perl -w
+# $Id: man.t,v 1.1 2002/01/02 09:03:28 eagle Exp $
+#
+# man.t -- Additional specialized tests for Pod::Man.
+#
+# Copyright 2002 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';
+    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>) {
+    next until $_ eq "###\n";
+    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 or die "Cannot create parser\n";
+    $parser->parse_from_file ('tmp.pod', 'out.tmp');
+    open (TMP, 'out.tmp') or die "Cannot open out.tmp: $!\n";
+    while (<TMP>) { last if /^\.TH/ }
+    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 nroff output.
+# This is used to test specific features or problems with Pod::Man.  The input
+# and output are separated by lines containing only ###.
+
+__DATA__
+
+###
+=head1 NAME
+
+gcc - GNU project C and C++ compiler
+
+=head1 C++ NOTES
+
+Other mentions of C++.
+###
+.SH "NAME"
+gcc \- GNU project C and C++ compiler
+.SH "\*(C+ NOTES"
+.IX Header " NOTES"
+Other mentions of \*(C+.
+###
diff --git a/lib/Pod/t/text-errors.t b/lib/Pod/t/text-errors.t
new file mode 100644 (file)
index 0000000..48d6c39
--- /dev/null
@@ -0,0 +1,81 @@
+#!/usr/bin/perl -w
+# $Id: text-errors.t,v 1.1 2002/01/01 02:41:53 eagle Exp $
+#
+# texterrs.t -- Error tests for Pod::Text.
+#
+# 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';
+    if ($ENV{PERL_CORE}) {
+        @INC = '../lib';
+    } else {
+        unshift (@INC, '../blib/lib');
+    }
+    unshift (@INC, '../blib/lib');
+    $| = 1;
+    print "1..5\n";
+}
+
+END {
+    print "not ok 1\n" unless $loaded;
+}
+
+use Pod::Text;
+
+$loaded = 1;
+print "ok 1\n";
+
+# Hard-code a few values to try to get reproducible results.
+$ENV{COLUMNS} = 80;
+$ENV{TERM} = 'xterm';
+$ENV{TERMCAP} = 'xterm:co=80:do=^J:md=\E[1m:us=\E[4m:me=\E[m';
+
+# Set default options to match those of pod2man and pod2text.
+my %options = (sentence => 0);
+
+# Capture warnings for inspection.
+my $warnings = '';
+$SIG{__WARN__} = sub { $warnings .= $_[0] };
+
+# Run a single test, given some POD to parse and the warning messages that are
+# expected.  Any formatted output is ignored; only warning messages are
+# checked.  Writes the POD to a temporary file since that's the easiest way to
+# interact with Pod::Parser.
+sub test_error {
+    my ($pod, $expected) = @_;
+    open (TMP, '> tmp.pod') or die "Cannot create tmp.pod: $!\n";
+    print TMP $pod;
+    close TMP;
+    my $parser = Pod::Text->new (%options);
+    return unless $parser;
+    $warnings = '';
+    $parser->parse_from_file ('tmp.pod', 'out.tmp');
+    unlink ('tmp.pod', 'out.tmp');
+    if ($warnings eq $expected) {
+        return 1;
+    } else {
+        print "  # '$warnings'\n  # '$expected'\n";
+        return 0;
+    }
+}
+
+# The actual tests.
+my @tests = (
+    [ "=head1 a E<0x2028> b\n"
+        => "tmp.pod:1: Unknown escape: E<0x2028>\n" ],
+    [ "=head1 a Y<0x2028> b\n"
+        => "tmp.pod:1: Unknown formatting code: Y<0x2028>\n" ],
+    [ "=head1 TEST\n\n=command args\n"
+        => "tmp.pod:3: Unknown command paragraph: =command args\n" ],
+    [ "=head1 TEST\n\n  Foo bar\n\n=back\n"
+        => "tmp.pod:5: Unmatched =back\n" ]
+);
+my $n = 2;
+for (@tests) {
+    print (test_error ($$_[0], $$_[1]) ? "ok $n\n" : "not ok $n\n");
+    $n++;
+}