Is there a "poor man's" perldoc?

Discussion in 'Perl Misc' started by jl_post@hotmail.com, Mar 4, 2010.

  1. Guest

    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
    , Mar 4, 2010
    #1
    1. Advertising

  2. John Bokma Guest

    "" <> writes:

    > 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::perldoc and locally [1], it comes with perldoc.
    Just set a path to it, or:

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

    perldoc -q 'own module'

    --
    John Bokma j3b

    Hacking & Hiking in Mexico - http://johnbokma.com/
    http://castleamber.com/ - Perl & Python Development
    John Bokma, Mar 4, 2010
    #2
    1. Advertising

  3. Guest

    > "" <> asked:
    > >    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.



    On Mar 4, 12:44 pm, John Bokma <> replied:
    >
    > Install Pod::perldoc and locally [1], it comes with perldoc.
    > Just set a path to it, or:
    >
    > perl -MPod::perldoc -e'Pod::perldoc->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::perldoc is apparently
    already installed, even though the "perldoc" package is not.)

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

    perl -MPod::perldoc -e "Pod::perldoc->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::perldoc -e "Pod::perldoc->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::perldoc" 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
    , Mar 4, 2010
    #3
  4. "" <> wrote:
    > 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
    Jürgen Exner, Mar 4, 2010
    #4
  5. Bart Lateur Guest

    Jürgen Exner wrote:

    >"" <> wrote:
    >> 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.


    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.

    --
    Bart.
    Bart Lateur, Mar 5, 2010
    #5
  6. Guest

    On Mar 4, 4:21 pm, Jürgen Exner <> wrote:
    >
    > 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
    , Mar 5, 2010
    #6
  7. Guest

    On Mar 4, 3:27 pm, Ben Morrow <> wrote:
    >
    > 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
    , Mar 5, 2010
    #7
  8. John Bokma Guest

    Sherm Pendley <> writes:

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

    >
    > There's this thing called "email," you see... :)
    >
    >> Sadly, some people just don't think the perldocs are all that
    >> important.

    >
    > 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.

    --
    John Bokma j3b

    Hacking & Hiking in Mexico - http://johnbokma.com/
    http://castleamber.com/ - Perl & Python Development
    John Bokma, Mar 5, 2010
    #8
  9. Bart Lateur <> wrote:
    >Jürgen Exner wrote:
    >
    >>"" <> wrote:
    >>> 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.

    >
    >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, Mar 5, 2010
    #9
  10. Sherm Pendley <> wrote:
    >Ben Morrow <> writes:
    >
    >> perldoc almost certainly *is* installed somewhere

    >
    >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, Mar 5, 2010
    #10
  11. Sherm Pendley <> wrote:
    >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
    Jürgen Exner, Mar 5, 2010
    #11
  12. John Bokma Guest

    Sherm Pendley <> writes:

    > John Bokma <> writes:
    >
    >> Sherm Pendley <> writes:
    >>
    >>> 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 ;-).

    >
    > 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.

    >> While you can mimick the development environment on your own machine,
    >> it might not always be easy to do so.

    >
    > 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 j3b

    Hacking & Hiking in Mexico - http://johnbokma.com/
    http://castleamber.com/ - Perl & Python Development
    John Bokma, Mar 5, 2010
    #12
  13. John Bokma Guest

    Jürgen Exner <> writes:

    > Sherm Pendley <> wrote:
    >>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.


    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 ;-)

    --
    John Bokma j3b

    Hacking & Hiking in Mexico - http://johnbokma.com/
    http://castleamber.com/ - Perl & Python Development
    John Bokma, Mar 5, 2010
    #13
  14. John Bokma <> wrote:
    >Jürgen Exner <> writes:
    >
    >> Sherm Pendley <> wrote:
    >>>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.

    >
    >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
    Jürgen Exner, Mar 5, 2010
    #14
  15. Sherm Pendley <> writes:

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

    >
    > There's this thing called "email," you see... :)
    >
    >> Sadly, some people just don't think the perldocs are all that
    >> important.

    >
    > 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

    --
    "We will need a longer wall when the revolution comes."
    --- AJS, quoting an uncertain source.
    Mart van de Wege, Mar 6, 2010
    #15
  16. On 2010-03-05 16:59, Jürgen Exner <> wrote:
    > Sherm Pendley <> wrote:
    >>Ben Morrow <> writes:
    >>> perldoc almost certainly *is* installed somewhere

    >>
    >>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.


    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
    Peter J. Holzer, Mar 6, 2010
    #16
  17. Mart van de Wege wrote:
    > Sherm Pendley <> writes:
    >
    >> "" <> writes:
    >>
    >>> Sadly, some people just don't think the perldocs are all that
    >>> important.

    >> 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.


    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
    Xho Jingleheimerschmidt, Mar 6, 2010
    #17
  18. On Sat, 06 Mar 2010 10:39:25 -0800, Xho Jingleheimerschmidt wrote:

    > 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
    Martijn Lievaart, Mar 6, 2010
    #18
  19. Guest

    On Sat, 06 Mar 2010 10:39:25 -0800, Xho Jingleheimerschmidt <> wrote:

    >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
    , Mar 6, 2010
    #19
  20. Martijn Lievaart <> writes:

    > On Sat, 06 Mar 2010 10:39:25 -0800, Xho Jingleheimerschmidt wrote:
    >
    >> 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.
    >

    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

    --
    "We will need a longer wall when the revolution comes."
    --- AJS, quoting an uncertain source.
    Mart van de Wege, Mar 7, 2010
    #20
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Replies:
    9
    Views:
    500
    Benji
    Nov 23, 2005
  2. qvx
    Replies:
    7
    Views:
    438
  3. Replies:
    27
    Views:
    821
    Marc 'BlackJack' Rintsch
    Mar 17, 2006
  4. pete
    Replies:
    12
    Views:
    722
    Stephen Sprunk
    Dec 27, 2010
  5. James Edward Gray II

    Perldoc Equivalent?

    James Edward Gray II, Aug 28, 2004, in forum: Ruby
    Replies:
    19
    Views:
    332
    Mauricio Fernández
    Sep 6, 2004
Loading...

Share This Page