Dear Marek,
People who download the Pod-Parser distribution (and see the ANNOUNCE file) and install it manually are probably a minority compared to people who installed it in an automated fashion. I included a first patch, which affects documents the deprecation in all modules included in Pod-Parser.
The second patch addresses the two use-case I filed above. The case where an empty string is passed is a case where the POD was not clear enough. The case where an arrayref is passed is a case where more thorough input checking needed to be done.
In the future I will certainly consider Pod-Simple. I need to read its documentation but it does not seem that there is a ready-made module in Pod-Simple that does what Pod::Select does. I suppose I will have to write and contribute such a module.
Thank you,
Florent
diff -rupN Pod-Parser-1.61/lib/Pod/Find.pm Pod-Parser-1.61-deprec/lib/Pod/Find.pm
--- Pod-Parser-1.61/lib/Pod/Find.pm 2013-06-01 23:13:52.000000000 +1000
+++ Pod-Parser-1.61-deprec/lib/Pod/Find.pm 2013-09-27 11:22:39.000000000 +1000
@@ -45,6 +45,10 @@ Pod::Find - find POD documents in direct
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
B<Pod::Find> 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<use> statement if you need them:
diff -rupN Pod-Parser-1.61/lib/Pod/InputObjects.pm Pod-Parser-1.61-deprec/lib/Pod/InputObjects.pm
--- Pod-Parser-1.61/lib/Pod/InputObjects.pm 2013-06-01 23:08:46.000000000 +1000
+++ Pod-Parser-1.61-deprec/lib/Pod/InputObjects.pm 2013-09-27 11:22:18.000000000 +1000
@@ -35,6 +35,10 @@ Nothing.
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
This module defines some basic input objects used by B<Pod::Parser> when
reading and parsing POD text from an input source. The following objects
are defined:
diff -rupN Pod-Parser-1.61/lib/Pod/Parser.pm Pod-Parser-1.61-deprec/lib/Pod/Parser.pm
--- Pod-Parser-1.61/lib/Pod/Parser.pm 2013-06-01 23:12:20.000000000 +1000
+++ Pod-Parser-1.61-deprec/lib/Pod/Parser.pm 2013-09-27 11:22:06.000000000 +1000
@@ -81,6 +81,10 @@ Nothing.
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
B<Pod::Parser> is a base class for creating POD filters and translators.
It handles most of the effort involved with parsing the POD sections
from an input stream, leaving subclasses free to be concerned only with
@@ -90,10 +94,6 @@ B<Pod::Parser> parses PODs, and makes me
components of the POD. Subclasses of B<Pod::Parser> override these methods
to translate the POD into whatever output format they desire.
-Note: This module is considered as legacy; modern Perl releases (5.18 and
-higher) are going to remove Pod::Parser from core and use L<Pod::Simple>
-for all things POD.
-
=head1 QUICK OVERVIEW
To create a POD filter for translating POD documentation into some other
diff -rupN Pod-Parser-1.61/lib/Pod/ParseUtils.pm Pod-Parser-1.61-deprec/lib/Pod/ParseUtils.pm
--- Pod-Parser-1.61/lib/Pod/ParseUtils.pm 2013-06-01 23:09:47.000000000 +1000
+++ Pod-Parser-1.61-deprec/lib/Pod/ParseUtils.pm 2013-09-27 11:22:24.000000000 +1000
@@ -27,6 +27,10 @@ Pod::ParseUtils - helpers for POD parsin
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
B<Pod::ParseUtils> contains a few object-oriented helper packages for
POD parsing and processing (i.e. in POD formatters and translators).
diff -rupN Pod-Parser-1.61/lib/Pod/PlainText.pm Pod-Parser-1.61-deprec/lib/Pod/PlainText.pm
--- Pod-Parser-1.61/lib/Pod/PlainText.pm 2013-02-01 05:38:29.000000000 +1000
+++ Pod-Parser-1.61-deprec/lib/Pod/PlainText.pm 2013-09-27 11:22:28.000000000 +1000
@@ -621,6 +621,10 @@ Pod::PlainText - Convert POD data to for
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
Pod::PlainText is a module that can convert documentation in the POD format (the
preferred language for documenting Perl) into formatted ASCII. It uses no
special formatting controls or codes whatsoever, and its output is therefore
diff -rupN Pod-Parser-1.61/lib/Pod/Select.pm Pod-Parser-1.61-deprec/lib/Pod/Select.pm
--- Pod-Parser-1.61/lib/Pod/Select.pm 2013-06-01 23:12:57.000000000 +1000
+++ Pod-Parser-1.61-deprec/lib/Pod/Select.pm 2013-09-27 11:22:34.000000000 +1000
@@ -71,6 +71,10 @@ podselect()
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
B<podselect()> is a function which will extract specified sections of
pod documentation from an input stream. This ability is provided by the
B<Pod::Select> module which is a subclass of B<Pod::Parser>.
diff -rupN Pod-Parser-1.61/lib/Pod/Parser.pm Pod-Parser-1.61-sanity/lib/Pod/Parser.pm
--- Pod-Parser-1.61/lib/Pod/Parser.pm 2013-06-01 23:12:20.000000000 +1000
+++ Pod-Parser-1.61-sanity/lib/Pod/Parser.pm 2013-09-27 13:01:00.000000000 +1000
@@ -1146,7 +1146,7 @@ closes the input and output files.
=back
-If the special input filename "-" or "<&STDIN" is given then the STDIN
+If the special input filename "", "-" or "<&STDIN" is given then the STDIN
filehandle is used for input (and no open or close is performed). If no
input filename is specified then "-" is implied. Filehandle references,
or objects that support the regular IO operations (like C<E<lt>$fhE<gt>>
diff -rupN Pod-Parser-1.61/lib/Pod/Select.pm Pod-Parser-1.61-sanity/lib/Pod/Select.pm
--- Pod-Parser-1.61/lib/Pod/Select.pm 2013-06-01 23:12:57.000000000 +1000
+++ Pod-Parser-1.61-sanity/lib/Pod/Select.pm 2013-09-27 13:02:07.000000000 +1000
@@ -531,7 +531,7 @@ implicit first argument.
B<podselect> will print the raw (untranslated) POD paragraphs of all
POD sections in the given input files specified by C<@filelist>
-according to the given options.
+according to the options given in C<\%options>.
If any argument to B<podselect> is a reference to a hash
(associative array) then the values with the following keys are
@@ -565,10 +565,10 @@ are used.
=back
-All other arguments should correspond to the names of input files
-containing POD sections. A file name of "-" or "<&STDIN" will
-be interpreted to mean standard input (which is the default if no
-filenames are given).
+All other arguments are optional and should correspond to the names
+of input files containing POD sections. A file name of "", "-" or
+"<&STDIN" will be interpreted to mean standard input (which is the
+default if no filenames are given).
=cut
@@ -581,8 +581,11 @@ sub podselect {
my %opts;
local $_;
for (@argv) {
- if (ref($_)) {
- next unless (ref($_) eq 'HASH');
+ my $ref = ref($_);
+ if ($ref) {
+ if (not $ref eq 'HASH') {
+ croak "Input from $ref reference not supported!\n";
+ }
%opts = (%defaults, %{$_});
##-------------------------------------------------------------
@@ -617,7 +620,7 @@ sub podselect {
++$num_inputs;
}
}
- $pod_parser->parse_from_file('-') unless ($num_inputs > 0);
+ $pod_parser->parse_from_file('-') unless ($num_inputs > 0);
}
#############################################################################
diff -rupN Pod-Parser-1.61/t/pod/testp2pt.pl Pod-Parser-1.61-sanity/t/pod/testp2pt.pl
--- Pod-Parser-1.61/t/pod/testp2pt.pl 2011-09-17 00:32:16.000000000 +1000
+++ Pod-Parser-1.61-sanity/t/pod/testp2pt.pl 2013-09-27 12:33:43.000000000 +1000
@@ -141,8 +141,8 @@ sub testpodplaintext( @ ) {
my %opts = (ref $_[0] eq 'HASH') ? %{shift()} : ();
my @testpods = @_;
my ($testname, $testdir) = ("", "");
- my ($podfile, $cmpfile) = ("", "");
- my ($outfile, $errfile) = ("", "");
+ my ($podfile , $cmpfile) = ("", "");
+ my ($outfile , $errfile) = ("", "");
my $passes = 0;
my $failed = 0;
local $_;
