What is POD
• Plain Old Documentation.
• Perl's markup language for documentation.
• Semantic markup.
• Simple.
o "The intent is simplicity of use, not power of expression."
• Can be embedded within Perl code.
Reading POD
• perldoc command
o Refer to module documentation: perldoc Pod::Simple
o Refer to a specific file containing POD: perldoc example.pod
• perldoc.perl.org
• CPAN - http://search.cpan.org/perldoc?Test::Pod
• Text editor
o Most POD is readable as-is, without any formatting.
o Useful when you're reading the source of a module with embedded documentation.
Writing POD
• Can be embedded in with your code.
o Some authors put it after an __END__ cut mark so perl can just ignore it.
o No real performance hit from having POD inline.
o May be advantages to having documentation next to the code it's documenting.
• Can be included in a separate .pod file.
Example
This serves as an example
=head1 SYNOPSIS
my $example = "code";
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.
o 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.
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
=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<...> - italic
B<...> - bold
C<...> - code
F<...> - filename
S<...> - 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.
Links
• L<name> - link to a Perl manual page
• L<name/"section"> - link to a section in another manual page
• L</"section"> - section in this POD document
o Sections are started by =item or =head commands.
• L<uri> - link to a URI
Formatting codes
Links with text
• L<text|name>, L<text|name/"sec"> - use "text" as the link
• Formatting codes
• 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.
o Name
o Version
o Synopsis
o Description
o Subroutines/Methods/Interface
o Diagnostics
o Configuration and environment
o Dependencies
o Incompatibilities
o Bugs and limitations
o Author
o License and copyright
o Disclaimer of warranty
• Use some, all, or none....
Suggested sections
Perl programs
• Suggested by Damian Conway in Perl Best Practices.
o Name
o Usage
o Description
o Required arguments
o Options
o Exit status
o Diagnostics
o Configuration
o Dependencies
o Incompatibilities
o Bugs and limitations
o Author
o License and copyright
o Disclaimer of warranty
• Use some, all, or none....
What is POD
• Plain Old Documentation.
• Perl's markup language for documentation.
• Semantic markup.
• Simple.
o "The intent is simplicity of use, not power of expression."
• Can be embedded within Perl code.
Reading POD
• perldoc command
o Refer to module documentation: perldoc Pod::Simple
o Refer to a specific file containing POD: perldoc example.pod
• perldoc.perl.org
• CPAN - http://search.cpan.org/perldoc?Test::Pod
• Text editor
o Most POD is readable as-is, without any formatting.
o Useful when you're reading the source of a module with embedded documentation.
Writing POD
• Can be embedded in with your code.
o Some authors put it after an __END__ cut mark so perl can just ignore it.
o No real performance hit from having POD inline.
o May be advantages to having documentation next to the code it's documenting.
• Can be included in a separate .pod file.
Example
This serves as an example
=head1 SYNOPSIS
my $example = "code";
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.
o 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.
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
=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<...> - italic
B<...> - bold
C<...> - code
F<...> - filename
S<...> - 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.
Links
• L<name> - link to a Perl manual page
• L<name/"section"> - link to a section in another manual page
• L</"section"> - section in this POD document
o Sections are started by =item or =head commands.
• L<uri> - link to a URI
Formatting codes
Links with text
• L<text|name>, L<text|name/"sec"> - use "text" as the link
• Formatting codes
• 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.
o Name
o Version
o Synopsis
o Description
o Subroutines/Methods/Interface
o Diagnostics
o Configuration and environment
o Dependencies
o Incompatibilities
o Bugs and limitations
o Author
o License and copyright
o Disclaimer of warranty
• Use some, all, or none....
Suggested sections
Perl programs
• Suggested by Damian Conway in Perl Best Practices.
o Name
o Usage
o Description
o Required arguments
o Options
o Exit status
o Diagnostics
o Configuration
o Dependencies
o Incompatibilities
o Bugs and limitations
o Author
o License and copyright
o Disclaimer of warranty
• Use some, all, or none....
No comments:
Post a Comment