From: Jarkko Hietaniemi Date: Sat, 20 Oct 2001 15:18:57 +0000 (+0000) Subject: Upgrade to podlators 1.11, from Russ Allbery. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=59548ecaeaf22737b5c8a75235f5e142c16de75d;p=p5sagit%2Fp5-mst-13.2.git Upgrade to podlators 1.11, from Russ Allbery. p4raw-id: //depot/perl@12535 --- diff --git a/lib/Pod/Man.pm b/lib/Pod/Man.pm index 9c6eba0..ffb35dc 100644 --- a/lib/Pod/Man.pm +++ b/lib/Pod/Man.pm @@ -1074,7 +1074,7 @@ sub outindex { $$self{INDEX} = []; my $output; if (@entries) { - my $output = '.IX Xref "' + $output = '.IX Xref "' . join (' ', map { s/\"/\"\"/; $_ } @entries) . '"' . "\n"; } @@ -1132,10 +1132,10 @@ sub switchquotes { # changes for nroff in =item tags, since they're unnecessary. $nroff =~ s/\\f\(CW(.*)\\f[PR]/$1/g; - # Now finally output the command. Only bother with .if if the nroff + # Now finally output the command. Only bother with .ie if the nroff # and troff output isn't the same. if ($nroff ne $troff) { - return ".if n $command $nroff\n.el $command $troff\n"; + return ".ie n $command $nroff\n.el $command $troff\n"; } else { return "$command $nroff\n"; } diff --git a/lib/Pod/Text.pm b/lib/Pod/Text.pm index 9ebca63..3a1dc7b 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.11 2001/07/10 11:08:10 eagle Exp $ +# $Id: Text.pm,v 2.13 2001/10/20 08:07:21 eagle Exp $ # # Copyright 1999, 2000, 2001 by Russ Allbery # @@ -41,7 +41,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.11; +$VERSION = 2.13; ############################################################################## @@ -194,6 +194,9 @@ sub initialize { $$self{MARGIN} = $$self{indent}; # Current left margin in spaces. $self->SUPER::initialize; + + # Tell Pod::Parser that we want the non-POD stuff too if code was set. + $self->parseopts ('-want_nonPODs' => 1) if $$self{code}; } @@ -306,13 +309,15 @@ sub interior_sequence { local $_ = shift; return '' if ($command eq 'X' || $command eq 'Z'); - # Expand escapes into the actual character now, carping if invalid. + # Expand escapes into the actual character now, warning if invalid. if ($command eq 'E') { if (/^\d+$/) { return chr; } else { return $ESCAPES{$_} if defined $ESCAPES{$_}; - carp "Unknown escape: E<$_>"; + my $seq = shift; + my ($file, $line) = $seq->file_line; + warn "$file:$line: Unknown escape: E<$_>\n"; return "E<$_>"; } } @@ -334,15 +339,22 @@ sub interior_sequence { elsif ($command eq 'F') { return $self->seq_f ($_) } elsif ($command eq 'I') { return $self->seq_i ($_) } elsif ($command eq 'L') { return $self->seq_l ($_) } - else { carp "Unknown sequence $command<$_>" } + else { + my $seq = shift; + my ($file, $line) = $seq->file_line; + warn "$file:$line: Unknown sequence $command<$_>\n"; + } } # Called for each paragraph that's actually part of the POD. We take -# advantage of this opportunity to untabify the input. +# advantage of this opportunity to untabify the input. Also, if given the +# code option, we may see paragraphs that aren't part of the POD and need to +# output them directly. sub preprocess_paragraph { my $self = shift; local $_ = shift; 1 while s/^(.*?)(\t+)/$1 . ' ' x (length ($2) * 8 - length ($1) % 8)/me; + $self->output_code ($_) if $self->cutting; $_; } @@ -417,10 +429,12 @@ sub cmd_over { # End a list. sub cmd_back { - my $self = shift; + my ($self, $text, $line, $paragraph) = @_; $$self{MARGIN} = pop @{ $$self{INDENTS} }; unless (defined $$self{MARGIN}) { - carp "Unmatched =back"; + my $file; + ($file, $line) = $paragraph->file_line; + warn "$file:$line: Unmatched =back\n"; $$self{MARGIN} = $$self{indent}; } } @@ -576,7 +590,7 @@ sub item { local $_ = shift; my $tag = $$self{ITEM}; unless (defined $tag) { - carp "item called without tag"; + carp "Item called without tag"; return; } undef $$self{ITEM}; @@ -650,6 +664,11 @@ sub reformat { # Output text to the output device. sub output { $_[1] =~ tr/\01/ /; print { $_[0]->output_handle } $_[1] } +# Output a block of code (something that isn't part of the POD text). Called +# by preprocess_paragraph only if we were given the code option. Exists here +# only so that it can be overridden by subclasses. +sub output_code { $_[0]->output ($_[1]) } + ############################################################################## # Backwards compatibility @@ -740,6 +759,12 @@ If set to a true value, selects an alternate output format that, among other things, uses a different heading style and marks C<=item> entries with a colon in the left margin. Defaults to false. +=item code + +If set to a true value, the non-POD parts of the input file will be included +in the output. Useful for viewing code documented with POD blocks with the +POD rendered and the code left intact. + =item indent The number of spaces to indent regular text, and the default indentation for @@ -792,8 +817,10 @@ details. =item Bizarre space in item -(W) Something has gone wrong in internal C<=item> processing. This message -indicates a bug in Pod::Text; you should never see it. +=item Item called without tag + +(W) Something has gone wrong in internal C<=item> processing. These +messages indicate a bug in Pod::Text; you should never see them. =item Can't open %s for reading: %s @@ -810,17 +837,17 @@ invalid. A quote specification must be one, two, or four characters long. (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 +=item %s:%d: Unknown escape: %s (W) The POD source contained an CE> escape that Pod::Text didn't know about. -=item Unknown sequence: %s +=item %s:%d: Unknown sequence: %s (W) The POD source contained a non-standard internal sequence (something of the form CE>) that Pod::Text didn't know about. -=item Unmatched =back +=item %s:%d: Unmatched =back (W) Pod::Text encountered a C<=back> command that didn't correspond to an C<=over> command. diff --git a/lib/Pod/Text/Color.pm b/lib/Pod/Text/Color.pm index f747a96..35f0b4b 100644 --- a/lib/Pod/Text/Color.pm +++ b/lib/Pod/Text/Color.pm @@ -1,7 +1,7 @@ # Pod::Text::Color -- Convert POD data to formatted color ASCII text -# $Id: Color.pm,v 1.0 2001/07/10 11:03:43 eagle Exp $ +# $Id: Color.pm,v 1.1 2001/10/20 08:08:39 eagle Exp $ # -# Copyright 1999 by Russ Allbery +# Copyright 1999, 2001 by Russ Allbery # # This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. @@ -29,7 +29,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.00; +$VERSION = 1.01; ############################################################################## @@ -57,6 +57,13 @@ sub seq_b { return colored ($_[1], 'bold') } sub seq_f { return colored ($_[1], 'cyan') } sub seq_i { return colored ($_[1], 'yellow') } +# Output any included code in green. +sub output_code { + my ($self, $code) = @_; + $code = colored ($code, 'green'); + $self->output ($code); +} + # We unfortunately have to override the wrapping code here, since the normal # wrapping code gets really confused by all the escape sequences. sub wrap { @@ -126,7 +133,7 @@ Russ Allbery . =head1 COPYRIGHT AND LICENSE -Copyright 1999 by Russ Allbery . +Copyright 1999, 2001 by Russ Allbery . This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. diff --git a/lib/Pod/Text/Overstrike.pm b/lib/Pod/Text/Overstrike.pm index be159f4..c405235 100644 --- a/lib/Pod/Text/Overstrike.pm +++ b/lib/Pod/Text/Overstrike.pm @@ -1,5 +1,5 @@ # Pod::Text::Overstrike -- Convert POD data to formatted overstrike text -# $Id: Overstrike.pm,v 1.2 2001/07/10 11:04:36 eagle Exp $ +# $Id: Overstrike.pm,v 1.3 2001/10/20 08:11:29 eagle Exp $ # # Created by Joe Smith 30-Nov-2000 # (based on Pod::Text::Color by Russ Allbery ) @@ -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.02; +$VERSION = 1.03; ############################################################################## @@ -81,6 +81,13 @@ 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; $_ } +# Output any included code in bold. +sub output_code { + my ($self, $code) = @_; + $code =~ s/(.)/$1\b$1/g; + $self->output ($code); +} + # We unfortunately have to override the wrapping code here, since the normal # wrapping code gets really confused by all the escape sequences. sub wrap { @@ -90,7 +97,7 @@ sub wrap { my $spaces = ' ' x $$self{MARGIN}; my $width = $$self{width} - $$self{MARGIN}; while (length > $width) { - if (s/^((?:(?:[^\n]\cH)?[^\n]){0,$width})\s+// + if (s/^((?:(?:[^\n]\cH)?[^\n]){0,$width})(\Z|\s+)// || s/^((?:(?:[^\n]\cH)?[^\n]){$width})//) { $output .= $spaces . $1 . "\n"; } else { @@ -159,6 +166,7 @@ Joe Smith , using the framework created by Russ Allbery =head1 COPYRIGHT AND LICENSE Copyright 2000 by Joe Smith . +Copyright 2001 by Russ Allbery . This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. diff --git a/lib/Pod/Text/Termcap.pm b/lib/Pod/Text/Termcap.pm index c49e2c3..9e11e01 100644 --- a/lib/Pod/Text/Termcap.pm +++ b/lib/Pod/Text/Termcap.pm @@ -1,7 +1,7 @@ # Pod::Text::Termcap -- Convert POD data to ASCII text with format escapes. -# $Id: Termcap.pm,v 1.1 2001/07/10 11:04:36 eagle Exp $ +# $Id: Termcap.pm,v 1.2 2001/10/20 08:09:30 eagle Exp $ # -# Copyright 1999 by Russ Allbery +# Copyright 1999, 2001 by Russ Allbery # # 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.01; +$VERSION = 1.02; ############################################################################## @@ -82,6 +82,12 @@ sub cmd_head2 { sub seq_b { my $self = shift; return "$$self{BOLD}$_[0]$$self{NORM}" } sub seq_i { my $self = shift; return "$$self{UNDL}$_[0]$$self{NORM}" } +# Output any included code in bold. +sub output_code { + my ($self, $code) = @_; + $self->output ($$self{BOLD} . $code . $$self{NORM}); +} + # Override the wrapping code to igore the special sequences. sub wrap { my $self = shift; @@ -143,7 +149,7 @@ Russ Allbery . =head1 COPYRIGHT AND LICENSE -Copyright 1999 by Russ Allbery . +Copyright 1999, 2001 by Russ Allbery . This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. diff --git a/pod/pod2man.PL b/pod/pod2man.PL index cef507b..5a1deea 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.6 2001/07/10 11:23:46 eagle Exp $ +# $Id: pod2man.PL,v 1.7 2001/10/20 08:24:15 eagle Exp $ # # Copyright 1999, 2000, 2001 by Russ Allbery # @@ -51,6 +51,9 @@ use Pod::Usage qw(pod2usage); use strict; +# Silence -w warnings. +use vars qw($running_under_some_shell); + # Insert -- into @ARGV before any single dash argument to hide it from # Getopt::Long; we want to interpret it as meaning stdin (which Pod::Parser # does correctly). @@ -64,7 +67,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', 'official|o', 'quotes|q=s', 'lax|l', - 'help|h') or exit 1; + 'help|h', 'verbose|v') or exit 1; pod2usage (0) if $options{help}; # Official sets --center, but don't override things explicitly set. @@ -72,12 +75,17 @@ if ($options{official} && !defined $options{center}) { $options{center} = 'Perl Programmers Reference Guide'; } +# Verbose is only our flag, not a Pod::Man flag. +my $verbose = $options{verbose}; +delete $options{verbose}; + # Initialize and run the formatter, pulling a pair of input and output off at # a time. my $parser = Pod::Man->new (%options); my @files; do { @files = splice (@ARGV, 0, 2); + print " $files[1]\n" if $verbose; $parser->parse_from_file (@files); } while (@ARGV); @@ -93,7 +101,7 @@ pod2man [B<--section>=I] [B<--release>=I] [B<--center>=I] [B<--date>=I] [B<--fixed>=I] [B<--fixedbold>=I] [B<--fixeditalic>=I] [B<--fixedbolditalic>=I] [B<--official>] [B<--lax>] -[B<--quotes>=I] [I [I] ...] +[B<--quotes>=I] [B<--verbose>] [I [I] ...] pod2man B<--help> @@ -217,6 +225,10 @@ 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<-v>, B<--verbose> + +Print out the name of each output file as it is being generated. + =back =head1 DIAGNOSTICS diff --git a/pod/pod2text.PL b/pod/pod2text.PL index 54a2279..e038021 100644 --- a/pod/pod2text.PL +++ b/pod/pod2text.PL @@ -37,7 +37,7 @@ print OUT <<'!NO!SUBS!'; # pod2text -- Convert POD data to formatted ASCII text. # -# Copyright 1999, 2000 by Russ Allbery +# Copyright 1999, 2000, 2001 by Russ Allbery # # This program is free software; you may redistribute it and/or modify it # under the same terms as Perl itself. @@ -53,6 +53,9 @@ use Pod::Usage qw(pod2usage); use strict; +# Silence -w warnings. +use vars qw($running_under_some_shell); + # Take an initial pass through our options, looking for one of the form # -. We turn that into -w for compatibility with the # original pod2text script. @@ -74,7 +77,7 @@ my $stdin; my %options; $options{sentence} = 0; Getopt::Long::config ('bundling'); -GetOptions (\%options, 'alt|a', 'color|c', 'help|h', 'indent|i=i', +GetOptions (\%options, 'alt|a', 'code', 'color|c', 'help|h', 'indent|i=i', 'loose|l', 'overstrike|o', 'quotes|q=s', 'sentence|s', 'termcap|t', 'width|w=i') or exit 1; pod2usage (1) if $options{help}; @@ -107,8 +110,8 @@ pod2text - Convert POD data to formatted ASCII text =head1 SYNOPSIS -pod2text [B<-aclost>] [B<-i> I] [B<-q> I] [B<-w> I] -[I [I]] +pod2text [B<-aclost>] [B<--code>] [B<-i> I] S<[B<-q> I]> +S<[B<-w> I]> [I [I]] pod2text B<-h> @@ -132,6 +135,12 @@ given, the formatted output is written to STDOUT. Use an alternate output format that, among other things, uses a different heading style and marks C<=item> entries with a colon in the left margin. +=item B<--code> + +Include any non-POD text from the input file in the output as well. Useful +for viewing code documented with POD blocks with the POD rendered and the +code left intact. + =item B<-c>, B<--color> Format the output with ANSI color escape sequences. Using this option