Documenting Perl code with POD
Ian Malpass
Frozen Perl
February 2008
What is POD
- Plain Old Documentation.
- Perl's markup language for documentation.
- Semantic markup.
- Simple.
- "The intent is simplicity of use, not power of expression."
- Can be embedded within Perl code.
Reading POD
perldoc command
- Refer to module documentation:
perldoc Pod::Simple
- Refer to a specific file containing POD:
perldoc example.pod
perldoc.perl.org- CPAN - http://search.cpan.org/perldoc?Test::Pod
- Text editor
- Most POD is readable as-is, without any formatting.
- Useful when you're reading the source of a module with embedded documentation.
Writing POD
- Can be embedded in with your code.
- Some authors put it after an
__END__ cut mark so perl can just ignore it.
- No real performance hit from having POD inline.
- May be advantages to having documentation next to the code it's documenting.
- Can be included in a separate .pod file.
Example
=head1 SYNOPSIS
my $example = "code";
This serves as an example
Paragraphs
- ordinary
- verbatim
- command
Ordinary paragraphs
- Just a block of text.
- Minimal reformatting by POD reader.
- When writing POD, paragraphs are separated by one or more blank lines.
Example
This is an ordinary paragraph - just a regular block of text to be
rendered as the POD translator likes.
Verbatim paragraphs
- No formatting.
- Fixed width font.
- Used for code examples, etc.
- Paragraph starts with whitespace.
- Very easy to indent a block of text you don't intend to be verbatim.
Example
This is an ordinary paragraph...
...and this is a verbatim paragraph
Command paragraphs
- Begin with
=
- Specify special formatting of chunks of text.
- Commands need to be preceded by a blank line so that the POD parser recognises them as commands.
Starting and finishing POD
=pod
- Perl interpreter recognises POD command paragraphs and starts skipping the documentation.
=pod is only necessary if POD starts with something other than a command (i.e. a normal or verbatim paragraph).
=cut
- Ends a POD block.
- Perl interpreter starts processing code again.
Headings
=head1, =head2, =head3, =head4- Different levels of headings - most prominent to least.
- 3 & 4 might not work with older POD readers.
Example
=head1 This is a level 1 heading
This is an ordinary paragraph, for reference.
=head2 This is a level 2 heading
This is a verbatim block.
Lists
- Start with
=over n
- n is the number of spaces to indent the list by.
- Default n is 4.
- n may be ignored by the POD translator.
- Start each item with
=item
=item * - bullets=item 1. - numbered list=item foo - list
- Finish with
=back
Example: bullets
=over 4
=item * Item one
Some text.
=item * Item two
=back
Example: numbers
=over 4
=item 1. Item one
Some text.
=item 2. Item two
=back
Example: plain list
=over 4
=item Item one
Some text.
=item Item two
=back
Formatting codes
Text formatting
- Additional formatting done with formatting codes.
- Formatting codes have a capital letter, followed by <, followed by the text to format, and finished with >.
- Text styling codes:
I<...> - italicB<...> - boldC<...> - codeF<...> - filenameS<...> - contains non-breaking spaces
Example: text formatting
Some some text containing I<italic>, B<bold>, C<code>, F<filename>, and
S<non-breaking space> formatting codes.
Character escapes
- Allow you to include special or unusual characters.
E<lt> - "<"
- Optional, except when following a capital letter
E<gt> - ">", E<verbar> - "|", E<sol> - "/"
- Optional, except when used inside a formatting code.
E<htmlname> - htmlname is an HTML entity name, e.g. "quot" for a quote mark.E<charcode> - decimal character code
- Documentation says you can use hex or octal character codes, but some POD translators have difficulty with them.
Example: character escapes
An example of EE<lt>ltE<gt> and EE<lt>gtE<gt>. And some character
escapes: E<quot>A mE<248>E<248>se once bit my sister.E<quot>
Links
L<name> - link to a Perl manual pageL<name/"section"> - link to a section in another manual pageL</"section"> - section in this POD document
- Sections are started by
=item or =head commands.
L<uri> - link to a URI
Example: links
=head1 Internal
See section L</"External">.
=head1 External
See L<Pod::Simple>, or more specifically L<Pod::Simple/"DESCRIPTION">,
or email L<mailto:jbloggs@example.com>.
Links with text
L<text|name>, L<text|name/"sec"> - use "text" as the link
Example: links with text
You can specify L<a link to Pod::Simple|Pod::Simple>, or more specifically
a link to Pod::Simple's L<description section|Pod::Simple/"DESCRIPTION">,
or you can suggest they email L<the author|mailto:jbloggs@example.com>.
Mixing code and documentation
package Example;
=head1 NAME
An example package
=head1 METHODS
=head2 eg
Returns the string "example".
=cut
sub eg { return "example" }
=head2 lipsum
Returns the string "lipsum".
=cut
sub lipsum { return "lorem ipsum" }
Suggested sections
Perl libraries
- Suggested by Damian Conway in Perl Best Practices.
- Name
- Version
- Synopsis
- Description
- Subroutines/Methods/Interface
- Diagnostics
- Configuration and environment
- Dependencies
- Incompatibilities
- Bugs and limitations
- Author
- License and copyright
- Disclaimer of warranty
- Use some, all, or none....
Perl programs
- Suggested by Damian Conway in Perl Best Practices.
- Name
- Usage
- Description
- Required arguments
- Options
- Exit status
- Diagnostics
- Configuration
- Dependencies
- Incompatibilities
- Bugs and limitations
- Author
- License and copyright
- Disclaimer of warranty
- Use some, all, or none....
See also
perldoc perlpodperldoc perlpodspec
![[previous]](images/previous.gif){kind=small}
![[next]](images/next.gif){kind=small}