Reading remote documentation
When I need to read Perl documentation, I use perldoc. I spend most of my time working at the terminal, so it’s convenient to drop to a command prompt and bring up the documentation for some module or command right there in the terminal.
Pod::Cpandoc
Sometimes I need to check the documentation of a module I don’t have installed on my machine, and in those cases, perldoc
can’t help me. Instead I could use cpandoc, as it behaves like perldoc, but it will fetch remote documentation if the module is not installed on your system.
$ cpandoc Foo::Bar
# displays Foo::Bar pod in pager app
As cpandoc
supports the same options as perldoc
, you can use it for useful tricks like browsing the source code for a module without installing it.
♥ Metacpan ♥
Now, reading documentation in the terminal is fine and all, but I really like metacpan’s distribution pages, which not only include documentation, but also incorporate CPAN Testers’ results, a release history, open issues, and other useful links and data. So lately I’ve taken to reading documentation on metacpan.
Getting there though, can be tiresome. I open a new browser tab, start typing “metacpan”, my browser then autocompletes it to the most recent metacpan address I viewed, which is inevitably not the one I want, so I highlight the module name in the URL, and replace it with the one I’m looking for.
After having performed this routine more times than I’d like to admit, I finally wrote a shell script to do it for me:
#!/bin/sh
URL="https://metacpan.org/pod/$1"
if [[ "$OSTYPE" == "linux-gnu" ]]; then
xdg-open "$URL" &>/dev/null
elif [[ "$OSTYPE" == "darwin"* ]]; then
open "$URL" &>/dev/null
elif [[ "$OSTYPE" == "cygwin" ]]; then
cygstart "$URL" &>/dev/null
elif [[ "$OSTYPE" == "msys" ]]; then
start "$URL"
elif [[ "$OSTYPE" == "win32" ]]; then
start "$URL"
elif [[ "$OSTYPE" == "freebsd"* ]]; then
xdg-open "$URL" &>/dev/null
else
echo "OS not recognized"
fi
It constructs the metacpan URL using the first argument passed to the script, and then opens the URL in a new browser tab. I named the script pod
and placed it in my local path (I was going to call it mcpan
but that’s a little similar to cpanm
for my tastes, plus “pod” is faster to type). So now if I want to view something on metacpan, all I have to do is type:
$ pod Foo::Bar
And the script does the rest. I’ve added commands for other operating systems, but I’ve only tested it on Linux and MacOS.
Tags
David Farrell
David is a professional programmer who regularly tweets and blogs about code and the art of programming.
Browse their articles
Feedback
Something wrong with this article? Help us out by opening an issue or pull request on GitHub