Anonymous Monk has asked for the wisdom of the Perl Monks concerning the following question:

Why does "perldoc -lf splice" return perlfunc and perlop when the word "splice" does not exist in perlop?
% perldoc -lf splice                                                                             
/Users/u/perl5/perlbrew/perls/perl-5.42.0/lib/5.42.0/pods/perlfunc.pod
/Users/u/perl5/perlbrew/perls/perl-5.42.0/lib/5.42.0/pods/perlop.pod

% grep 'splice' /Users/u/perl5/perlbrew/perls/perl-5.42.0/lib/5.42.0/pods/perlfunc.pod
L<C<splice>|/splice ARRAY,OFFSET,LENGTH,LIST> has three scalar arguments
... (19 lines deleted for brevity)

% grep 'splice' /Users/u/perl5/perlbrew/perls/perl-5.42.0/lib/5.42.0/pods/perlop.pod
% <- NOTHING!

Replies are listed 'Best First'.
Re: perldoc -lf anomaly
by choroba (Cardinal) on May 07, 2026 at 19:56 UTC
    It seems
    perldoc -lf whatever
    returns perlfunc and perlop regardless of what "whatever" is.
    $ perldoc -lf anomaly /home/choroba/localperl/lib/5.43.9/pod/perlfunc.pod /home/choroba/localperl/lib/5.43.9/pod/perlop.pod
    map{substr$_->[0],$_->[1]||0,1}[\*||{},3],[[]],[ref qr-1,-,-1],[{}],[sub{}^*ARGV,3]
      returns perlfunc and perlop regardless of what "whatever" is.
      
      $ perldoc -lf anomaly
      /home/choroba/localperl/lib/5.43.9/pod/perlfunc.pod
      /home/choroba/localperl/lib/5.43.9/pod/perlop.pod
      
      

      Thanks for looking into it choroba. These results clearly contradict the perldoc documentation:

      perldoc perldoc (and man perldoc) says:
      -l   Display only the file name of the module found.
      
      perldoc --help says:
      -l   Display the module's file name
      
      Here's another anomaly:
      % perldoc -lf splice    
      /Users/u/perl5/perlbrew/perls/perl-5.42.0/lib/5.42.0/pods/perlfunc.pod
      /Users/u/perl5/perlbrew/perls/perl-5.42.0/lib/5.42.0/pods/perlop.pod
      
      % perldoc $_        
      No documentation found for "splice".
      
      % perldoc -v $_
      'splice' does not look like a Perl variable
      
      % perldoc -v '$_'
      $_      The default input and pattern-searching space...
      
      And another one:
      % perldoc -v '$_'
      $_      The default input and pattern-searching space...
      
      % perldoc -v '@_' 
      @_      Within a subroutine the array @_ contains the parameters...
      
      % perldoc -v '%_'
      No documentation for perl variable '%_' found
      
        I'm not sure about the "another anomaly". You get the documentation of splice for $_, as $_ without quotes is the shell variable which contains the last argument of the last command.

        map{substr$_->[0],$_->[1]||0,1}[\*||{},3],[[]],[ref qr-1,-,-1],[{}],[sub{}^*ARGV,3]

        These results clearly contradict the perldoc documentation:

        That's not true. The docs don't say what happens if you use -l with -f func instead of a module.

        Here's another anomaly

        What do you think is anomalous? That it's looking up splice instead of $_? That's your error. You interpolated shell variable $_ into your shell command, and it apparently had the value splice.

        And another one:

        What do you think is anomalous? That output is correct too, and I have no idea what you think is wrong.

        These results clearly contradict the perldoc documentation:

        That's not true. The docs don't say what happens if you use -l with -f func instead of a module.

        Here's another anomaly

        What do you think is anomalous? That it's looking up splice instead of $_? That's your error. You interpolated shell variable $_ into your shell command, and it apparently had the value splice.

        And another one:

        What do you think is anomalous? That output is correct too, and I have no idea what you think is wrong.

Re: perldoc -lf anomaly
by LanX (Saint) on May 07, 2026 at 23:13 UTC
    You are combining two unrelated options.

    What do you expect -lf to produce???

    If anything this undefined behaviour should be rejected.

    Anyway my best guess is that

    • -f is always (only) searching those two docs for snippets
    • -l is always listing the full path of parsed pods

    So this "anomaly" makes IMHO perfect sense.

    Edit

    Usage demo

    $ perldoc -l perldoc /data/data/com.termux/files/usr/lib/perl5/5.40.3/pod/perldoc.pod $ perldoc -l Data::Dumper /data/data/com.termux/files/usr/lib/perl5/5.40.3/aarch64-android/Data/ +Dumper.pm $ perldoc -f x x xor These operators are documented in perlop. $

    Update

    If your intention was to find every perldoc documenting a certain keyword :

    I once wrote a script which will parse them all for X<keyword> tags.

    See Perldoc Keyword Search (update3)

    Cheers Rolf
    (addicted to the Perl Programming Language :)
    see Wikisyntax for the Monastery