POD

Plain Ol' Documentation

Inline documentation & formatting

POD allows you to create documentation with markup in your Perl code.If you've seen Javadoc or PHPdoc,it's like that.Rather,Javadoc and PHPdoc are like POD.

Except that POD is part of the language,not an add-on spec.

Create headings with =head1 and =head2

  1.     =head1 MOST IMPORTANT
  2.  
  3.     Blah blah
  4.  
  5.     =head2 Subheading
  6.  
  7.     blah blah
  8.  
  9.     =head2 Subhading
  10.  
  11.     blah blah

Create unordered lists

To create this list:

  • Wango
  • Tango
  • Fandango

Use

  1.     =over
  2.  
  3.     =item * Wango
  4.  
  5.     =item * Tango
  6.  
  7.     =item * Fandango
  8.  
  9.     =back

Create ordered lists

To create this list:

  • 1 Visit perl101.org
  • 2 ???
  • 3 Profit!

Use

  1.     =over
  2.  
  3.     =item 1 Visit perl101.org
  4.  
  5.     =item 2 ???
  6.  
  7.     =item 3 Profit!
  8.  
  9.     =back

Use inline markup styles

POD uses B<>, I<> and C<> for bold, italics and code, respectively.

  1.     B<This is bolded>
  2.  
  3.     I<This is italics>
  4.  
  5.     C<This is code>

Your markup formats can nest.

Link with L<>

The L<> links either to keywords in your document, as in L<Methods>, or to a specific URL, as in L<http://search.cpan.org&gt;.

Paragraph mode vs. literal blocks

Everything in a paragraph word-wraps automatically. A paragraph is separated by at least one blank line.

  1.     A literal block is indented at least one space
  2.     and does not
  3.     get
  4.     wrapped.

This came from:

  1.     Everything in a paragraph word-wraps automatically.  A paragraph
  2.     is separated by at least one blank line.
  3.  
  4.         A literal block is indented at least one space
  5.         and does not
  6.         get
  7.         wrapped.

POD does not make anything run slower.

It's stripped out at compile time.

TODO

Talk about double-bracketing

Want to contribute?

Submit a PR to github.com/petdance/perl101