Pod::To::Pager

Pod::To::Pager is a Perl 6 project to generate prettier output from Perl 6 Pod structures. By default, Perl 6 ships with a very simple Pod formatter, which can be used by calling perl6 --doc <file>. You can specify a doc formatter by giving it as argument, like perl6 --doc=Text <file>. This will use the Pod::To::Text module to format the output, which is also the default.

But, I wanted something prettier, something I would actually like reading if I were looking for documentation on a module. Most people are familiar with UNIX man pages (or at least, most people who will read, this I hope). So I wanted to create something similar. To get used to Perl 6 Pod, I just tried making simple text, with some coloring, as this is easier than also trying to learn how man pages are to be created.

And so, Pod::To::Pager was born. I’ve received some feedback from the Perl 6 community, and included some of it in to the module. It comes with a p6man utility, which is very much like p6doc. It calls the formatter, and calls a pager to show the result. It looks very much like the UNIX man pages, and the pager lets you read it like one. It’s basically an on-the-fly generated man page.

Installation

To install the module, be sure to have Perl 6 and zef, the Perl 6 module manager, installed on your system. You can then call zef install to have it download, test, and install the module:

zef install Pod::To::Pager

Usage

Once installed, you can use the module in many ways. You can call it as a Pod formatter on Perl 6 itself:

perl6 --doc=Pager lib/Some/Module.pm6

This will render the document on STDOUT, and display it in your terminal. If it doesn’t support scrollback, there’s a high chance you can’t see the top part of it. To solve that, you can use a pager, like less:

perl6 --doc=Pager lib/Some/Module.pm6 | less

This will keep it possible to scroll through the output, until you press q to quit the pager.

p6man

Since the last form is the way it was intended to be used (hence the pager in Pod::To::Pager), there’s a utility bundled with the module to make such use easier. Inspired by the existence of p6doc, it’s called p6man. It will use less as the pager on GNU+Linux if possible, otherwise it will fall back to more. On Windows, it will just use more. You can call it with either a (relative) file path, or a module name:

p6man lib/Some/Module.pm6
p6man App::Assixt

For the latter variant to work, the module must be installed locally.

In Perl 6 programs

You can also use it directly in Perl 6 programs. This allows you to change behaviour of the formatting process, or render the program’s own documentation with this formatter’s output. To do that, use the module, and call the format method on the formatter class:

use Pod::To::Pager;

say Pod::To::Pager($=pod);

This will render the program’s own Pod structure, formatted using Pod::To::Pager, and print it to STDOUT.

Feedback

If you have any feedback, please reach out to me on #perl6 on IRC, or create an issue on the repository.