Perl Cd Bookshelf [Electronic resources] نسخه متنی

26.2. 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:

% pod2html File.pm > tmppagel
% lynx tmppagel
% netscape -remote "openURL(file:`pwd`/tmppagel)"

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.

pod2latex

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

This is a <STRONG>$variable</STRONG> right here

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:

[1]If
you''re designing a general-purpose pod translator, not one for Perl
code, your criteria may vary.

• 
  

  FILEHANDLE
  



• 
  

  $scalar
  



• 
  

  @array
  



• 
  

  function()
  



• 
  

  manpage(3r)
  



• 
  

  somebody@someplace.com
  



• 
  

  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\n";