Is there a "poor man's" perldoc?

[jl_post]

Hi,

I use the perldocs frequently when I'm programming in Perl.
However, on some systems I've used, "perldoc" is apparently not
installed (despite the fact that Perl is). What I'd like is a way to
cleanly extract the perldoc documentation from a module that is
installed on that system. (For example, I'd like to view the
documentation that I'd normally see with "perldoc Time::Local" on a
system that unfortunately doesn't have "perldoc" installed.)

I know that I can go to cpan.org and look up the documentation, but
sometimes I'm working on a system cut off from the internet. Just
extracting the perl documentation from an already installed module
doesn't seem to me to be a very complex issue (although maybe I'm
wrong).

So what I'm asking is: Is there a pure-Perl way to view a module's
perldoc documentation, particularly if the "perldoc" package is not
installed (and I have no power to install it)?

Thanks.

-- Jean-Luc

 

[John Bokma]

So what I'm asking is: Is there a pure-Perl way to view a module's
perldoc documentation, particularly if the "perldoc" package is not
installed (and I have no power to install it)?

perldoc *is* pure Perl.

Install Pod:erldoc and locally [1], it comes with perldoc.
Just set a path to it, or:

perl -MPod:erldoc -e'Pod:erldoc->run()' Time::Local

perldoc -q 'own module'

 

[jl_post]

   So what I'm asking is:  Is there a pure-Perl way to view
a module's perldoc documentation, particularly if the
"perldoc" package is not installed (and I have no power to
install it)?

perldoc *is* pure Perl.



Install Pod:erldoc and locally [1], it comes with perldoc.
Just set a path to it, or:

perl -MPod:erldoc -e'Pod:erldoc->run()' Time::Local

Excellent! I just tried that one command on one system that
doesn't have "perldoc" installed, and the perldoc documentation for
Time::Local appeared! (So ironically Pod:erldoc is apparently
already installed, even though the "perldoc" package is not.)

It even works for regular perldoc pages, like "perlpacktut", like
this:

perl -MPod:erldoc -e "Pod:erldoc->run()" perlpacktut

If I want to look up a core function, like split(), I can't figure
out how to emulate "perldoc -f split", but I CAN do:

perl -MPod:erldoc -e "Pod:erldoc->run()" perlfunc

and look it up from there. However, I still can't figure out how to
do things like "perldoc -q 'own module'". (I'd read through the
"perldoc Pod:erldoc" documentation, but apparently there isn't
any...)

