summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRuss Allbery <rra@stanford.edu>2002-08-03 13:56:42 -0700
committerhv <hv@crypt.org>2002-08-22 12:05:57 +0000
commit11f72409a81d362ab963d688ed5b84835e953fd8 (patch)
tree551d2a5cedd8d66d5d323d69c39f6501da5c616b
parentcaffd4cf829def5d43751df796fc8cbd66c0794d (diff)
downloadperl-11f72409a81d362ab963d688ed5b84835e953fd8.tar.gz
podlators 1.24 released
Message-ID: <ylbs8jff9h.fsf@windlord.stanford.edu> p4raw-id: //depot/perl@17753
-rw-r--r--MANIFEST1
-rw-r--r--lib/Pod/Text.pm37
-rw-r--r--lib/Pod/Text/Overstrike.pm7
-rw-r--r--lib/Pod/t/basic.t4
-rw-r--r--lib/Pod/t/text-options.t144
-rw-r--r--pod/pod2text.PL10
6 files changed, 185 insertions, 18 deletions
diff --git a/MANIFEST b/MANIFEST
index 36dafce59b..529b00be2a 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1395,6 +1395,7 @@ lib/Pod/t/parselink.t podlators test
lib/Pod/t/pod2html-lib.pl pod2html testing library
lib/Pod/t/Select.t See if Pod::Select works
lib/Pod/t/text-errors.t podlators test
+lib/Pod/t/text-options.t podlators test
lib/Pod/t/text.t podlators test
lib/Pod/t/Usage.t See if Pod::Usage works
lib/Pod/t/utils.t Test for Pod::ParseUtils
diff --git a/lib/Pod/Text.pm b/lib/Pod/Text.pm
index 3325e950cc..1028f2e9e1 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.20 2002/07/15 05:46:00 eagle Exp $
+# $Id: Text.pm,v 2.21 2002/08/04 03:34:58 eagle Exp $
#
# Copyright 1999, 2000, 2001, 2002 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.20;
+$VERSION = 2.21;
##############################################################################
@@ -177,6 +177,7 @@ sub initialize {
$$self{alt} = 0 unless defined $$self{alt};
$$self{indent} = 4 unless defined $$self{indent};
+ $$self{margin} = 0 unless defined $$self{margin};
$$self{loose} = 0 unless defined $$self{loose};
$$self{sentence} = 0 unless defined $$self{sentence};
$$self{width} = 76 unless defined $$self{width};
@@ -195,8 +196,11 @@ sub initialize {
croak qq(Invalid quote specification "$$self{quotes}");
}
- $$self{INDENTS} = []; # Stack of indentations.
- $$self{MARGIN} = $$self{indent}; # Current left margin in spaces.
+ # Stack of indentations.
+ $$self{INDENTS} = [];
+
+ # Current left margin.
+ $$self{MARGIN} = $$self{indent} + $$self{margin};
$self->SUPER::initialize;
@@ -496,10 +500,12 @@ sub heading {
$text = $self->interpolate ($text, $line);
if ($$self{alt}) {
my $closemark = reverse (split (//, $marker));
- $self->output ("\n" . "$marker $text $closemark" . "\n\n");
+ my $margin = ' ' x $$self{margin};
+ $self->output ("\n" . "$margin$marker $text $closemark" . "\n\n");
} else {
$text .= "\n" if $$self{loose};
- $self->output (' ' x $indent . $text . "\n");
+ my $margin = ' ' x ($$self{margin} + $indent);
+ $self->output ($margin . $text . "\n");
}
}
@@ -526,12 +532,12 @@ sub item {
undef $$self{ITEM};
my $indent = $$self{INDENTS}[-1];
unless (defined $indent) { $indent = $$self{indent} }
- my $space = ' ' x $indent;
- $space =~ s/^ /:/ if $$self{alt};
+ my $margin = ' ' x $$self{margin};
if (!$_ || /^\s+$/ || ($$self{MARGIN} - $indent < length ($tag) + 1)) {
- my $margin = $$self{MARGIN};
+ my $realindent = $$self{MARGIN};
$$self{MARGIN} = $indent;
my $output = $self->reformat ($tag);
+ $output =~ s/^$margin /$margin:/ if ($$self{alt} && $indent > 0);
$output =~ s/\n*$/\n/;
# If the text is just whitespace, we have an empty item paragraph;
@@ -541,11 +547,13 @@ sub item {
$output .= "\n" if $_ && $_ =~ /^\s*$/;
$self->output ($output);
- $$self{MARGIN} = $margin;
+ $$self{MARGIN} = $realindent;
$self->output ($self->reformat ($_)) if $_ && /\S/;
} else {
+ my $space = ' ' x $indent;
+ $space =~ s/^$margin /$margin:/ if $$self{alt};
$_ = $self->reformat ($_);
- s/^ /:/ if ($$self{alt} && $indent > 0);
+ s/^$margin /$margin:/ if ($$self{alt} && $indent > 0);
my $tagspace = ' ' x length $tag;
s/^($space)$tagspace/$1$tag/ or warn "Bizarre space in item";
$self->output ($_);
@@ -716,6 +724,13 @@ 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 margin
+
+The width of the left margin in spaces. Defaults to 0. This is the margin
+for all text, including headings, not the amount by which regular text is
+indented; for the latter, see the I<indent> option. To set the right
+margin, see the I<width> option.
+
=item quotes
Sets the quote marks used to surround CE<lt>> text. If the value is a
diff --git a/lib/Pod/Text/Overstrike.pm b/lib/Pod/Text/Overstrike.pm
index 503f4003ad..8ba918396c 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.9 2002/07/15 05:46:00 eagle Exp $
+# $Id: Overstrike.pm,v 1.10 2002/08/04 03:35:01 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.09;
+$VERSION = 1.10;
##############################################################################
@@ -85,7 +85,8 @@ 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");
+ my $margin = ' ' x ($$self{margin} + $indent);
+ $self->output ($margin . $text . "\n");
}
# Fix the various formatting codes.
diff --git a/lib/Pod/t/basic.t b/lib/Pod/t/basic.t
index eb6db54f30..a61b4bf07f 100644
--- a/lib/Pod/t/basic.t
+++ b/lib/Pod/t/basic.t
@@ -98,9 +98,9 @@ for (sort keys %translators) {
close MASTER;
close OUTPUT;
- # EBCDIC platforms use a different character for ESC
+ # OS/390 is EBCDIC, which uses a different character for ESC
# apparently. Try to convert so that the test still works.
- if (ord('A') eq 193 && $_ eq 'Pod::Text::Termcap') {
+ if ($^O eq 'os390' && $_ eq 'Pod::Text::Termcap') {
$output =~ tr/\033/\047/;
}
diff --git a/lib/Pod/t/text-options.t b/lib/Pod/t/text-options.t
new file mode 100644
index 0000000000..b398fcf922
--- /dev/null
+++ b/lib/Pod/t/text-options.t
@@ -0,0 +1,144 @@
+#!/usr/bin/perl -w
+# $Id: text-options.t,v 1.2 2002/08/04 03:38:24 eagle Exp $
+#
+# text-options.t -- Additional tests for Pod::Text options.
+#
+# 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..3\n";
+}
+
+END {
+ print "not ok 1\n" unless $loaded;
+}
+
+use Pod::Text;
+
+$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::Text->new (%options) 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";
+ 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::Text. The
+# input and output are separated by lines containing only ###.
+
+__DATA__
+
+###
+alt 1
+###
+=head1 SAMPLE
+
+=over 4
+
+=item F
+
+Paragraph.
+
+=item Bar
+
+=item B
+
+Paragraph.
+
+=item Longer
+
+Paragraph.
+
+=back
+
+###
+
+==== SAMPLE ====
+
+: F Paragraph.
+
+: Bar
+: B Paragraph.
+
+: Longer
+ Paragraph.
+
+###
+
+###
+margin 4
+###
+=head1 SAMPLE
+
+This is some body text that is long enough to be a paragraph that wraps,
+thereby testing margins with wrapped paragraphs.
+
+ This is some verbatim text.
+
+=over 6
+
+=item Test
+
+This is a test of an indented paragraph.
+
+This is another indented paragraph.
+
+=back
+###
+ SAMPLE
+ This is some body text that is long enough to be a paragraph that
+ wraps, thereby testing margins with wrapped paragraphs.
+
+ This is some verbatim text.
+
+ Test This is a test of an indented paragraph.
+
+ This is another indented paragraph.
+
+###
diff --git a/pod/pod2text.PL b/pod/pod2text.PL
index 53270dd3ab..0486e2da0a 100644
--- a/pod/pod2text.PL
+++ b/pod/pod2text.PL
@@ -78,8 +78,8 @@ my %options;
$options{sentence} = 0;
Getopt::Long::config ('bundling');
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;
+ 'loose|l', 'margin|left-margin|m=i', 'overstrike|o',
+ '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.
@@ -162,6 +162,12 @@ 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<-m> I<width>, B<--left-margin>=I<width>, B<--margin>=I<width>
+
+The width of the left margin in spaces. Defaults to 0. This is the margin
+for all text, including headings, not the amount by which regular text is
+indented; for the latter, see B<-i> option.
+
=item B<-o>, B<--overstrike>
Format the output with overstruck printing. Bold text is rendered as