After thinking about the recent discussion regarding the operators, I was
hit by a simple consideration: we (the human) are debating about something
that it (the computer) should manage.
On the one hand, the docs for the quote-like operators are in perlop. I
think that we all like this (the "they're operators!" party being somewhat
more enthusiast ;). On the other hand, I also think that we all like
"perldoc -f whatever" being *immediately* useful, without forcing to do
one more step (for the joy of the "laziness" party).
Both points of view are correct IMHO, what's probably wrong is thinking
they're opposite :) I'd like to propose a little patch to Pod/Perldoc.pm,
which looks for sensible documentation in perlop for the following
operators:
m q qq qr qx qw s tr y
We're lucky that the description of these operators has (more or less) the
same structure that we find in perlfunc.
If you think this could be helpful, I'd be glad to propose the patch to
Mr. Sean M. Burke, who seems to be the responsible for Pod::Perldoc
maintenance. The patch seems to work on my system but - ehr - that's only
my system :)
Best regards,
Flavio.
--- the following patch applies to Pod/Perldoc.m v. 3.14 ---
--- /opt/perl/lib/5.8.8/Pod/Perldoc.pm 2006-02-02 12:58:49.000000000 +0100
+++ Perldoc.pm 2006-05-19 17:29:09.987278264 +0200
@@ -408,7 +408,7 @@
my @pages;
$self->{'pages'} = [EMAIL PROTECTED];
- if( $self->opt_f) { @pages = ("perlfunc") }
+ if( $self->opt_f) { @pages = ("perlfunc", 'perlop') }
elsif( $self->opt_q) { @pages = ("perlfaq1" .. "perlfaq9") }
else { @pages = @{$self->{'args'}};
# @pages = __FILE__
@@ -807,6 +807,29 @@
DEBUG > 2 and print "Search: @$found_things\n";
+ # First, search in perlfunc
+ $self->_search_perlfunc_workhorse($found_things, $pod,
+ qr/^=head2 Alphabetical Listing of Perl Functions/);
+
+ # Then, search in perlop, if applicable. This is lazy, but we
+ # use the previous search in order to have a "polished" thing
+ # to search upon.
+ if ($pod->[0] =~ m{\A=item\s+(?: [qmsy] | q[qrxw] | tr )\b}mxs) {
+ @$pod = ();
+ $self->_search_perlfunc_workhorse($found_things, $pod,
+ qr/^=head2 Regexp Quote-Like Operators/);
+ push @$pod, "\n", "\n", "(Description taken from L<perlop>)\n", "\n";
+ }
+ return;
+}
+
+#..........................................................................
+
+sub _search_perlfunc_workhorse {
+ my($self, $found_things, $pod, $starter_regex) = @_;
+
+ DEBUG > 2 and print "Search: @$found_things\n";
+
my $perlfunc = shift @$found_things;
open(PFUNC, "<", $perlfunc) # "Funk is its own reward"
or die("Can't open $perlfunc: $!");
@@ -821,7 +844,7 @@
# Skip introduction
local $_;
while (<PFUNC>) {
- last if /^=head2 Alphabetical Listing of Perl Functions/;
+ last if /$starter_regex/;
}
# Look for our function
@@ -842,7 +865,7 @@
--$inlist;
}
push @$pod, $_;
- ++$found if /^\w/; # found descriptive text
+ ++$found if /^\w/ && ! /^X</; # found descriptive text
}
if ([EMAIL PROTECTED]) {
die sprintf