Anyway, John, your solution goes above and beyond what I was hoping
for. (Now I just need to commit it to memory for those times when I
can't look it up.)

Thanks again!

-- Jean-Luc

 

[Jürgen Exner]

I use the perldocs frequently when I'm programming in Perl.
However, on some systems I've used, "perldoc" is apparently not
installed (despite the fact that Perl is).

Then you may want to kick the administrator until he fixes the broken
installation.

jue

 

[Bart Lateur]

Then you may want to kick the administrator until he fixes the broken
installation.

Yeah, yeah.

Why not complain against the people making the Linux distributions. A
lot of them, if not all, separate the perl binary from the core modules.

 

[jl_post]

Then you may want to kick the administrator until he fixes the broken
installation.

That might work, if only I lived anywhere near the administrator.
But in some cases, (s)he's in another country altogether.

Sadly, some people just don't think the perldocs are all that
important. Once I was working on a system maintained by a fellow co-
worker who lived all the way across the country, and I needed the
documentation for an important Perl script. I tried "perldoc"ing it,
of course, but unfortunately the "perldoc" package was not installed.

Over the phone I begged my co-worker to install the "perldoc"
package but he didn't see the point. He figured that since we already
had access to the Camel book there was nothing more that the perldocs
could offer. Nevertheless, I succeeded in having him install the
perldocs, after which I instantly pulled up all the relevant
documentation.

He was surprised. "How did you find that information so quickly?"
he asked. I explained him it that all good modules have documentation
that can be extracted with the "perldoc" package, but that the
documentation can only be viewed if the "perldoc" package is properly
installed.

He then muttered something about the perldocs being more than what
he thought they were, and went on his way to do something else.

(With other administrators I haven't been so lucky. Many of them I
don't even know personally, so I fire off an e-mail, and never hear
from them.)

While I agree with you 100% that system administrators should
install the "perldoc" package along with Perl, if they happen to think
it's redundant and not needed, convincing them otherwise is a bit like
moving mountains.

-- Jean-Luc

 

[jl_post]

perldoc almost certainly *is* installed somewhere,
it's just not in your PATH. Check to see if your
/usr/bin/perl is a symlink somewhere, and if
the real binary has a 'perldoc' next to it.

I just tried your suggestion on one account (where "perldoc"
doesn't work) and sure enough, the file that "which perl" revealed was
indeed a symlink to... another symlink! I followed that new symlink,
and in that directory I found both the perl and the perldoc
executables.

So at least on that system, I can solve the perldoc problem by
creating an alias.

I'll have to try your suggestion on the system that lacks internet
access -- next time I use it, that is.

Thanks for your input, Ben.

-- Jean-Luc

 

[John Bokma]

There's this thing called "email," you see...


Having perldocs on a production server is *not* important. You
shouldn't be using that server for development work anyway. With
VirtualBox et al, you can easily mirror whatever deployment config
you need, right on your desktop, and install the tools and docs
you need on that.

There is such a thing as working on a remote development server ;-).
While you can mimick the development environment on your own machine, it
might not always be easy to do so.

 

[Jürgen Exner]

Yeah, yeah.

Why not complain against the people making the Linux distributions. A
lot of them, if not all, separate the perl binary from the core modules.

Not sure if you really meant core modules or rather perl documentation.

As for the documentation being in a separate package that is actually
logical when thinking about servers (of all kind). Documentation is for
human consumption during code development and nobody in his right mind
would develop code on a live server. On the contrary, in a server
environment you want the configuration to be as slick and streamlined as
possible to reduce any even far-fetched chance of interference.
Therefore I would expect servers not to contain any documentation.

Of course omitting the docs in a developer's environment is
unforegivable.

jue

 

[Jürgen Exner]

That's not necessarily true. Many Linux systems package perldoc
and the various .pod files into a separate perl-dev or similar
package.

Which actually makes sense because you need those only while
_dev_-eloping Perl code but not on any server that is running perl as a
utility.

jue

 

[Jürgen Exner]

True, but what I said is still valid, whether the dev environment is
on your desk or on the other side of the planet. Either way, it's the
developer's machine that needs perldoc, not the deployment server.

Exactly. Nobody in his right mind would develop code on a live server.

And for those red hot fixes that have to be done this instance bypassing
any and all testing and deployment procedures you can still check the
documentation on your dev machine or in the worst case online.
You are taking a very high risk anyway, the added risk of mismatched doc
versions is negligable in comparision.

jue

 

[John Bokma]

True, but what I said is still valid, whether the dev environment is
on your desk or on the other side of the planet. Either way, it's the
developer's machine that needs perldoc, not the deployment server.

Not argueing with you there. OTOH I see no great harm in 1 (or maybe
more) additional modules, and a bunch of text files.

It depends on the degree of accuracy you need. I don't have a Sparc
workstation in the office, for example - but I can install Solaris
in a VirtualBox instance, and for many purposes that can be close
enough.

Yup, true. On the other hand a customer might run SunOS with perl 5.0xxx
;-)

 

[John Bokma]

Exactly. Nobody in his right mind would develop code on a live server.

I haven't seen anybody implying such a thing. Why is it that working
remote seem to imply you're working on a live server?

There *are* situations where the development environment is remote. And
in that case it's good to have perldoc available on that system. Not
only because reproducing the environment on your own computer for the
sake of having access to the documentation that comes with Perl is
cumbersome (or might even be impossible), but also because it's useful
to read the documentation of custom Perl modules. And customers who want
you to work on their development computers are often not happy when you
download the custom modules to your own computer so you can read the
documentation with perldoc locally ;-)

 

[Jürgen Exner]

