Perldoc and POD

Author: John M. Gabriele | back to index

Perldoc and POD

• Perl 6 Perldoc
• Quick Pod tips
• Using Perl 5's pod2html

---

Perl 6 Perldoc

Perl 5 POD has been updated for Perl 6 by Damian Conway. The new Perl 6 Pod (note capitalization) is called Perldoc, or just Pod for short.

The relevant module you want to install on your Perl 5 system is Perl6::Perldoc.

The new command for converting to xhtml is perldoc2xhtml. There's also a perldoc2text command. After installing Perl6::Perldoc, the first thing you probably want to do is convert the S26.pod6 doc to html for easy reading.

Quick Pod tips

A few quick notes on Pod:

• Formatting codes are sometimes also equivalent to a given type of block:

  Formatting code	block type
  C<>	code
  K<>	input
  T<>	output
  Z<>	comment

• =para blocks can be useful if you want to add configuration to a given paragraph:

  =begin para :formatted<B>
  Warning! Do not press the blue button!
  =end para
  

• "nested" is not just shorthand for "para :nested". If you want a blockquote, use a nested block. And, as you'd expect, one level of nesting == one level of indenting.

• You can turn on section numbering at the beginning of your document, you you like:

  =config head1 :numbered
  =config head2 :numbered
  =config head3 :numbered
  =config head4 :numbered
  

• The block data for an abbreviated block can spill over into additional lines, if necessary.

• If you want to add configuration information for a block, you've got to use either delimited style or paragraph -- not abbreviated style.

• X<> is for generating index entries, but it doesn't seem that the current perldoc2xhtml tool generates an index... (?)

• There doesn't seem to be a built-in way to

  • put in a horizontal rule (line)
  • center or right-align text

  At the moment, I don't see a way to pass html directly to the xhtml renderer... (TODO)

• You can often use Z<> to get a little extra horizontal whitespace in your html output, for example, after the last item of a sub-list (to visually separate it from the next outer list item).

Using Perl 5's pod2html

Regarding Perl 5's POD, to make one big single html page:

pod2html --title='foo' --outfile=foo.html --css=path/to/foo.css foo.pod

If you want, you can browse a long page right in your terminal window:

pod2html --outfile=/tmp/foo.html foo.pod; lynx /tmp/foo.html

The benefits with that being the handy table of contents navigation menu you get at the top of the screen, and possibly a colorized display.