Reading the Friendly Manual

So, when you want to just play around with a module, local::lib is a good way to install libraries in a quick, disposable way that doesn't affect your global development environment. Sometimes, though, you don't even need to play around. You just want to look at the docs for the code someone suggested but that you haven't yet installed.

A lot of people would switch over to a web browser, but not me. I'm used to reading Perl documentation in the terminal, and reading it elsewhere ends up giving me a confused feeling. In the past, I used to just install the code (in a local::lib compartment once I knew about it) and then run perldoc.

Of course, some people prefer reading their docs on the web. There are other tools for weirdos like that. Me, I like cpandoc!

cpandoc works almost exactly like perldoc, with a big change that makes it even better. If cpandoc can't find the library you asked for in your system's Perl environment, it will get it – just the documentation – from the CPAN and format that instead.

In other words:

  ~$ perldoc MooseX::Iterator
  No documentation found for "MooseX::Iterator".

Oh no! Will I have to press Cmd-Tab and go to my web browser? Or download the library and look at its tarball's contents? No! I can just...

  ~$ cpandoc MooseX::Iterator
  [ ... and the pager runs, showing me the documentation! ]

Truth be told, though, this isn't where it shines for me. I like that it provides all the same options as perldoc. Specifically, it has the -m option, to view the source. When someone on IRC has questions about how some module they're trying to use works, I just run...

  ~$ cpandoc -m Some::Stupid::Module

...and I get the source of the code in question, whether or not I already have it locally.

And, well, actually that's not true either. Since cpandoc is just like perldoc, I made a shell alias. When I type perldoc – as I always do, since it's burned into my muscle memory – I get cpandoc instead.

See Also

• Pod::Cpandoc

• Pod::Perldoc