t/pod/nested_seqs.xr Expected results for nested_seqs.t
t/pod/oneline_cmds.t Test single paragraph ==cmds
t/pod/oneline_cmds.xr Expected results for oneline_cmds.t
+t/pod/p2u_data.pl Test Pod::Usage
t/pod/plainer.t Test Pod::Plainer
t/pod/pod2usage2.t Test Pod::Usage
t/pod/pod2usage.t Test Pod::Usage
t/pod/testp2pt.pl Module to test Pod::PlainText for a given file
t/pod/testpchk.pl Module to test Pod::Checker for a given file
t/pod/testpods/lib/Pod/Stuff.pm Sample data for find.t
+t/pod/twice.t Test Pod::Parser
t/README Instructions for regression tests
t/run/exit.t Test perl's exit status.
t/run/fresh_perl.t Tests that require a fresh perl.
=item *
-Check for malformed or nonexisting entities C<EE<lt>...E<gt>>.
+Check for malformed or non-existing entities C<EE<lt>...E<gt>>.
=item *
=item * unresolved internal link I<NAME>
The given link to I<NAME> does not have a matching node in the current
-POD. This also happend when a single word node name is not enclosed in
+POD. This also happened when a single word node name is not enclosed in
C<"">.
=item * Unknown command "I<CMD>"
=item * =item type mismatch (I<one> vs. I<two>)
-A list started with e.g. a bulletted C<=item> and continued with a
+A list started with e.g. a bullet-like C<=item> and continued with a
numbered one. This is obviously inconsistent. For most translators the
type of the I<first> C<=item> determines the type of the list.
=head2 Hyperlinks
-There are some warnings wrt. malformed hyperlinks.
+There are some warnings with respect to malformed hyperlinks:
=over 4
method to print errors and warnings. The summary output (e.g.
"Pod syntax OK") has been dropped from the module and has been included in
B<podchecker> (the script). This allows users of B<Pod::Checker> to
-control completely the output behaviour. Users of B<podchecker> (the script)
-get the well-known behaviour.
+control completely the output behavior. Users of B<podchecker> (the script)
+get the well-known behavior.
=cut
package Pod::ParseUtils;
use vars qw($VERSION);
-$VERSION = 1.33; ## Current version of this package
+$VERSION = 1.35; ## Current version of this package
require 5.005; ## requires this Perl version or later
=head1 NAME
$node = $1;
$type = 'item';
}
+
+ # non-standard: Hyperlink with alt-text - doesn't remove protocol prefix, maybe it should?
+ elsif(m!^ \s* (.*?) \s* [|] \s* (\w+:[^:\s] [^\s|]*?) \s* $!ix) {
+ ($alttext,$node) = ($1,$2);
+ $type = 'hyperlink';
+ }
+
# non-standard: Hyperlink
elsif(m!^(\w+:[^:\s]\S*)$!i) {
$node = $1;
elsif(m!^(.*?)\s*[|]\s*/(.+)$!) {
($alttext, $node) = ($1,$2);
}
- # nonstandard: alttext and hyperlink
- elsif(m!^(.*?)\s*[|]\s*(\w+:[^:\s]\S*)$!) {
- ($alttext, $node) = ($1,$2);
- $type = 'hyperlink';
- }
# must be an item or a "malformed" section (without "")
else {
$node = $_;
Look for a node or index entry named C<$name> in the object.
Returns the unique id of the node (i.e. the second element of the array
-stored in the node arry) or undef if not found.
+stored in the node array) or undef if not found.
=cut
package Pod::Parser;
use vars qw($VERSION);
-$VERSION = 1.32; ## Current version of this package
+$VERSION = 1.35; ## Current version of this package
require 5.005; ## requires this Perl version or later
#############################################################################
For the most part, the B<Pod::Parser> base class should be able to
do most of the input parsing for you and leave you free to worry about
-how to intepret the commands and translate the result.
+how to interpret the commands and translate the result.
Note that all we have described here in this quick overview is the
simplest most straightforward use of B<Pod::Parser> to do stream-based
The parameter C<$text> is a string or block of text to be parsed
for interior sequences; and the parameter C<$line_num> is the
-line number curresponding to the beginning of C<$text>.
+line number corresponding to the beginning of C<$text>.
B<parse_text()> will parse the given text into a parse-tree of "nodes."
and interior-sequences. Each "node" in the parse tree is either a
$seq->append($expand_text ? &$xtext_sub($self,$_,$seq) : $_);
}
## Keep track of line count
- $line += tr/\n//;
+ $line += s/\r*\n//;
## Remember the "current" sequence
$seq = $seq_stack[-1];
}
my $self = shift;
my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : ();
my ($infile, $outfile) = @_;
- my ($in_fh, $out_fh) = (gensym(), gensym()) if ($] < 5.006);
+ my ($in_fh, $out_fh);
+ if ($] < 5.006) {
+ ($in_fh, $out_fh) = (gensym(), gensym());
+ }
my ($close_input, $close_output) = (0, 0);
local *myData = $self;
local *_;
they are text-strings, or by calling their B<emit()> method if they
are objects/references.
+=head1 CAVEATS
+
+Please note that POD has the notion of "paragraphs": this is something
+starting I<after> a blank (read: empty) line, with the single exception
+of the file start, which is also starting a paragraph. That means that
+especially a command (e.g. C<=head1>) I<must> be preceded with a blank
+line; C<__END__> is I<not> a blank line.
+
=head1 SEE ALSO
L<Pod::InputObjects>, L<Pod::Select>
}
}
+# third level heading - not strictly perlpodspec compliant
+sub cmd_head3 {
+ my $self = shift;
+ local $_ = shift;
+ s/\s+$//;
+ $_ = $self->interpolate ($_, shift);
+ if ($$self{alt}) {
+ $self->output ("\n= $_ =\n");
+ } else {
+ $self->output (' ' x ($$self{indent}) . $_ . "\n");
+ }
+}
+
+# fourth level heading - not strictly perlpodspec compliant
+# just like head3
+*cmd_head4 = \&cmd_head3;
+
# Start a list.
sub cmd_over {
my $self = shift;
package Pod::Select;
use vars qw($VERSION);
-$VERSION = 1.30; ## Current version of this package
+$VERSION = 1.35; ## Current version of this package
require 5.005; ## requires this Perl version or later
#############################################################################
## Keep track of current sections levels and headings
$_ = $paragraph;
- if (/^=((?:sub)*)(?:head(?:ing)?|sec(?:tion)?)(\d*)\s+(.*)\s*$/)
+ if (/^=((?:sub)*)(?:head(?:ing)?|sec(?:tion)?)(\d*)\s+(.*?)\s*$/)
{
## This is a section heading command
my ($level, $heading) = ($2, $3);
All other arguments should correspond to the names of input files
containing POD sections. A file name of "-" or "<&STDIN" will
-be interpeted to mean standard input (which is the default if no
+be interpreted to mean standard input (which is the default if no
filenames are given).
=cut
=item *
If program usage has been explicitly requested by the user, it is often
-desireable to exit with a status of 1 (as opposed to 0) after issuing
-the user-requested usage message. It is also desireable to give a
+desirable to exit with a status of 1 (as opposed to 0) after issuing
+the user-requested usage message. It is also desirable to give a
more verbose description of program usage in this case.
=back
Based on code for B<Pod::Text::pod2text()> written by
Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
-=head1 ACKNOWLEDGEMENTS
+=head1 ACKNOWLEDGMENTS
Steven McDougall E<lt>swmcd@world.std.comE<gt> for his help and patience
with re-writing this manpage.
elsif ($opts{"-verbose"} >= 2 && $opts{"-verbose"} != 99) {
$parser->select('.*');
}
+ elsif ($opts{"-verbose"} >= 2 && $opts{"-verbose"} != 99) {
+ $parser->select('.*');
+ }
elsif ($opts{"-verbose"} == 99) {
$parser->select( $opts{"-sections"} );
$opts{"-verbose"} = 1;
## spit out the entire PODs. Might as well invoke perldoc
my $progpath = File::Spec->catfile($Config{scriptdir}, "perldoc");
system($progpath, $opts{"-input"});
+ if($?) {
+ # RT16091: fall back to more if perldoc failed
+ system($ENV{PAGER} || 'more', $opts{"-input"});
+ }
}
else {
$parser->parse_from_file($opts{"-input"}, $opts{"-output"});
--- /dev/null
+use Pod::Usage;
+pod2usage(-verbose => 2, -exit => 17, -input => \*DATA);
+
+__DATA__
+=head1 NAME
+
+Test
+
+=head1 SYNOPSIS
+
+perl podusagetest.pl
+
+=head1 DESCRIPTION
+
+This is a test.
+
+=cut
+
defined($f2text = <$fh2>) and chomp($f2text);
++$line;
last unless ( defined($f1text) and defined($f2text) );
+ # kill any extra line endings
+ $f1text =~ s/[\r\n]+$//s;
+ $f2text =~ s/[\r\n]+$//s;
$diffs = (ref $cmplines) ? &$cmplines($f1text, $f2text)
: ($f1text ne $f2text);
last if $diffs;
--- /dev/null
+use strict;
+use Test;
+use File::Spec;
+
+BEGIN { plan tests => 1 }
+
+use Pod::Parser;
+use Carp;
+$SIG{__DIE__} = \&Carp::confess;
+
+eval {require IO::String;};
+skip($@ ? 'no IO::String' : '', sub {
+ {
+ my $pod_string = 'some I<silly> text';
+ my $handle = IO::String->new( \$pod_string );
+ my $parser = Pod::Parser->new();
+ $parser->parse_from_file( $0, $handle );
+ }
+ # free the reference
+ {
+ my $parser = Pod::Parser->new();
+ $parser->parse_from_file( $0, File::Spec->devnull );
+ }
+ 1;
+});
+
+exit 0;
+
+__END__
+
+=head1 EXAMPLE
+
+This test makes sure the parse_from_file is re-entrant
+
+=cut
+
projects / p5sagit/p5-mst-13.2.git / commitdiff