|P is for Practical|
perldoc "tricks"by Tanktalus (Canon)
|on Nov 30, 2011 at 00:16 UTC||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:
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.