Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid

perldoc "tricks"

by Tanktalus (Canon)
on Nov 30, 2011 at 00:16 UTC ( #940738=CUFP: print w/replies, xml ) Need Help??

It was only in the last couple of years I found the "-l" flag to perldoc. This makes it so easy to view code: less $(perldoc -l Modern::Perl). It then becomes really easy to see how a module works so ensure I'm calling it correctly. I spent a lot of time recently looking at various parts of AnyEvent this way, and it helped a lot.

However, that's only a minor thing. The "cool" bit is when I looked at the perldoc command itself. It's structured beautifully: it loads Pod::Perldoc, and calls run on the Pod::Perldoc package. So I got the idea, why not write my own wrapper where I can add appropriate paths to my @INC for my RCS. I took the perldoc command, added in use lib (); and some lib->import(...);s (*) before calling Pod::Perldoc->run(), and saved this as "pdoc". Not only do I save 42% off the length of the command (I'm a fan of ack, too), but I can immediately read the perldocs embedded in any of my code. With some modules providing very core functionality that is used all the time with many options, and other modules providing core functionality that is not used very much but is very important, enabling myself and my team to quickly pull up the documentation can save a lot of time.

Up to now, I've been reading my own docs in my editor. And that works, more or less, for me. Some of my teammates are less comfortable trying to read docs among the code, or just perldoc in general. Having it reformatted has been a big win for us. Even for me, just finding it in the editor (we have about four library paths in our RCS, which get sent to the user in different ways, if at all, so that's four directories to go up and down) can be time consuming, but finding it through pdoc allows the computer to do my work for me.

And then I combine the two. I have an alias "ed" that dates back to my OS/2 days which was just a pointer to my current favourite editor (it varied a lot originally, but has been pretty static for the last decade or so). So I just type ed $(pdoc -l My::Module) and up comes the source. I'm tempted to add a -e flag or something that would automatically bring up the file in the editor, but that starts to complicate things.

Just thought that this might give tools fans something to think about, and for the non-fans, just a thought as to how tools can make your life sooo much easier.

(*) How you determine the library paths in your RCS is going to be very specific to your situation. In my case, I just mandated some environment variables that our testing code relies on, and reused them here. For example, something like this:

lib->import($_) for grep { -d } map { File::Spec->catdir($ENV{RCS_ROOT}, qw(common bits of path), $_) } 'lib', 'internal/code', 'etc';
How complex this is depends directly on how complex your RCS tree is. Ours is more complex than really needed, and yet still far less complex than when I joined the project.

Replies are listed 'Best First'.
Re: perldoc "tricks"
by toolic (Bishop) on Nov 30, 2011 at 00:37 UTC
    There is also perldoc -m :
    perldoc -m Carp
    which is similar to (on unix):
    more `perldoc -l Carp`
    Funny, I have an alias for perldoc named "pdoc" because I can't type "perldoc" correctly. I even have an alias named "pdco" because I can't type "pdoc" correctly :)
      double your productivity, make it pd
Re: perldoc "tricks"
by Tux (Abbot) on Nov 30, 2011 at 09:55 UTC

    All of this is described in O'Reilly's "Perl Hacks", Hack #2, page 3-6 "Put Perldoc to Work" (Do more than just read the documentation).

    I think that was written by chromatic

    Enjoy, Have FUN! H.Merijn
Re: perldoc "tricks"
by juster (Friar) on Dec 01, 2011 at 19:00 UTC
    The downside of the -l flag is that it will not display the path of the .pm file if there is no embedded POD documentation inside the module file. This does not seem to affect the -m flag.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: CUFP [id://940738]
Approved by ww
Front-paged by ww
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others exploiting the Monastery: (8)
As of 2017-05-25 08:35 GMT
Find Nodes?
    Voting Booth?