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 the editor of Perl.com. An organizer of the New York Perl Meetup, he works for ZipRecruiter as a software developer, and sometimes tweets about Perl and Open Source.

Browse their articles

Feedback

Something wrong with this article? Help us out by opening an issue or pull request on GitHub