perldoc error: No documentation file

I usually document my perl code using POD syntax, normally I can read the documentation using:

perldoc myscript.pl

where myscript.pl is the perl script I wrote with the POD inside.

For example if myscript.pl contains:

#!/usr/bin/perl

use warnings;
use strict;

print 'hello world';

=head1 NAME

My Script name

=head1 DESCRIPTION

Description of My Script

=cut

and execute: perldoc myscript.pl I got this:

MYSCRIPT(1)           User Contributed Perl Documentation          MYSCRIPT(1)



NAME
       My Script name

DESCRIPTION
       Description of My Script



perl v5.18.2                      2016-03-15                       MYSCRIPT(1)

Now I found that in some systems I got the following error:

$ perldoc myscript.pl
No documentation found for "myscript.pl".

Anyone have an idea why is this happening? Could be a missing module or software package? Anything else?

Answers


If you consult the man page for perldoc itself; man perldoc you read:

 "perldoc" also searches directories specified by the 
 "PERL5LIB" (or "PERLLIB" if "PERL5LIB" is not defined) and
 "PATH" environment variables.  (The latter is so that embedded 
 pods for executables, such as "perldoc" itself,are available.)

So you see, the usual places that libraries of modules can be found are searched but also directories specified in your $PATH environment variable. The latter might come as a surprise but as the man page explains, how else is going to check for POD in home-grown scripts.

Your question is really dependant on your environment so, I can't say anything authoritative, but I would bet that in some places (ie some machines) your $PATH includes "." - the current directory - for convenience but on other machines, "." is excluded from $PATH on security grounds.

Failing that, you can get a running commentary on where perldoc is looking for the POD by using the -D CLI option:

$ perldoc -D myscript.pl
Ending switch processing.  Args are [myscript.pl] with 0 errors.
Pagers: /usr/bin/sensible-pagermorelesspgviewcat/usr/bin/perldoc => Pod::Perldoc v3.23

Formatter class Pod::Perldoc::ToTerm version 3.23 successfully loaded!
Will format with the class Pod::Perldoc::ToTerm
Searching for myscript.pl
Looking for myscript.pl in /usr/bin /etc/perl /usr/local/lib/x86_64-linux-gn
u/perl/5.20.2 /usr/local/share/perl/5.20.2 /usr/lib/x86_64-linux-gnu/perl5/5.20
/usr/share/perl5 /usr/lib/x86_64-linux-gnu/perl/5.20 /usr/share/perl/5.20
/usr/local/lib/site_perl . /opt/perl6/share/perl6/site/bin /opt/perl6/bin
/usr/local/sbin /usr/local/bin /usr/sbin /usr/bin /sbin /bin
No documentation found for "myscript.pl".
$

I deliberately chose "myscript.pl" because I don't have such a script. You see clearly everywhere it's looking - this should reveal where the problem is. Finally, finally, you can use -F to explicitly state what file to get the POD out of - this can be used to see if the problem is the POD in the file itself: perldoc -F ./myscript.pl


Need Your Help

How to send arguments when requesting form

django django-forms validation

During user registration I'm calling some custom function :

Extjs Pie Chart on click direct to new page

extjs web onclick extjs4.1 pie-chart

I have an Extjs pie chart right now and I want each piece of the pie to be clickable, and once clicked, take me to a new page.