I haven't seen anybody implying such a thing. Why is it that working
remote seem to imply you're working on a live server?

Well, servers came up as an example of an environment where there is no
need for documentation on the machine.

There *are* situations where the development environment is remote. And
in that case it's good to have perldoc available on that system.

No question about that! On a development system, no matter if local or
remote, you do want and need all the tools that make you productive. You
wouldn't put up with ed, either, instead of vim or emacs or whatever
your favourite editor is.

jue

 

[Mart van de Wege]

There's this thing called "email," you see...


Having perldocs on a production server is *not* important.

Quite frankly, I disagree. When I am debugging a production problem, and
part of the problem is perl scripts and/or modules, it's convenient to
read the docs in-place, especially since I know the version of the docs
should fit the deployed perl.

Mart

 

[Peter J. Holzer]

Which actually makes sense because you need those only while
_dev_-eloping Perl code but not on any server that is running perl as a
utility.

Unless you're a consultant called in to fix something. Then it's damned
convenient to be able to read the docs of the scripts and modules which
are actually installed on the server with the problem instead of those
on your home system without the problem. Oh, and
perldoc -l Module::Name
is also nicer to type than
perl -MModule::Name -le 'print $INC{"Module/Name.pm"}'

hp

 

[Xho Jingleheimerschmidt]

Quite frankly, I disagree. When I am debugging a production problem, and
part of the problem is perl scripts and/or modules, it's convenient to
read the docs in-place, especially since I know the version of the docs
should fit the deployed perl.

I run into this problem frequently. I'm trying to debug something on
production server, and discover that not only does it not have perldoc
or man, it also doesn't have top, ps, strace, ltrace, etc. The
resulting conversation goes something like this:

me: "Please install these on the production servers"

IT: "We don't put debugging tools on the production servers because you
are supposed to debug on dev, not production"

me: "The problem does not manifest on dev servers, only production, so
it has to be debugged on production."

IT: "That's impossible, the production servers are identical to the dev
servers."

me: "Obviously not. If they were indentical, then all the debug tools I
just requested would already be there. They aren't."

IT and me: Mutual head explosion.

Xho

 

[Martijn Lievaart]

I run into this problem frequently. I'm trying to debug something on
production server, and discover that not only does it not have perldoc
or man, it also doesn't have top, ps, strace, ltrace, etc. The
resulting conversation goes something like this:

Oh yes, production servers without man. So I am supposed to "know" all
parameters of those seldom used commands on $SOME_ANCIENT_UNIX and will
never make a mistake, while the hacker that just entered the machine is
seriously hampered by the omission of man pages. Yeah sure.

I call that a production risk. Unfortunately, many risk "professionals"
don't agree with me.

M4

 

[sln]

me: "The problem does not manifest on dev servers, only production, so
it has to be debugged on production."

IT: "That's impossible, the production servers are identical to the dev
servers."

me: "Obviously not. If they were indentical, then all the debug tools I
just requested would already be there. They aren't."

You lost me with these 3. The debug tools on dev are the only difference
between the two and it doesen't manifest on dev ??
There must be some serious background proceses hooking going on, on dev.

So, you want to put debug tools on production, making it identical to dev?
Thats not a step in the right direction.

-sln

 

[Mart van de Wege]

Oh yes, production servers without man. So I am supposed to "know" all
parameters of those seldom used commands on $SOME_ANCIENT_UNIX and will
never make a mistake, while the hacker that just entered the machine is
seriously hampered by the omission of man pages. Yeah sure.

I call that a production risk. Unfortunately, many risk "professionals"
don't agree with me.

Yes, well, my daily job *is* security.

And I run into a lot of 'consultants' who do security by the book, which
means that rules like 'no extraneous software on production servers' get
implemented in the most hare-brained way possible, and any protest that
you *need* certain tools is met with 'That's a security risk'.

You know, sometimes security is best served by giving an admin the tools
to reduce their response time to an incident. That gives them the time
to ascertain whether the incident is merely an innocent crash or an
actual exploit attempt.

And for that, I often need dev tools and documentation.

Mart