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.
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.
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
Converts pod into HTML for use with your favorite viewer:
%pod2html File.pm > tmppage.html
%lynx tmppage.html
%netscape -remote "openURL(file:`pwd`/tmppage.html)"
That last one is a netscape hack that works if you already have netscape running somewhere to tell that incarnation to load the page. Otherwise, just call it as you did lynx.
Converts pod into [LaTeX].
Additional translators are available on CPAN for other formats.
Translators exhibit different default behaviors depending on the output format. For instance, if your pod has a prose paragraph saying:
This is a $variable right here
then pod2html will turn that into:
This is a <STRONG>$variable</STRONG> right here
but pod2text will leave it unadorned, since the dollar should be enough to let it be read.
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 translator to decide how things in your text should be represented. That means letting the translator figure out how to create paired quotes, how to fill and adjust text, how to find a smaller font for words in all capitals, etc. Since these were written to process Perl documentation, most translators[1] should also recognize unadorned items like these and render them appropriately:
FILEHANDLE
$scalar
@array
function()
manpage(3r)
http://foo.com/
Perl also comes with several standard modules for parsing and
converting pod, including Pod::Checker
(and the
associated podchecker utility) for checking the
syntax of pod documents, Pod::Find
for finding pod
documents in directory trees, and Pod::Parser
for
creating your own pod utilities.
Note that pod translators should only look at paragraphs beginning with a pod directive (this makes parsing easier), whereas the compiler actually knows to look for pod escapes even in the middle of a paragraph. This means that the following secret stuff will be ignored by both the compiler and the translators.
$a=3; =secret stuff warn "Neither POD nor CODE!?" =cut back print "got $a ";
You probably shouldn't rely upon the warn
being podded out forever. Not all pod translators are well-behaved in
this regard, and the compiler may someday become pickier.
[1] If you're designing a general-purpose pod translator, not one for Perl code, your criteria may vary.