From: Jarkko Hietaniemi Date: Thu, 10 Aug 2000 22:38:13 +0000 (+0000) Subject: Update to Pod::Parser 1.17, from Brad Appleton. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=92e3d63aacb66085fea74c3f951f09e136337b97;p=p5sagit%2Fp5-mst-13.2.git Update to Pod::Parser 1.17, from Brad Appleton. p4raw-id: //depot/perl@6578 --- diff --git a/lib/Pod/Checker.pm b/lib/Pod/Checker.pm index ae32677..37ed68f 100644 --- a/lib/Pod/Checker.pm +++ b/lib/Pod/Checker.pm @@ -10,7 +10,7 @@ package Pod::Checker; use vars qw($VERSION); -$VERSION = 1.098; ## Current version of this package +$VERSION = 1.2; ## Current version of this package require 5.005; ## requires this Perl version or later use Pod::ParseUtils; ## for hyperlinks and lists @@ -44,7 +44,8 @@ This function can take a hash of options: =item B<-warnings> =E I -Turn warnings on/off. See L<"Warnings">. +Turn warnings on/off. I is usually 1 for on, but higher values +trigger additional warnings. See L<"Warnings">. =back @@ -212,11 +213,15 @@ There is some whitespace on a seemingly empty line. POD is very sensitive to such things, so this is flagged. B users switch on the B option to avoid this problem. +=begin _disabled_ + =item * file does not start with =head The file starts with a different POD directive than head. This is most probably something you do not want. +=end _disabled_ + =item * No numeric argument for =over The C<=over> command is supposed to have a numeric argument (the @@ -243,7 +248,8 @@ type of the I C<=item> determines the type of the list. Angle brackets not written as CltE> and CgtE> can potentially cause errors as they could be misinterpreted as -markup commands. +markup commands. This is only printed when the -warnings level is +greater than 1. =item * Unknown entity @@ -273,11 +279,41 @@ The NAME section (C<=head1 NAME>) should consist of a single paragraph with the script/module name, followed by a dash `-' and a very short description of what the thing is good for. -=item * Hyperlinks +=back + +=head2 Hyperlinks + +There are some warnings wrt. malformed hyperlinks. + +=over 4 + +=item * collapsing newlines to blanks + +A hyperlink LE...E spans more than one line. This may indicate +and error. -There are some warnings wrt. hyperlinks: -Leading/trailing whitespace, newlines in hyperlinks, -brackets C<()>. +=item * ignoring leading/trailing whitespace in link + +There is whitespace at the beginning or the end of the contents of +LE...E. + +=item * (section) in '$page' deprecated + +There is a section detected in the page name of LE...E, e.g. +Cpasswd(2)E>. POD hyperlinks may point to POD documents only. +Please write Cpasswd(2)E> instead. Some formatters are able +to expand this to appropriate code. For links to (builtin) functions, +please say Cperlfunc/mkdirE>, without (). + +=item * alternative text/node '%s' contains non-escaped | or / + +The characters C<|> and C are special in the LE...E context. +Although the hyperlink parser does its best to determine which "/" is +text and which is a delimiter in case of doubt, one ought to escape +these literal characters like this: + + / E + | E =back @@ -307,7 +343,6 @@ use strict; use Carp; use Exporter; use Pod::Parser; -require VMS::Filespec if $^O eq 'VMS'; use vars qw(@ISA @EXPORT); @ISA = qw(Pod::Parser); @@ -471,7 +506,6 @@ sub podchecker( $ ; $ % ) { ## Now create a pod checker my $checker = new Pod::Checker(%options); - $checker->parseopts(-process_cut_cmd => 1, -warnings => 1); ## Now check the pod document for errors $checker->parse_from_file($infile, $outfile); @@ -486,6 +520,27 @@ sub podchecker( $ ; $ % ) { ## Method definitions begin here ##------------------------------- +################################## + +=over 4 + +=item Cnew( %options )> + +Return a reference to a new Pod::Checker object that inherits from +Pod::Parser and is used for calling the required methods later. The +following options are recognized: + +C<-warnings =E num> + Print warnings if C is true. The higher the value of C, +the more warnings are printed. Currently there are only levels 1 and 2. + +C<-quiet =E num> + If C is true, do not print any errors/warnings. This is useful +when Pod::Checker is used to munge POD code into plain text from within +POD formatters. + +=cut + ## sub new { ## my $this = shift; ## my $class = ref($this) || $this; @@ -501,7 +556,9 @@ sub initialize { ## Initialize number of errors, and setup an error function to ## increment this number and then print to the designated output. $self->{_NUM_ERRORS} = 0; - $self->errorsub('poderror'); # set the error handling subroutine + $self->{-quiet} ||= 0; + # set the error handling subroutine + $self->errorsub($self->{-quiet} ? sub { 1; } : 'poderror'); $self->{_commands} = 0; # total number of POD commands encountered $self->{_list_stack} = []; # stack for nested lists $self->{_have_begin} = ''; # stores =begin @@ -511,12 +568,11 @@ sub initialize { # print warnings? $self->{-warnings} = 1 unless(defined $self->{-warnings}); $self->{_current_head1} = ''; # the current =head1 block + $self->parseopts(-process_cut_cmd => 1, -warnings => $self->{-warnings}); } ################################## -=over 4 - =item C<$checker-Epoderror( @args )> =item C<$checker-Epoderror( {%opts}, @args )> @@ -547,7 +603,6 @@ The error level, should be 'WARNING' or 'ERROR'. sub poderror { my $self = shift; my %opts = (ref $_[0]) ? %{shift()} : (); - $opts{-file} = VMS::Filespec::unixify($opts{-file}) if (exists($opts{-file}) && $^O eq 'VMS'); ## Retrieve options chomp( my $msg = ($opts{-msg} || "")."@_" ); @@ -562,7 +617,7 @@ sub poderror { ## Increment error count and print message " ++($self->{_NUM_ERRORS}) if(!%opts || ($opts{-severity} && $opts{-severity} eq 'ERROR')); - my $out_fh = $self->output_handle(); + my $out_fh = $self->output_handle() || \*STDERR; print $out_fh ($severity, $msg, $line, $file, "\n") if($self->{-warnings} || !%opts || $opts{-severity} ne 'WARNING'); } @@ -672,7 +727,6 @@ sub end_pod { ## print the number of errors found my $self = shift; my $infile = $self->input_file(); - $infile = VMS::Filespec::unixify($infile) if $^O eq 'VMS'; my $out_fh = $self->output_handle(); if(@{$self->{_list_stack}}) { @@ -691,12 +745,15 @@ sub end_pod { my %nodes; foreach($self->node()) { $nodes{$_} = 1; - if(/^(\S+)\s+/) { + if(/^(\S+)\s+\S/) { # we have more than one word. Use the first as a node, too. # This is used heavily in perlfunc.pod $nodes{$1} ||= 2; # derived node } } + foreach($self->idx()) { + $nodes{$_} = 3; # index node + } foreach($self->hyperlink()) { my ($line,$link) = @$_; # _TODO_ what if there is a link to the page itself by the name, @@ -746,14 +803,17 @@ sub command { $self->poderror({ -line => $line, -file => $file, -severity => 'ERROR', -msg => "Unknown command '$cmd'" }); } - else { - # found a valid command - if(!$self->{_commands}++ && $cmd !~ /^head/) { - $self->poderror({ -line => $line, -file => $file, - -severity => 'WARNING', - -msg => "file does not start with =head" }); - } - ## check syntax of particular command + else { # found a valid command + $self->{_commands}++; # delete this line if below is enabled again + + ##### following check disabled due to strong request + #if(!$self->{_commands}++ && $cmd !~ /^head/) { + # $self->poderror({ -line => $line, -file => $file, + # -severity => 'WARNING', + # -msg => "file does not start with =head" }); + #} + + # check syntax of particular command if($cmd eq 'over') { # check for argument $arg = $self->interpolate_and_check($paragraph, $line,$file); @@ -1005,12 +1065,13 @@ sub _check_ptree { unless(ref) { my $count; # count the unescaped angle brackets + # complain only when warning level is greater than 1 my $i = $_; if($count = $i =~ tr/<>/<>/) { $self->poderror({ -line => $line, -file => $file, -severity => 'WARNING', -msg => "$count unescaped <> in paragraph" }) - if($self->{-warnings}); + if($self->{-warnings} && $self->{-warnings}>1); } $text .= $i; next; diff --git a/lib/Pod/Find.pm b/lib/Pod/Find.pm index 8de197b..fb0f6b8 100644 --- a/lib/Pod/Find.pm +++ b/lib/Pod/Find.pm @@ -13,8 +13,9 @@ package Pod::Find; use vars qw($VERSION); -$VERSION = 0.12; ## Current version of this package -require 5.005; ## requires this Perl version or later +$VERSION = 0.21; ## Current version of this package +require 5.005; ## requires this Perl version or later +use Carp; ############################################################################# @@ -32,12 +33,38 @@ Pod::Find - find POD documents in directory trees print "podname=",simplify_name('a/b/c/mymodule.pod'),"\n"; + $location = pod_where( { -inc => 1 }, "Pod::Find" ); + =head1 DESCRIPTION -B provides a function B that searches for POD -documents in a given set of files and directories. It returns a hash -with the file names as keys and the POD name as value. The POD name -is derived from the file name and its position in the directory tree. +B provides a set of functions to locate POD files. Note that +no function is exported by default to avoid pollution of your namespace, +so be sure to specify them in the B statement if you need them: + + use Pod::Find qw(pod_find); + +=cut + +use strict; +#use diagnostics; +use Exporter; +use File::Spec; +use File::Find; +use Cwd; + +use vars qw(@ISA @EXPORT_OK $VERSION); +@ISA = qw(Exporter); +@EXPORT_OK = qw(&pod_find &simplify_name &pod_where &contains_pod); + +# package global variables +my $SIMPLIFY_RX; + +=head2 C + +The function B searches for POD documents in a given set of +files and/or directories. It returns a hash with the file names as keys +and the POD name as value. The POD name is derived from the file name +and its position in the directory tree. E.g. when searching in F<$HOME/perl5lib>, the file F<$HOME/perl5lib/MyModule.pm> would get the POD name I, @@ -51,73 +78,39 @@ A warning is printed if more than one POD file with the same POD name is found, e.g. F in different directories. This usually indicates duplicate occurrences of modules in the I<@INC> search path. -The function B is equivalent to B, but also -strips Perl-like extensions (.pm, .pl, .pod) and extensions like -F<.bat>, F<.cmd> on Win32 and OS/2, respectively. - -Note that neither B nor B are exported by -default so be sure to specify them in the B statement if you need -them: - - use Pod::Find qw(pod_find simplify_name); - -=head1 OPTIONS - -The first argument for B may be a hash reference with options. -The rest are either directories that are searched recursively or files. -The POD names of files are the plain basenames with any Perl-like extension -(.pm, .pl, .pod) stripped. +B The first argument for B may be a hash reference +with options. The rest are either directories that are searched +recursively or files. The POD names of files are the plain basenames +with any Perl-like extension (.pm, .pl, .pod) stripped. =over 4 -=item B<-verbose> +=item C<-verbose =E 1> Print progress information while scanning. -=item B<-perl> +=item C<-perl =E 1> Apply Perl-specific heuristics to find the correct PODs. This includes stripping Perl-like extensions, omitting subdirectories that are numeric but do I match the current Perl interpreter's version id, suppressing F as a module hierarchy name etc. -=item B<-script> +=item C<-script =E 1> Search for PODs in the current Perl interpreter's installation B. This is taken from the local L module. -=item B<-inc> +=item C<-inc =E 1> Search for PODs in the current Perl interpreter's I<@INC> paths. This -automatically considers paths specified in the C environment. +automatically considers paths specified in the C environment +as this is prepended to I<@INC> by the Perl interpreter itself. =back -=head1 AUTHOR - -Marek Rouchal Emarek@saftsack.fs.uni-bayreuth.deE, -heavily borrowing code from Nick Ing-Simmons' PodToHtml. - -=head1 SEE ALSO - -L, L - =cut -use strict; -#use diagnostics; -use Exporter; -use File::Spec; -use File::Find; -use Cwd; - -use vars qw(@ISA @EXPORT_OK $VERSION); -@ISA = qw(Exporter); -@EXPORT_OK = qw(&pod_find &simplify_name); - -# package global variables -my $SIMPLIFY_RX; - # return a hash of the POD files found # first argument may be a hashref (options), # rest is a list of directories to search recursively @@ -222,27 +215,14 @@ sub _check_and_extract_name { # check extension or executable flag # this involves testing the .bat extension on Win32! - unless($file =~ /\.(pod|pm|plx?)\z/i || (-f $file && -x _ && -T _)) { - return undef; + unless(-f $file && -T _ && ($file =~ /\.(pod|pm|plx?)\z/i || -x _ )) { + return undef; } - # check for one line of POD - unless(open(POD,"<$file")) { - warn "Error: $file is unreadable: $!\n"; - return undef; - } - local $/ = undef; - my $pod = ; - close(POD); - unless($pod =~ /\n=(head\d|pod|over|item)\b/) { - warn "No POD in $file, skipping.\n" - if($verbose); - return; - } - undef $pod; + return undef unless contains_pod($file,$verbose); # strip non-significant path components - # _TODO_ what happens on e.g. Win32? + # TODO what happens on e.g. Win32? my $name = $file; if(defined $root_rx) { $name =~ s!$root_rx!!s; @@ -256,6 +236,14 @@ sub _check_and_extract_name { $name; } +=head2 C + +The function B is equivalent to B, but also +strips Perl-like extensions (.pm, .pl, .pod) and extensions like +F<.bat>, F<.cmd> on Win32 and OS/2, respectively. + +=cut + # basic simplification of the POD name: # basename & strip extension sub simplify_name { @@ -274,5 +262,180 @@ sub _simplify { $_[0] =~ s/\.(bat|exe|cmd)\z//i if($^O =~ /win|os2/i); } +# contribution from Tim Jenness + +=head2 C + +Returns the location of a pod document given a search directory +and a module (e.g. C) or script (e.g. C) name. + +Options: + +=over 4 + +=item C<-inc =E 1> + +Search @INC for the pod and also the C defined in the +L module. + +=item C<-dirs =E [ $dir1, $dir2, ... ]> + +Reference to an array of search directories. These are searched in order +before looking in C<@INC> (if B<-inc>). Current directory is used if +none are specified. + +=item C<-verbose =E 1> + +List directories as they are searched + +=back + +Returns the full path of the first occurence to the file. +Package names (eg 'A::B') are automatically converted to directory +names in the selected directory. (eg on unix 'A::B' is converted to +'A/B'). Additionally, '.pm', '.pl' and '.pod' are appended to the +search automatically if required. + +A subdirectory F is also checked if it exists in any of the given +search directories. This ensures that e.g. L is +found. + +It is assumed that if a module name is supplied, that that name +matches the file name. Pods are not opened to check for the 'NAME' +entry. + +A check is made to make sure that the file that is found does +contain some pod documentation. + +=cut + +sub pod_where { + + # default options + my %options = ( + '-inc' => 0, + '-verbose' => 0, + '-dirs' => [ '.' ], + ); + + # Check for an options hash as first argument + if (defined $_[0] && ref($_[0]) eq 'HASH') { + my $opt = shift; + + # Merge default options with supplied options + %options = (%options, %$opt); + } + + # Check usage + carp 'Usage: pod_where({options}, $pod)' unless (scalar(@_)); + + # Read argument + my $pod = shift; + + # Split on :: and then join the name together using File::Spec + my @parts = split (/::/, $pod); + + # Get full directory list + my @search_dirs = @{ $options{'-dirs'} }; + + if ($options{'-inc'}) { + + require Config; + + # Add @INC + push (@search_dirs, @INC) if $options{'-inc'}; + + # Add location of pod documentation for perl man pages (eg perlfunc) + # This is a pod directory in the private install tree + #my $perlpoddir = File::Spec->catdir($Config::Config{'installprivlib'}, + # 'pod'); + #push (@search_dirs, $perlpoddir) + # if -d $perlpoddir; + + # Add location of binaries such as pod2text + push (@search_dirs, $Config::Config{'scriptdir'}) + if -d $Config::Config{'scriptdir'}; + } + + # Loop over directories + Dir: foreach my $dir ( @search_dirs ) { + + # Don't bother if cant find the directory + if (-d $dir) { + warn "Looking in directory $dir\n" + if $options{'-verbose'}; + + # Now concatenate this directory with the pod we are searching for + my $fullname = File::Spec->catfile($dir, @parts); + warn "Filename is now $fullname\n" + if $options{'-verbose'}; + + # Loop over possible extensions + foreach my $ext ('', '.pod', '.pm', '.pl') { + my $fullext = $fullname . $ext; + if (-f $fullext && + contains_pod($fullext, $options{'-verbose'}) ) { + warn "FOUND: $fullext\n" if $options{'-verbose'}; + return $fullext; + } + } + } else { + warn "Directory $dir does not exist\n" + if $options{'-verbose'}; + next Dir; + } + if(-d File::Spec->catdir($dir,'pod')) { + $dir = File::Spec->catdir($dir,'pod'); + redo Dir; + } + } + # No match; + return undef; +} + +=head2 C + +Returns true if the supplied filename (not POD module) contains some pod +information. + +=cut + +sub contains_pod { + my $file = shift; + my $verbose = 0; + $verbose = shift if @_; + + # check for one line of POD + unless(open(POD,"<$file")) { + warn "Error: $file is unreadable: $!\n"; + return undef; + } + + local $/ = undef; + my $pod = ; + close(POD) || die "Error closing $file: $!\n"; + unless($pod =~ /\n=(head\d|pod|over|item)\b/s) { + warn "No POD in $file, skipping.\n" + if($verbose); + return 0; + } + + return 1; +} + +=head1 AUTHOR + +Marek Rouchal Emarek@saftsack.fs.uni-bayreuth.deE, +heavily borrowing code from Nick Ing-Simmons' PodToHtml. + +Tim Jenness Et.jenness@jach.hawaii.eduE provided +C and C. + +=head1 SEE ALSO + +L, L, L + +=cut + 1; diff --git a/lib/Pod/InputObjects.pm b/lib/Pod/InputObjects.pm index 6bc329b..9c89413 100644 --- a/lib/Pod/InputObjects.pm +++ b/lib/Pod/InputObjects.pm @@ -11,7 +11,7 @@ package Pod::InputObjects; use vars qw($VERSION); -$VERSION = 1.12; ## Current version of this package +$VERSION = 1.13; ## Current version of this package require 5.005; ## requires this Perl version or later ############################################################################# @@ -42,7 +42,7 @@ are defined: =begin __PRIVATE__ -=item B +=item package B An object corresponding to a source of POD input text. It is mostly a wrapper around a filehandle or C-type object (or anything @@ -51,23 +51,23 @@ additional information relevant to the parsing of PODs. =end __PRIVATE__ -=item B +=item package B An object corresponding to a paragraph of POD input text. It may be a plain paragraph, a verbatim paragraph, or a command paragraph (see L). -=item B +=item package B An object corresponding to an interior sequence command from the POD input text (see L). -=item B +=item package B An object corresponding to a tree of parsed POD text. Each "node" in a parse-tree (or I) is either a text-string or a reference to a B object. The nodes appear in the parse-tree -in they order in which they were parsed from left-to-right. +in the order in which they were parsed from left-to-right. =back @@ -232,7 +232,7 @@ It has the following methods/attributes: ##--------------------------------------------------------------------------- -=head2 B +=head2 Pod::Paragraph-EB my $pod_para1 = Pod::Paragraph->new(-text => $text); my $pod_para2 = Pod::Paragraph->new(-name => $cmd, @@ -284,7 +284,7 @@ sub new { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_para-EB my $para_cmd = $pod_para->cmd_name(); @@ -303,7 +303,7 @@ sub cmd_name { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_para-EB my $para_text = $pod_para->text(); @@ -318,7 +318,7 @@ sub text { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_para-EB my $raw_pod_para = $pod_para->raw_text(); @@ -335,7 +335,7 @@ sub raw_text { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_para-EB my $prefix = $pod_para->cmd_prefix(); @@ -351,7 +351,7 @@ sub cmd_prefix { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_para-EB my $separator = $pod_para->cmd_separator(); @@ -367,7 +367,7 @@ sub cmd_separator { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_para-EB my $ptree = $pod_parser->parse_text( $pod_para->text() ); $pod_para->parse_tree( $ptree ); @@ -387,13 +387,13 @@ sub parse_tree { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_para-EB my ($filename, $line_number) = $pod_para->file_line(); my $position = $pod_para->file_line(); Returns the current filename and line number for the paragraph -object. If called in a list context, it returns a list of two +object. If called in an array context, it returns a list of two elements: first the filename, then the line number. If called in a scalar context, it returns a string containing the filename, followed by a colon (':'), followed by the line number. @@ -423,7 +423,7 @@ It has the following methods/attributes: ##--------------------------------------------------------------------------- -=head2 B +=head2 Pod::InteriorSequence-EB my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd -ldelim => $delimiter); @@ -497,7 +497,7 @@ sub new { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_seq-EB my $seq_cmd = $pod_seq->cmd_name(); @@ -546,7 +546,7 @@ sub _unset_child2parent_links { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_seq-EB $pod_seq->prepend($text); $pod_seq1->prepend($pod_seq2); @@ -565,7 +565,7 @@ sub prepend { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_seq-EB $pod_seq->append($text); $pod_seq1->append($pod_seq2); @@ -584,7 +584,7 @@ sub append { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_seq-EB $outer_seq = $pod_seq->nested || print "not nested"; @@ -602,7 +602,7 @@ sub nested { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_seq-EB my $seq_raw_text = $pod_seq->raw_text(); @@ -623,7 +623,7 @@ sub raw_text { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_seq-EB my $ldelim = $pod_seq->left_delimiter(); @@ -642,7 +642,7 @@ sub left_delimiter { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_seq-EB The rightmost delimiter beginning the argument text to the interior sequence (should be ">"). @@ -659,7 +659,7 @@ sub right_delimiter { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_seq-EB my $ptree = $pod_parser->parse_text($paragraph_text); $pod_seq->parse_tree( $ptree ); @@ -680,13 +680,13 @@ sub parse_tree { ##--------------------------------------------------------------------------- -=head2 B +=head2 $pod_seq-EB my ($filename, $line_number) = $pod_seq->file_line(); my $position = $pod_seq->file_line(); Returns the current filename and line number for the interior sequence -object. If called in a list context, it returns a list of two +object. If called in an array context, it returns a list of two elements: first the filename, then the line number. If called in a scalar context, it returns a string containing the filename, followed by a colon (':'), followed by the line number. @@ -701,7 +701,7 @@ sub file_line { ##--------------------------------------------------------------------------- -=head2 B +=head2 Pod::InteriorSequence::B This method performs any necessary cleanup for the interior-sequence. If you override this method then it is B that you invoke @@ -738,7 +738,7 @@ itself contain a parse-tree (since interior sequences may be nested). ##--------------------------------------------------------------------------- -=head2 B +=head2 Pod::ParseTree-EB my $ptree1 = Pod::ParseTree->new; my $ptree2 = new Pod::ParseTree; @@ -766,7 +766,7 @@ sub new { ##--------------------------------------------------------------------------- -=head2 B +=head2 $ptree-EB my $top_node = $ptree->top(); $ptree->top( $top_node ); @@ -794,7 +794,7 @@ sub top { ##--------------------------------------------------------------------------- -=head2 B +=head2 $ptree-EB This method gets/sets the children of the top node in the parse-tree. If no arguments are given, it returns the list (array) of children @@ -814,7 +814,7 @@ sub children { ##--------------------------------------------------------------------------- -=head2 B +=head2 $ptree-EB This method prepends the given text or parse-tree to the current parse-tree. If the first item on the parse-tree is text and the argument is also text, @@ -842,7 +842,7 @@ sub prepend { ##--------------------------------------------------------------------------- -=head2 B +=head2 $ptree-EB This method appends the given text or parse-tree to the current parse-tree. If the last item on the parse-tree is text and the argument is also text, @@ -866,7 +866,7 @@ sub append { } } -=head2 B +=head2 $ptree-EB my $ptree_raw_text = $ptree->raw_text(); @@ -902,7 +902,7 @@ sub _set_child2parent_links { ## nothing to do, Pod::ParseTrees cant have parent pointers } -=head2 B +=head2 Pod::ParseTree::B This method performs any necessary cleanup for the parse-tree. If you override this method then it is B diff --git a/lib/Pod/ParseUtils.pm b/lib/Pod/ParseUtils.pm index 2cb8cdc..6703a7f 100644 --- a/lib/Pod/ParseUtils.pm +++ b/lib/Pod/ParseUtils.pm @@ -10,7 +10,7 @@ package Pod::ParseUtils; use vars qw($VERSION); -$VERSION = 0.2; ## Current version of this package +$VERSION = 0.22; ## Current version of this package require 5.005; ## requires this Perl version or later =head1 NAME @@ -49,7 +49,7 @@ The following methods are available: =over 4 -=item new() +=item Pod::List-Enew() Create a new list object. Properties may be specified through a hash reference like this: @@ -79,7 +79,7 @@ sub initialize { $self->{-type} ||= ''; } -=item file() +=item $list-Efile() Without argument, retrieves the file name the list is in. This must have been set before by either specifying B<-file> in the B @@ -92,7 +92,7 @@ sub file { return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file}; } -=item start() +=item $list-Estart() Without argument, retrieves the line number where the list started. This must have been set before by either specifying B<-start> in the @@ -106,7 +106,7 @@ sub start { return (@_ > 1) ? ($_[0]->{-start} = $_[1]) : $_[0]->{-start}; } -=item indent() +=item $list-Eindent() Without argument, retrieves the indent level of the list as specified in C<=over n>. This must have been set before by either specifying @@ -120,7 +120,7 @@ sub indent { return (@_ > 1) ? ($_[0]->{-indent} = $_[1]) : $_[0]->{-indent}; } -=item type() +=item $list-Etype() Without argument, retrieves the list type, which can be an arbitrary value, e.g. C
    , C
      , ... when thinking the HTML way. @@ -135,7 +135,7 @@ sub type { return (@_ > 1) ? ($_[0]->{-type} = $_[1]) : $_[0]->{-type}; } -=item rx() +=item $list-Erx() Without argument, retrieves a regular expression for simplifying the individual item strings once the list type has been determined. Usage: @@ -152,7 +152,7 @@ sub rx { return (@_ > 1) ? ($_[0]->{-rx} = $_[1]) : $_[0]->{-rx}; } -=item item() +=item $list-Eitem() Without argument, retrieves the array of the items in this list. The items may be represented by any scalar. @@ -172,7 +172,7 @@ sub item { } } -=item parent() +=item $list-Eparent() Without argument, retrieves information about the parent holding this list, which is represented as an arbitrary scalar. @@ -188,7 +188,7 @@ sub parent { return (@_ > 1) ? ($_[0]->{-parent} = $_[1]) : $_[0]->{-parent}; } -=item tag() +=item $list-Etag() Without argument, retrieves information about the list tag, which can be any scalar. @@ -227,7 +227,7 @@ used to construct hyperlinks. =over 4 -=item new() +=item Pod::Hyperlink-Enew() The B method can either be passed a set of key/value pairs or a single scalar value, namely the contents of a C...E> sequence. An object @@ -269,10 +269,14 @@ sub initialize { $self->{_warnings} = []; } -=item parse($string) +=item $link-Eparse($string) This method can be used to (re)parse a (new) hyperlink, i.e. the contents of a C...E> sequence. The result is stored in the current object. +Warnings are stored in the B property. +E.g. sections like Copen(2)E> are deprected, as they do not point +to Perl documents. CDBI::foo(3p)E> is wrong as well, the manpage +section can simply be dropped. =cut @@ -280,7 +284,7 @@ sub parse { my $self = shift; local($_) = $_[0]; # syntax check the link and extract destination - my ($alttext,$page,$node,$type) = ('','','',''); + my ($alttext,$page,$node,$type) = (undef,'','',''); $self->{_warnings} = []; @@ -308,25 +312,24 @@ sub parse { # problem: a lot of people use (), or (1) or the like to indicate # man page sections. But this collides with L that is supposed # to point to an internal funtion... - # I would like the following better, here and below: - #if(m!^(\w+(?:::\w+)*)$!) { - my $page_rx = '[\w.]+(?:::[\w.]+)*'; + my $page_rx = '[\w.]+(?:::[\w.]+)*(?:[(](?:\d\w*|)[)]|)'; + # page name only if(m!^($page_rx)$!o) { $page = $1; $type = 'page'; } # alttext, page and "section" - elsif(m!^(.+?)\s*[|]\s*($page_rx)\s*/\s*"(.+)"$!o) { + elsif(m!^(.*?)\s*[|]\s*($page_rx)\s*/\s*"(.+)"$!o) { ($alttext, $page, $node) = ($1, $2, $3); $type = 'section'; } # alttext and page - elsif(m!^(.+?)\s*[|]\s*($page_rx)$!o) { + elsif(m!^(.*?)\s*[|]\s*($page_rx)$!o) { ($alttext, $page) = ($1, $2); $type = 'page'; } # alttext and "section" - elsif(m!^(.+?)\s*[|]\s*(?:/\s*|)"(.+)"$!) { + elsif(m!^(.*?)\s*[|]\s*(?:/\s*|)"(.+)"$!) { ($alttext, $node) = ($1,$2); $type = 'section'; } @@ -356,16 +359,16 @@ sub parse { $type = 'hyperlink'; } # alttext, page and item - elsif(m!^(.+?)\s*[|]\s*($page_rx)\s*/\s*(.+)$!o) { + elsif(m!^(.*?)\s*[|]\s*($page_rx)\s*/\s*(.+)$!o) { ($alttext, $page, $node) = ($1, $2, $3); $type = 'item'; } # alttext and item - elsif(m!^(.+?)\s*[|]\s*/(.+)$!) { + elsif(m!^(.*?)\s*[|]\s*/(.+)$!) { ($alttext, $node) = ($1,$2); } # nonstandard: alttext and hyperlink - elsif(m!^(.+?)\s*[|]\s*((?:http|ftp|mailto|news):.+)$!) { + elsif(m!^(.*?)\s*[|]\s*((?:http|ftp|mailto|news):.+)$!) { ($alttext, $node) = ($1,$2); $type = 'hyperlink'; } @@ -377,9 +380,19 @@ sub parse { # collapse whitespace in nodes $node =~ s/\s+/ /gs; - #if($page =~ /[(]\w*[)]$/) { - # $self->warning("section in '$page' deprecated"); - #} + # empty alternative text expands to node name + if(defined $alttext) { + if(!length($alttext)) { + $alttext = $node | $page; + } + } + else { + $alttext = ''; + } + + if($page =~ /[(]\w*[)]$/) { + $self->warning("(section) in '$page' deprecated"); + } if($node =~ m:[|/]:) { $self->warning("node '$node' contains non-escaped | or /"); } @@ -435,7 +448,7 @@ sub _construct_text { } } -=item markup($string) +=item $link-Emarkup($string) Set/retrieve the textual value of the link. This string contains special markers CE> and CE> that should be expanded by the @@ -450,7 +463,7 @@ sub markup { return (@_ > 1) ? ($_[0]->{_markup} = $_[1]) : $_[0]->{_markup}; } -=item text() +=item $link-Etext() This method returns the textual representation of the hyperlink as above, but without markers (read only). Depending on the link type this is one of @@ -469,7 +482,7 @@ sub text { $_[0]->{_text}; } -=item warning() +=item $link-Ewarning() After parsing, this method returns any warnings encountered during the parsing process. @@ -486,7 +499,9 @@ sub warning { return @{$self->{_warnings}}; } -=item line(), file() +=item $link-Efile() + +=item $link-Eline() Just simple slots for storing information about the line and the file the link was encountered in. Has to be filled in manually. @@ -503,7 +518,7 @@ sub file { return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file}; } -=item page() +=item $link-Epage() This method sets or returns the POD page this link points to. @@ -518,7 +533,7 @@ sub page { $_[0]->{-page}; } -=item node() +=item $link-Enode() As above, but the destination node text of the link. @@ -533,7 +548,7 @@ sub node { $_[0]->{-node}; } -=item alttext() +=item $link-Ealttext() Sets or returns an alternative text specified in the link. @@ -548,7 +563,7 @@ sub alttext { $_[0]->{-alttext}; } -=item type() +=item $link-Etype() The node type, either C
      or C. As an unofficial type, there is also C, derived from e.g. Chttp://perl.comE> @@ -560,7 +575,7 @@ sub type { return (@_ > 1) ? ($_[0]->{-type} = $_[1]) : $_[0]->{-type}; } -=item link() +=item $link-Elink() Returns the link as contents of CE>. Reciprocal to B. @@ -620,7 +635,7 @@ The following methods are available: =over 4 -=item new() +=item Pod::Cache-Enew() Create a new cache object. This object can hold an arbitrary number of POD documents of class Pod::Cache::Item. @@ -635,7 +650,7 @@ sub new { return $self; } -=item item() +=item $cache-Eitem() Add a new item to the cache. Without arguments, this method returns a list of all cache elements. @@ -654,7 +669,7 @@ sub item { } } -=item find_page($name) +=item $cache-Efind_page($name) Look for a POD document named C<$name> in the cache. Returns the reference to the corresponding Pod::Cache::Item object or undef if @@ -686,7 +701,7 @@ The following methods are available: =over 4 -=item new() +=item Pod::Cache::Item-Enew() Create a new object. @@ -707,7 +722,7 @@ sub initialize { $self->{-nodes} = [] unless(defined $self->{-nodes}); } -=item page() +=item $cacheitem-Epage() Set/retrieve the POD document name (e.g. "Pod::Parser"). @@ -718,7 +733,7 @@ sub page { return (@_ > 1) ? ($_[0]->{-page} = $_[1]) : $_[0]->{-page}; } -=item description() +=item $cacheitem-Edescription() Set/retrieve the POD short description as found in the C<=head1 NAME> section. @@ -730,7 +745,7 @@ sub description { return (@_ > 1) ? ($_[0]->{-description} = $_[1]) : $_[0]->{-description}; } -=item path() +=item $cacheitem-Epath() Set/retrieve the POD file storage path. @@ -741,7 +756,7 @@ sub path { return (@_ > 1) ? ($_[0]->{-path} = $_[1]) : $_[0]->{-path}; } -=item file() +=item $cacheitem-Efile() Set/retrieve the POD file name. @@ -752,7 +767,7 @@ sub file { return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file}; } -=item nodes() +=item $cacheitem-Enodes() Add a node (or a list of nodes) to the document's node list. Note that the order is kept, i.e. start with the first node and end with the last. @@ -775,14 +790,12 @@ sub nodes { } } -=item find_node($name) +=item $cacheitem-Efind_node($name) 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. -=back - =cut sub find_node { @@ -798,7 +811,7 @@ sub find_node { undef; } -=item idx() +=item $cacheitem-Eidx() Add an index entry (or a list of them) to the document's index list. Note that the order is kept, i.e. start with the first node and end with the last. @@ -807,6 +820,8 @@ same order the entries have been added. An index entry can be any scalar, but usually is a pair of string and unique id. +=back + =cut # The POD index entries diff --git a/lib/Pod/Parser.pm b/lib/Pod/Parser.pm index 48fc198..99615bc 100644 --- a/lib/Pod/Parser.pm +++ b/lib/Pod/Parser.pm @@ -205,7 +205,6 @@ use strict; use Pod::InputObjects; use Carp; use Exporter; -require VMS::Filespec if $^O eq 'VMS'; BEGIN { if ($] < 5.6) { require Symbol; @@ -848,7 +847,6 @@ sub parse_text { my $errorsub = (@seq_stack > 1) ? $self->errorsub() : undef; while (@seq_stack > 1) { ($cmd, $file, $line) = ($seq->name, $seq->file_line); - $file = VMS::Filespec::unixify($file) if $^O eq 'VMS'; $ldelim = $seq->ldelim; ($rdelim = $ldelim) =~ tr//; $rdelim =~ s/^(\S+)(\s*)$/$2$1/; @@ -1081,10 +1079,9 @@ sub parse_from_filehandle { && (length $paragraph)); ## Issue a warning about any non-empty blank lines - if (length($1) > 1 and $myOpts{'-warnings'} and ! $myData{_CUTTING}) { + if (length($1) > 0 and $myOpts{'-warnings'} and ! $myData{_CUTTING}) { my $errorsub = $self->errorsub(); my $file = $self->input_file(); - $file = VMS::Filespec::unixify($file) if $^O eq 'VMS'; my $errmsg = "*** WARNING: line containing nothing but whitespace". " in paragraph at line $nlines in file $file\n"; (ref $errorsub) and &{$errorsub}($errmsg) diff --git a/lib/Pod/Select.pm b/lib/Pod/Select.pm index 5dd1595..d86d823 100644 --- a/lib/Pod/Select.pm +++ b/lib/Pod/Select.pm @@ -10,7 +10,7 @@ package Pod::Select; use vars qw($VERSION); -$VERSION = 1.12; ## Current version of this package +$VERSION = 1.13; ## Current version of this package require 5.005; ## requires this Perl version or later ############################################################################# @@ -92,7 +92,7 @@ The formal syntax of a section specification is: =over 4 -=item +=item * I/I/... @@ -160,7 +160,7 @@ The formal syntax of a range specification is: =over 4 -=item +=item * /I/[../I/] diff --git a/lib/Pod/Usage.pm b/lib/Pod/Usage.pm index 571588e..56e91fc 100644 --- a/lib/Pod/Usage.pm +++ b/lib/Pod/Usage.pm @@ -10,7 +10,7 @@ package Pod::Usage; use vars qw($VERSION); -$VERSION = 1.12; ## Current version of this package +$VERSION = 1.13; ## Current version of this package require 5.005; ## requires this Perl version or later =head1 NAME @@ -46,7 +46,7 @@ B should be given either a single argument, or a list of arguments corresponding to an associative array (a "hash"). When a single argument is given, it should correspond to exactly one of the following: -=over +=over 4 =item * @@ -68,7 +68,7 @@ assumed to be a hash. If a hash is supplied (either as a reference or as a list) it should contain one or more elements with the following keys: -=over +=over 4 =item C<-message> @@ -129,7 +129,7 @@ Unless they are explicitly specified, the default values for the exit status, verbose level, and output stream to use are determined as follows: -=over +=over 4 =item * @@ -159,7 +159,7 @@ Although the above may seem a bit confusing at first, it generally does "the right thing" in most situations. This determination of the default values to use is based upon the following typical Unix conventions: -=over +=over 4 =item * @@ -211,7 +211,7 @@ convenient to use as an innocent looking error message handling function: ## Check for too many filenames pod2usage("$0: Too many files given.\n") if (@ARGV > 1); -Some users however may feel that the above "economy of expression" is +Some user's however may feel that the above "economy of expression" is not particularly readable nor consistent and may instead choose to do something more like the following: diff --git a/pod/pod2usage.PL b/pod/pod2usage.PL index e0f70b2..1c1296a 100644 --- a/pod/pod2usage.PL +++ b/pod/pod2usage.PL @@ -39,7 +39,7 @@ print OUT <<'!NO!SUBS!'; ############################################################################# # pod2usage -- command to print usage messages from embedded pod docs # -# Copyright (c) 1996-1999 by Bradford Appleton. All rights reserved. +# Copyright (c) 1996-2000 by Bradford Appleton. All rights reserved. # This file is part of "PodParser". PodParser is free software; # you can redistribute it and/or modify it under the same terms # as Perl itself. diff --git a/pod/podchecker.PL b/pod/podchecker.PL index a7f9643..20d5e94 100644 --- a/pod/podchecker.PL +++ b/pod/podchecker.PL @@ -39,7 +39,7 @@ print OUT <<'!NO!SUBS!'; ############################################################################# # podchecker -- command to invoke the podchecker function in Pod::Checker # -# Copyright (c) 1998-1999 by Bradford Appleton. All rights reserved. +# Copyright (c) 1998-2000 by Bradford Appleton. All rights reserved. # This file is part of "PodParser". PodParser is free software; # you can redistribute it and/or modify it under the same terms # as Perl itself. @@ -70,7 +70,9 @@ Print the manual page and exit. =item B<-warnings> B<-nowarnings> -Turn on/off printing of warnings. +Turn on/off printing of warnings. Repeating B<-warnings> increases the +warning level, i.e. more warnings are printed. Currently increasing to +level two causes flagging of unescaped "E,E" characters. =item I @@ -85,6 +87,8 @@ syntax errors in the POD documentation and will print any errors it find to STDERR. At the end, it will print a status message indicating the number of errors found. +Directories are ignored, an appropriate warning message is printed. + B invokes the B function exported by B Please see L for more details. @@ -124,24 +128,34 @@ use Pod::Usage; use Getopt::Long; ## Define options -my %options = ( - "help" => 0, - "man" => 0, - "warnings" => 1, -); +my %options; ## Parse options -GetOptions(\%options, "help", "man", "warnings!") || pod2usage(2); +GetOptions(\%options, qw(help man warnings+ nowarnings)) || pod2usage(2); pod2usage(1) if ($options{help}); pod2usage(-verbose => 2) if ($options{man}); +if($options{nowarnings}) { + $options{warnings} = 0; +} +elsif(!defined $options{warnings}) { + $options{warnings} = 1; # default is warnings on +} + ## Dont default to STDIN if connected to a terminal pod2usage(2) if ((@ARGV == 0) && (-t STDIN)); ## Invoke podchecker() my $status = 0; -@ARGV = ("<&STDIN") unless(@ARGV); +@ARGV = qw(-) unless(@ARGV); for (@ARGV) { + if($_ eq '-') { + $_ = "<&STDIN"; + } + elsif(-d) { + warn "podchecker: Warning: Ignoring directory '$_'\n"; + next; + } my $s = podchecker($_, undef, '-warnings' => $options{warnings}); if($s > 0) { # errors occurred diff --git a/pod/podselect.PL b/pod/podselect.PL index f2ba80a..b6b8c9b 100644 --- a/pod/podselect.PL +++ b/pod/podselect.PL @@ -39,7 +39,7 @@ print OUT <<'!NO!SUBS!'; ############################################################################# # podselect -- command to invoke the podselect function in Pod::Select # -# Copyright (c) 1996-1999 by Bradford Appleton. All rights reserved. +# Copyright (c) 1996-2000 by Bradford Appleton. All rights reserved. # This file is part of "PodParser". PodParser is free software; # you can redistribute it and/or modify it under the same terms # as Perl itself. diff --git a/t/pod/emptycmd.t b/t/pod/emptycmd.t index d348a9d..59e395e 100755 --- a/t/pod/emptycmd.t +++ b/t/pod/emptycmd.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/for.t b/t/pod/for.t index b8a6ec5..44af44f 100755 --- a/t/pod/for.t +++ b/t/pod/for.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/headings.t b/t/pod/headings.t index fc7b4b2..78608d0 100755 --- a/t/pod/headings.t +++ b/t/pod/headings.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/include.t b/t/pod/include.t index 6d0b7e3..4e73b78 100755 --- a/t/pod/include.t +++ b/t/pod/include.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/included.t b/t/pod/included.t index 0e31a09..4f171c4 100755 --- a/t/pod/included.t +++ b/t/pod/included.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/lref.t b/t/pod/lref.t index e367d6d..02e2c9e 100755 --- a/t/pod/lref.t +++ b/t/pod/lref.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/multiline_items.t b/t/pod/multiline_items.t index 37e8d53..0fe410a 100755 --- a/t/pod/multiline_items.t +++ b/t/pod/multiline_items.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/nested_items.t b/t/pod/nested_items.t index 9c09801..c8e9b22 100755 --- a/t/pod/nested_items.t +++ b/t/pod/nested_items.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/nested_seqs.t b/t/pod/nested_seqs.t index 6a5405b..8559f1f 100755 --- a/t/pod/nested_seqs.t +++ b/t/pod/nested_seqs.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/oneline_cmds.t b/t/pod/oneline_cmds.t index 3081ef4..28bd1d0 100755 --- a/t/pod/oneline_cmds.t +++ b/t/pod/oneline_cmds.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/pod2usage.t b/t/pod/pod2usage.t index bceeeef..cf2c31b 100755 --- a/t/pod/pod2usage.t +++ b/t/pod/pod2usage.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/poderrs.t b/t/pod/poderrs.t index ec632c2..8db7d43 100755 --- a/t/pod/poderrs.t +++ b/t/pod/poderrs.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testpchk.pl"; import TestPodChecker; } @@ -59,7 +59,7 @@ The above blank line contains tabs and spaces only =over 4 -=item oops +=item aaps =head2 end without begin @@ -75,6 +75,20 @@ The above blank line contains tabs and spaces only =end +second one results in end w/o begin + +=head2 begin w/o formatter + +=begin + +=end + +=head2 for w/o formatter + +=for + +something... + =head2 Nested sequences of the same type C>> @@ -84,6 +98,9 @@ C>> E E> E> +E<0x100> +E<07777> +E<300> =head2 Unresolved internal links @@ -96,12 +113,15 @@ L L L<> +L< aha> +L L<"Warnings"> this one is ok +L ok too, this POD has an X of the same name =head2 Warnings L -L< some text|page/"section" > +L should give warnings as hell =over 4 @@ -109,17 +129,70 @@ L< some text|page/"section" > =back 200 +the 200 is evil + =begin html What? =end xml +Xsee these unescaped < and > in the text? + +=head2 Misc + +Z should be empty + +X<> should not be empty + +=over four + +This paragrapgh is misplaced - it ought to be an item. + +=item four should be numeric! + +=item + +=item blah + +=item previous is all empty!!! + +=back + +All empty over/back: + +=over 4 + +=back + +item w/o name + +=cut + +=pod bla + +bla is evil + +=cut blub + +blub is evil + +=head2 reoccurence + =over 4 +=item Misc + +we already have a head Misc + =back -see these unescaped < and > in the text? +=head2 some heading + +=head2 another one + +previous section is empty! =cut + diff --git a/t/pod/poderrs.xr b/t/pod/poderrs.xr index b8e5e86..015f898 100644 --- a/t/pod/poderrs.xr +++ b/t/pod/poderrs.xr @@ -1,33 +1,48 @@ -*** ERROR: Unknown command 'unknown1' at line 25 in file pod/poderrs.t -*** ERROR: Unknown interior-sequence 'Q' at line 29 in file pod/poderrs.t -*** ERROR: Unknown interior-sequence 'A' at line 30 in file pod/poderrs.t -*** ERROR: Unknown interior-sequence 'Y' at line 31 in file pod/poderrs.t -*** ERROR: Unknown interior-sequence 'V' at line 31 in file pod/poderrs.t -*** ERROR: unterminated B<...> at line 35 in file pod/poderrs.t -*** ERROR: unterminated I<...> at line 34 in file pod/poderrs.t -*** ERROR: unterminated C<...> at line 37 in file pod/poderrs.t -*** WARNING: line containing nothing but whitespace in paragraph at line 45 in file pod/poderrs.t -*** ERROR: =item without previous =over at line 52 in file pod/poderrs.t -*** ERROR: =back without previous =over at line 56 in file pod/poderrs.t -*** ERROR: =over on line 60 without closing =back (at head2) at line 64 in file pod/poderrs.t -*** ERROR: =end without =begin at line 66 in file pod/poderrs.t -*** ERROR: Nested =begin's (first at line 70:html) at line 72 in file pod/poderrs.t -*** ERROR: =end without =begin at line 76 in file pod/poderrs.t -*** ERROR: nested commands C<...C<...>...> at line 80 in file pod/poderrs.t -*** ERROR: garbled entity E at line 84 in file pod/poderrs.t -*** ERROR: garbled entity E> at line 85 in file pod/poderrs.t -*** ERROR: garbled entity E> at line 86 in file pod/poderrs.t -*** WARNING: collapsing newlines to blanks at line 96 in file pod/poderrs.t -*** ERROR: malformed link L<> : empty link at line 98 in file pod/poderrs.t -*** WARNING: ignoring leading whitespace in link at line 104 in file pod/poderrs.t -*** WARNING: ignoring trailing whitespace in link at line 104 in file pod/poderrs.t -*** ERROR: Spurious character(s) after =back at line 110 in file pod/poderrs.t -*** WARNING: No items in =over (at line 118) / =back list at line 120 in file pod/poderrs.t -*** WARNING: 2 unescaped <> in paragraph at line 122 in file pod/poderrs.t -*** ERROR: unresolved internal link 'begin or begin' at line 90 in file pod/poderrs.t -*** ERROR: unresolved internal link 'end with begin' at line 91 in file pod/poderrs.t -*** ERROR: unresolved internal link 'OoPs' at line 92 in file pod/poderrs.t -*** ERROR: unresolved internal link 'abc def' at line 96 in file pod/poderrs.t -*** ERROR: unresolved internal link 'passwd(5)' at line 103 in file pod/poderrs.t -*** WARNING: multiple occurence of link target 'oops' at line - in file pod/poderrs.t -pod/poderrs.t has 25 pod syntax errors. +*** ERROR: Unknown command 'unknown1' at line 25 in file t/pod/poderrs.t +*** ERROR: Unknown interior-sequence 'Q' at line 29 in file t/pod/poderrs.t +*** ERROR: Unknown interior-sequence 'A' at line 30 in file t/pod/poderrs.t +*** ERROR: Unknown interior-sequence 'Y' at line 31 in file t/pod/poderrs.t +*** ERROR: Unknown interior-sequence 'V' at line 31 in file t/pod/poderrs.t +*** ERROR: unterminated B<...> at line 35 in file t/pod/poderrs.t +*** ERROR: unterminated I<...> at line 34 in file t/pod/poderrs.t +*** ERROR: unterminated C<...> at line 37 in file t/pod/poderrs.t +*** WARNING: line containing nothing but whitespace in paragraph at line 45 in file t/pod/poderrs.t +*** ERROR: =item without previous =over at line 52 in file t/pod/poderrs.t +*** ERROR: =back without previous =over at line 56 in file t/pod/poderrs.t +*** ERROR: =over on line 60 without closing =back (at head2) at line 64 in file t/pod/poderrs.t +*** ERROR: =end without =begin at line 66 in file t/pod/poderrs.t +*** ERROR: Nested =begin's (first at line 70:html) at line 72 in file t/pod/poderrs.t +*** ERROR: =end without =begin at line 76 in file t/pod/poderrs.t +*** ERROR: No argument for =begin at line 82 in file t/pod/poderrs.t +*** ERROR: =for without formatter specification at line 88 in file t/pod/poderrs.t +*** ERROR: nested commands C<...C<...>...> at line 94 in file t/pod/poderrs.t +*** ERROR: garbled entity E at line 98 in file t/pod/poderrs.t +*** ERROR: garbled entity E> at line 99 in file t/pod/poderrs.t +*** ERROR: garbled entity E> at line 100 in file t/pod/poderrs.t +*** ERROR: Entity number out of range E<0x100> at line 101 in file t/pod/poderrs.t +*** ERROR: Entity number out of range E<07777> at line 102 in file t/pod/poderrs.t +*** ERROR: Entity number out of range E<300> at line 103 in file t/pod/poderrs.t +*** WARNING: collapsing newlines to blanks at line 113 in file t/pod/poderrs.t +*** ERROR: malformed link L<> : empty link at line 115 in file t/pod/poderrs.t +*** WARNING: ignoring leading whitespace in link at line 116 in file t/pod/poderrs.t +*** WARNING: ignoring trailing whitespace in link at line 117 in file t/pod/poderrs.t +*** WARNING: (section) in 'passwd(5)' deprecated at line 123 in file t/pod/poderrs.t +*** WARNING: node '$|' contains non-escaped | or / at line 124 in file t/pod/poderrs.t +*** WARNING: alternative text '$|' contains non-escaped | or / at line 124 in file t/pod/poderrs.t +*** ERROR: Spurious character(s) after =back at line 130 in file t/pod/poderrs.t +*** ERROR: Nonempty Z<> at line 144 in file t/pod/poderrs.t +*** ERROR: Empty X<> at line 146 in file t/pod/poderrs.t +*** WARNING: No numeric argument for =over at line 148 in file t/pod/poderrs.t +*** WARNING: preceding non-item paragraph(s) at line 152 in file t/pod/poderrs.t +*** WARNING: No argument for =item at line 154 in file t/pod/poderrs.t +*** WARNING: previous =item has no contents at line 156 in file t/pod/poderrs.t +*** WARNING: No items in =over (at line 164) / =back list at line 166 in file t/pod/poderrs.t +*** ERROR: Spurious text after =pod at line 172 in file t/pod/poderrs.t +*** ERROR: Spurious text after =cut at line 176 in file t/pod/poderrs.t +*** WARNING: empty section in previous paragraph at line 192 in file t/pod/poderrs.t +*** ERROR: unresolved internal link 'begin or begin' at line 107 in file t/pod/poderrs.t +*** ERROR: unresolved internal link 'end with begin' at line 108 in file t/pod/poderrs.t +*** ERROR: unresolved internal link 'OoPs' at line 109 in file t/pod/poderrs.t +*** ERROR: unresolved internal link 'abc def' at line 113 in file t/pod/poderrs.t +*** WARNING: multiple occurence of link target 'Misc' at line - in file t/pod/poderrs.t +t/pod/poderrs.t has 33 pod syntax errors. diff --git a/t/pod/podselect.t b/t/pod/podselect.t index 30eb30c..0004548 100755 --- a/t/pod/podselect.t +++ b/t/pod/podselect.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; } diff --git a/t/pod/special_seqs.t b/t/pod/special_seqs.t index b8af57e..1f229c2 100755 --- a/t/pod/special_seqs.t +++ b/t/pod/special_seqs.t @@ -1,7 +1,7 @@ -#!./perl BEGIN { - chdir 't' if -d 't'; - unshift @INC, './pod', '../lib'; + use File::Basename; + my $THISDIR = dirname $0; + unshift @INC, $THISDIR; require "testp2pt.pl"; import TestPodIncPlainText; }