Upgrade to podlators-1.03 (Pod::Man 1.07 and Pod::Text 2.05),

by Russ Allbery.

p4raw-id: //depot/perl@7047

4 files changed, 162 insertions, 43 deletions

diff --git a/lib/Pod/Man.pm b/lib/Pod/Man.pm
index 7c716817f8..8484cd559f 100644
--- a/lib/Pod/Man.pm
+++ b/lib/Pod/Man.pm
@@ -1,5 +1,5 @@
 # Pod::Man -- Convert POD data to formatted *roff input.
-# $Id: Man.pm,v 1.4 2000/04/26 04:03:41 eagle Exp $
+# $Id: Man.pm,v 1.7 2000/09/03 09:22:57 eagle Exp $
 #
 # Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu>
 #
@@ -38,7 +38,7 @@ use vars qw(@ISA %ESCAPES $PREAMBLE $VERSION);
 # 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.07;
 
 
 ############################################################################
@@ -47,8 +47,10 @@ $VERSION = 1.04;
 
 # The following is the static preamble which starts all *roff output we
 # generate.  It's completely static except for the font to use as a
-# fixed-width font, which is designed by @CFONT@.  $PREAMBLE should
-# therefore be run through s/\@CFONT\@/<font>/g before output.
+# fixed-width font, which is designed by @CFONT@, and the left and right
+# quotes to use for C<> text, designated by @LQOUTE@ and @RQUOTE@.
+# $PREAMBLE should therefore be run through s/\@CFONT\@/<font>/g before
+# output.
 $PREAMBLE = <<'----END OF PREAMBLE----';
 .de Sh \" Subsection heading
 .br
@@ -93,8 +95,8 @@ $PREAMBLE = <<'----END OF PREAMBLE----';
 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
 .    ds L" ""
 .    ds R" ""
