Programming Perl, 4th Edition

Pod Translators and Modules

Perl is bundled with several pod translators that convert pod documents (or the embedded pod in other types of documents) into various formats. All should be 8-bit clean.

pod2text

Converts pod into text. Normally, this text will be 7-bit ASCII, but it will be 8-bit if it had 8-bit input, or specifically ISO-8859-1 (or Unicode) if you use sequences like LE<uacute>thien for Lúthien or EE<auml>rendil for Eärendil.

If you have a file with pod in it, the easiest (although perhaps not the prettiest) way to view just the formatted pod would be:

% pod2text File.pm | more

Then again, pod is supposed to be human readable without formatting.

pod2man

Converts pod into Unix manpage format suitable for viewing through nroff(1) or creating typeset copies via troff(1). For example:

% pod2man File.pm | nroff –man | more

or:

% pod2man File.pm | troff -man -Tps -t > tmppage.ps
% ghostview tmppage.ps

and to print:

% lpr –Ppostscript tmppage.ps

pod2html

Converts pod into HTML for use with your favorite viewer (maybe that’s lynx):

% pod2html --infile=File.pm --outfile-tmppage.html
% lynx tmppage.html

pod2latex

Converts pod into the format, which you can then typeset with that tool.

Additional translators for other formats are available on CPAN.

You should write your pod as close to plain text as you possibly can, with as few explicit markups as you can get away with. It is up to the individual ...