Search notes:

Perl: Plain Old Documents (POD)

perldoc perlpod

Setting encoding

=encoding utf8

Structuring documents with sections

Documents are structured with =headN (N = 1 … 4) 
=head1 Title

Some text. 

More text

    # code is indented by 4 spaces
    my $foo = 'bar';

=cut
Note: the empty line after =headN seems important.
The recommended order of sections (=head1) in a Perl module is:
  • NAME
  • SYNOPSIS
  • DESCRIPTION (of module)
  • Description of methods in module
  • BUGS/CAVEATS
  • AUTHOR
  • SEE ALSO
  • COPYRIGHT and LICENSE
Compare with the usual structure of a man page.

Items

=over indent-level

=item * foo

Optional text for item foo

=item * bar

Optional text for item bar

=item * baz

=back
The optional number indent-level specifies how far (in Ms) the text should be indented. Can be ignored.

Formatting text

I<italic>, B<bold>, C<code>, E<lt>, E<gt>, E<verbar>, E<sol>,
F<filename.txt> S<text with no breaking spaces>
Formatting text that contains < or > is possible using double brackets: << … >>: 
<< if (a < b) >>
Note: the space after << and before >> is ignored.

Hyperlinks

L<http://www.example.xyz/foo/bar.html>
L<link text|http://www.example.xyz/foo.bar.html>
L<Module::Name>
L<Module::Name/section>

Index entries

X<index entry one>
X<another index entry>

Index