-.    ds C` `
-.    ds C' '
+.    ds C` @LQUOTE@
+.    ds C' @RQUOTE@
 'br\}
 .el\{\
 .    ds -- \|\(em\|
@@ -194,7 +196,7 @@ $PREAMBLE = <<'----END OF PREAMBLE----';
     'lt'        =>    '<',      # left chevron, less-than
     'gt'        =>    '>',      # right chevron, greater-than
     'quot'      =>    '"',      # double quote
-    'sol'       =>    '/',      # solidus
+    'sol'       =>    '/',      # solidus (forward slash)
     'verbar'    =>    '|',      # vertical bar
 
     'Aacute'    =>    "A\\*'",  # capital A, acute accent
@@ -325,7 +327,8 @@ sub initialize {
     for (qw/fixed fixedbold fixeditalic fixedbolditalic/) {
         if (defined $$self{$_}) {
             if (length ($$self{$_}) < 1 || length ($$self{$_}) > 2) {
-                croak "roff font should be 1 or 2 chars, not `$$self{$_}'";
+                croak qq(roff font should be 1 or 2 chars,)
+                    . qq( not "$$self{$_}");
             }
         } else {
             $$self{$_} = '';
@@ -370,6 +373,26 @@ sub initialize {
         $$self{$_} =~ s/\"/\"\"/g if $$self{$_};
     }
 
+    # Figure out what quotes we'll be using for C<> text.
+    $$self{quotes} ||= "'";
+    if ($$self{quotes} eq 'none') {
+        $$self{LQUOTE} = $$self{RQUOTE} = '';
+    } elsif (length ($$self{quotes}) == 1) {
+        $$self{LQUOTE} = $$self{RQUOTE} = $$self{quotes};
+    } elsif ($$self{quotes} =~ /^(.)(.)$/
+             || $$self{quotes} =~ /^(..)(..)$/) {
+        $$self{LQUOTE} = $1;
+        $$self{RQUOTE} = $2;
+    } else {
+        croak qq(Invalid quote specification "$$self{quotes}");
+    }
+
+    # Double the first quote; note that this should not be s///g as two
+    # double quotes is represented in *roff as three double quotes, not
+    # four.  Weird, I know.
+    $$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.
@@ -377,9 +400,7 @@ sub initialize {
     $self->SUPER::initialize;
 }
 
-# For each document we process, output the preamble first.  Note that the
-# fixed width font is a global default; once we interpolate it into the
-# PREAMBLE, it ain't ever changing.  Maybe fix this later.
+# For each document we process, output the preamble first.
 sub begin_pod {
     my $self = shift;
 
@@ -425,15 +446,18 @@ sub begin_pod {
     }
 
     # Now, print out the preamble and the title.
-    $PREAMBLE =~ s/\@CFONT\@/$$self{fixed}/;
-    chomp $PREAMBLE;
+    local $_ = $PREAMBLE;
+    s/\@CFONT\@/$$self{fixed}/;
+    s/\@LQUOTE\@/$$self{LQUOTE}/;
+    s/\@RQUOTE\@/$$self{RQUOTE}/;
+    chomp $_;
     print { $self->output_handle } <<"----END OF HEADER----";
 .\\" Automatically generated by Pod::Man version $VERSION
 .\\" @{[ scalar localtime ]}
 .\\"
 .\\" Standard preamble:
 .\\" ======================================================================
-$PREAMBLE
+$_
 .\\" ======================================================================
 .\\"
 .IX Title "$name $section"
@@ -460,19 +484,17 @@ sub command {
     my $self = shift;
     my $command = shift;
     return if $command eq 'pod';
-    return if ($$self{EXCLUDE} && $command ne 'end');
-    $command = 'cmd_' . $command;
-    unless ($self -> can ($command)) {
-        my $com = substr $command => 4;
-        my ($file, $line) = $_ [2] -> file_line;
-       (my $text = $_ [0]) =~ s/\n+\z//g;
-        $text = " $text" if $text =~ /^\S/;
-        warn qq {$file: Unknown command paragraph "=$com${text}"},
-             qq { on line $line.\n};
-        return;
-    }
-    else {
+   return if ($$self{EXCLUDE} && $command ne 'end');
+    if ($self->can ('cmd_' . $command)) {
+        $command = 'cmd_' . $command;
         $self->$command (@_);
+     } else {
+        my ($text, $line, $paragraph) = @_;
+        my ($file, $line) = $paragraph->file_line;
+        $text =~ s/\n+\z//;
+        $text = " $text" if ($text =~ /^\S/);
+        warn qq($file:$line: Unknown command paragraph "=$command$text"\n);
+        return;
     }
 }
 
@@ -1114,6 +1136,18 @@ Pod::Man doesn't assume you have this, and defaults to CB.  Some systems
 (such as Solaris) have this font available as CX.  Only matters for troff(1)
 output.
 
+=item quotes
+
+Sets the quote marks used to surround CE<lt>> text.  If the value is a
+single character, it is used as both the left and right quote; if it is two
+characters, the first character is used as the left quote and the second as
+the right quoted; and if it is four characters, the first two are used as
+the left quote and the second two as the right quote.
+
+This may also be set to the special value C<none>, in which case no quote
+marks are added around CE<lt>> text (but the font is still changed for troff
+output).
+
 =item release
 
 Set the centered footer.  By default, this is the version of Perl you run
@@ -1150,7 +1184,7 @@ details.
 
 =over 4
 
-=item roff font should be 1 or 2 chars, not `%s'
+=item roff font should be 1 or 2 chars, not "%s"
 
 (F) You specified a *roff font (using C<fixed>, C<fixedbold>, etc.) that
 wasn't either one or two characters.  Pod::Man doesn't support *roff fonts
@@ -1163,6 +1197,16 @@ versions of nroff(1) and troff(1) don't either).
 unable to parse.  You should never see this error message; it probably
 indicates a bug in Pod::Man.
 
+=item Invalid quote specification "%s"
+
+(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".
+
+(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.
+
 =item Unknown escape EE<lt>%sE<gt>
 
 (W) The POD source contained an C<EE<lt>E<gt>> escape that Pod::Man didn't
diff --git a/lib/Pod/Text.pm b/lib/Pod/Text.pm
index 47dcee584f..29d0dba20a 100644
--- a/lib/Pod/Text.pm
+++ b/lib/Pod/Text.pm
@@ -1,5 +1,5 @@
 # Pod::Text -- Convert POD data to formatted ASCII text.
-# $Id: Text.pm,v 2.4 2000/03/17 00:17:08 eagle Exp $
+# $Id: Text.pm,v 2.5 2000/09/03 09:23:29 eagle Exp $
 #
 # Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu>
 #
@@ -37,7 +37,7 @@ use vars qw(@ISA @EXPORT %ESCAPES $VERSION);
 # 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.04;
+$VERSION = 2.05;
 
 
 ############################################################################
@@ -53,7 +53,7 @@ $VERSION = 2.04;
     'lt'        =>    '<',      # left chevron, less-than
     'gt'        =>    '>',      # right chevron, greater-than
     'quot'      =>    '"',      # double quote
-    'sol'       =>    '/',      # solidus
+    'sol'       =>    '/',      # solidus (forward slash)
     'verbar'    =>    '|',      # vertical bar
                                  
     "Aacute"    =>    "\xC1",   # capital A, acute accent
@@ -172,6 +172,20 @@ sub initialize {
     $$self{sentence} = 0  unless defined $$self{sentence};
     $$self{width}    = 76 unless defined $$self{width};
 
+    # Figure out what quotes we'll be using for C<> text.
+    $$self{quotes} ||= "'";
+    if ($$self{quotes} eq 'none') {
+        $$self{LQUOTE} = $$self{RQUOTE} = '';
+    } elsif (length ($$self{quotes}) == 1) {
+        $$self{LQUOTE} = $$self{RQUOTE} = $$self{quotes};
+    } elsif ($$self{quotes} =~ /^(.)(.)$/
+             || $$self{quotes} =~ /^(..)(..)$/) {
+        $$self{LQUOTE} = $1;
+        $$self{RQUOTE} = $2;
+    } else {
+        croak qq(Invalid quote specification "$$self{quotes}");
+    }
+
     $$self{INDENTS}  = [];              # Stack of indentations.
     $$self{MARGIN}   = $$self{indent};  # Current left margin in spaces.
 
@@ -193,8 +207,17 @@ sub command {
     return if $command eq 'pod';
     return if ($$self{EXCLUDE} && $command ne 'end');
     $self->item ("\n") if defined $$self{ITEM};
-    $command = 'cmd_' . $command;
-    $self->$command (@_);
+    if ($self->can ('cmd_' . $command)) {
+        $command = 'cmd_' . $command;
+        $self->$command (@_);
+    } else {
+        my ($text, $line, $paragraph) = @_;
+        my ($file, $line) = $paragraph->file_line;
+        $text =~ s/\n+\z//;
+        $text = " $text" if ($text =~ /^\S/);
+        warn qq($file:$line: Unknown command paragraph "=$command$text"\n);
+        return;
+    }
 }
 
 # Called for a verbatim paragraph.  Gets the paragraph, the line number, and
@@ -419,9 +442,11 @@ sub cmd_for {
 # The simple formatting ones.  These are here mostly so that subclasses can
 # override them and do more complicated things.
 sub seq_b { return $_[0]{alt} ? "``$_[1]''" : $_[1] }
-sub seq_c { return $_[0]{alt} ? "``$_[1]''" : "`$_[1]'" }
 sub seq_f { return $_[0]{alt} ? "\"$_[1]\"" : $_[1] }
 sub seq_i { return '*' . $_[1] . '*' }
+sub seq_c {
+    return $_[0]{alt} ? "``$_[1]''" : "$_[0]{LQUOTE}$_[1]$_[0]{RQUOTE}"
+}
 
 # The complicated one.  Handle links.  Since this is plain text, we can't
 # actually make any real links, so this is all to figure out what text we
@@ -592,13 +617,14 @@ sub pod2text {
     # means we need to turn the first argument into a file handle.  Magic
     # open will handle the <&STDIN case automagically.
     if (defined $_[1]) {
+        my @fhs = @_;
         local *IN;
-        unless (open (IN, $_[0])) {
-            croak ("Can't open $_[0] for reading: $!\n");
+        unless (open (IN, $fhs[0])) {
+            croak ("Can't open $fhs[0] for reading: $!\n");
             return;
         }
-        $_[0] = \*IN;
-        return $parser->parse_from_filehandle (@_);
+        $fhs[0] = \*IN;
+        return $parser->parse_from_filehandle (@fhs);
     } else {
         return $parser->parse_from_file (@_);
     }
@@ -664,6 +690,17 @@ it's the expected formatting for manual pages; if you're formatting
 arbitrary text documents, setting this to true may result in more pleasing
 output.
 
+=item quotes
+
+Sets the quote marks used to surround CE<lt>> text.  If the value is a
+single character, it is used as both the left and right quote; if it is two
+characters, the first character is used as the left quote and the second as
+the right quoted; and if it is four characters, the first two are used as
+the left quote and the second two as the right quote.
+
+This may also be set to the special value C<none>, in which case no quote
+marks are added around CE<lt>> text.
+
 =item sentence
 
 If set to a true value, Pod::Text will assume that each sentence ends in two
@@ -699,6 +736,16 @@ indicates a bug in Pod::Text; you should never see it.
 (F) Pod::Text was invoked via the compatibility mode pod2text() interface
 and the input file it was given could not be opened.
 
+=item Invalid quote specification "%s"
+
+(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".
+
+(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.
+
 =item Unknown escape: %s
 
 (W) The POD source contained an C<EE<lt>E<gt>> escape that Pod::Text didn't
diff --git a/pod/pod2man.PL b/pod/pod2man.PL
index bf35cff4cc..4c5831b90b 100644
--- a/pod/pod2man.PL
+++ b/pod/pod2man.PL
@@ -36,7 +36,7 @@ $Config{startperl}
 print OUT <<'!NO!SUBS!';
 
 # pod2man -- Convert POD data to formatted *roff input.
-# $Id: pod2man.PL,v 1.2 2000/03/16 21:08:23 eagle Exp $
+# $Id: pod2man.PL,v 1.3 2000/09/03 09:20:52 eagle Exp $
 #
 # Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu>
 #
@@ -63,7 +63,8 @@ my %options;
 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', 'official|o', 'lax|l', 'help|h') or exit 1;
+            'fixedbolditalic=s', 'official|o', 'quotes|q=s', 'lax|l',
+            'help|h') or exit 1;
 pod2usage (0) if $options{help};
 
 # Official sets --center, but don't override things explicitly set.
@@ -86,8 +87,8 @@ pod2man - Convert POD data to formatted *roff input
 pod2man [B<--section>=I<manext>] [B<--release>=I<version>]
 [B<--center>=I<string>] [B<--date>=I<string>] [B<--fixed>=I<font>]
 [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
-[B<--fixedbolditalic>=I<font>] [B<--official>] [B<--lax>] [I<input>
-[I<output>]]
+[B<--fixedbolditalic>=I<font>] [B<--official>] [B<--lax>]
+[B<--quotes>=I<quotes>] [I<input> [I<output>]]
 
 pod2man B<--help>
 
@@ -173,6 +174,19 @@ POD checking functionality is not yet implemented in Pod::Man.
 Set the default header to indicate that this page is part of the standard
 Perl release, if B<--center> is not also given.
 
+=item B<-q> I<quotes>, B<--quotes>=I<quotes>
+
+Sets the quote marks used to surround CE<lt>> text to I<quotes>.  If
+I<quotes> is a single character, it is used as both the left and right
+quote; if I<quotes> is two characters, the first character is used as the
+left quote and the second as the right quoted; and if I<quotes> is four
+characters, the first two are used as the left quote and the second two as
+the right quote.
+
+I<quotes> may also be set to the special value C<none>, in which case no
+quote marks are added around CE<lt>> text (but the font is still changed for
+troff output).
+
 =item B<-r>, B<--release>
 
 Set the centered footer.  By default, this is the version of Perl you run
diff --git a/pod/pod2text.PL b/pod/pod2text.PL
index c5460aef30..b4965cb00f 100644
--- a/pod/pod2text.PL
+++ b/pod/pod2text.PL
@@ -75,7 +75,8 @@ my %options;
 $options{sentence} = 0;
 Getopt::Long::config ('bundling');
 GetOptions (\%options, 'alt|a', 'color|c', 'help|h', 'indent|i=i',
-            'loose|l', 'sentence|s', 'termcap|t', 'width|w=i') or exit 1;
+            'loose|l', 'quotes|q=s', 'sentence|s', 'termcap|t',
+            'width|w=i') or exit 1;
 pod2usage (1) if $options{help};
 
 # Figure out what formatter we're going to use.  -c overrides -t.
@@ -103,7 +104,8 @@ pod2text - Convert POD data to formatted ASCII text
 
 =head1 SYNOPSIS
 
-pod2text [B<-aclst>] [B<-i> I<indent>] [B<-w> I<width>] [I<input> [I<output>]]
+pod2text [B<-aclst>] [B<-i> I<indent>] [B<-q> I<quotes>] [B<-w> I<width>]
+[I<input> [I<output>]]
 
 pod2text B<-h>
 
@@ -148,6 +150,18 @@ printed after C<=head1>, although one is still printed after C<=head2>,
 because this is the expected formatting for manual pages; if you're
 formatting arbitrary text documents, using this option is recommended.
 
+=item B<-q> I<quotes>, B<--quotes>=I<quotes>
+
+Sets the quote marks used to surround CE<lt>> text to I<quotes>.  If
+I<quotes> is a single character, it is used as both the left and right
+quote; if I<quotes> is two characters, the first character is used as the
+left quote and the second as the right quoted; and if I<quotes> is four
+characters, the first two are used as the left quote and the second two as
+the right quote.
+
+I<quotes> may also be set to the special value C<none>, in which case no
+quote marks are added around CE<lt>> text.
+
 =item B<-s>, B<--sentence>
 
 Assume each sentence ends with two spaces and try to preserve that spacing.