Editing Plain Old Documentation

{{Short description|Markup language for Perl documentation}}
{{More footnotes needed|date=March 2024}}
'''Plain Old Documentation''' ('''pod''') is a [[lightweight markup language]] used to document the [[Perl]] programming language as well as Perl modules and programs.

==Design==
Pod is designed to be a simple, clean language with just enough syntax to be useful.  It purposefully does not include mechanisms for fonts, images, colors or tables.  Some of its goals are:
* Easy to parse
* Easy to convert to other formats, such as [[XML]], [[TeX]] or [[Markdown]]
* Easy to incorporate sample code
* Easy to read without a pod formatter (i.e. in its source-code form)
* Easy to write in

An extended version of pod that supports tables and footnotes called PseudoPOD has been used by [[O'Reilly & Associates]] to produce several Perl books, most notably ''[[Programming Perl]]'' by [[Larry Wall]], [[Tom Christiansen]], and Jon Orwant.

Pod makes it easy to write [[Manpage|manual pages]], which are well suited to user-oriented documents. In contrast, other documentation systems, such as Python's [[Docstring]] or Java's [[Javadoc]], though they can be used for user documentation, are designed to facilitate generating developer-oriented documentation about the source code for a software project.

==Use==

Pod is the language used for most [[documentation]] in the Perl world. This includes Perl itself, nearly all publicly released [[Perl module|modules]], many [[script (computer programming)|script]]s, most design documents, many articles on [http://www.perl.com/ Perl.com] and other Perl-related web sites,
and the [[Parrot virtual machine]].

Pod is rarely read in the raw, although it is designed to be readable without the assistance of a formatting tool.  Instead, it is read with the {{anchor|perldoc}}perldoc tool, or converted into Unix [[man page]]s or Web-standard HTML pages.

It is also possible to use pod in other contexts than Perl. For example, to add simple documentation to [[Bash (Unix shell)|bash scripts]], which can then be easily converted to man pages.<ref name="pod_in_bash">[http://bahut.alma.ch/2007/08/embedding-documentation-in-shell-script_16.html Embedding POD documentation in a shell script] (retrieved 10 Jan 2011)</ref> Such uses rely on language-specific hacks to hide the pod part(s), such as (in bash) prefixing the POD section with the line <code>:<<=cut</code> which works by calling bash's [[no-op]] <code>:</code> command, with the whole block of Pod as a [[here document]] as input to it.

Pure pod files usually have the extension <code>.pod</code>, but pod is mostly used directly in Perl
code, which typically uses the <code>.pl</code> and <code>.pm</code> extensions.  (The Perl
[[Interpreter (computing)|interpreter]]'s [[parser]] is designed to ignore pod in Perl code.) In source code files, the documentation is generally placed after the <code>__END__</code> marker (which also helps [[syntax highlighting]] in some editors to display it as comments).

Pod can easily be converted to other formats, for example some of the various [[Wiki]] formats like: [[WikiWikiWeb]], [[Kwiki]], [[TWiki]], [[UseModWiki]], [[TiddlyWiki]], [[Textile (markup language)|Textile]], [[MediaWiki]], [[MoinMoin]] or [[Confluence]] using Pod::Simple::Wiki.

==Example==

This document is syntactically correct pod, which attempts to follow the major conventions on section naming as well.<ref>{{cite web|url=http://p3rl.org/perlpodtut|title=perlpodtut|author=Juerd}}</ref>
{{pre|1=
=head1 NAME

{{codett|2=perl|1=My::Module}} - An example module

=head1 SYNOPSIS

    {{codett|2=perl|1=use My::Module;}}
    {{codett|2=perl|1=my $object = My::Module->new();}}
    {{codett|2=perl|1=print $object->as_string;}}

=head1 DESCRIPTION

This module does not really exist, it
was made for the sole purpose of
demonstrating how POD works.

=head2 Methods

=over 12

=item C<new>

Returns a new {{codett|2=perl|1=My::Module}} object.

=item C<as_string>

Returns a stringified representation of
the object. This is mainly for debugging
purposes.

=back

=head1 LICENSE

This is released under the [[Artistic License]]. 
See L<perlartistic>.

=head1 AUTHOR

Juerd - L<<span class="plainlinks">http://juerd.nl/</span>>

=head1 SEE ALSO

L<perlpod>, L<perlpodspec>

=cut
}}

==Formatting details==

Pod files are written in an [[ASCII]]-compatible [[Character encoding|encoding]], such as [[Latin-1]] or [[UTF-8]]. A pod parser always assumes that the file it is parsing doesn't start with pod; it ignores all lines
until it sees a pod directive.  pod directives must come at the beginning of a line, and all begin with an equal sign.  The pod parser will then assume that all following lines are pod, until it encounters a line consisting of the "=cut" directive.  Any content following that is ignored until the parser encounters another pod directive.  Thus, pod can be intermixed with executable source code if the language's parser knows how to recognize and ignore pod.

Pod content is divided into '''paragraphs''' by empty lines.  Paragraphs that begin with [[Whitespace character|whitespace]] characters—tabs or spaces—are considered to be "verbatim paragraphs", and are left completely unformatted; these are used for sample code, [[ASCII art]], etc.  Paragraphs that begin with an equal sign are "command paragraphs"; the sequence of alphanumeric characters immediately following the equal sign is treated as a pod directive, and the rest of the paragraph is formatted according to that directive.  Some directives also affect the following paragraphs.  If a paragraph starts with something besides an equal sign or whitespace, it's considered an "ordinary paragraph".

Both ordinary paragraphs and the contents of command paragraphs are parsed for formatting codes. Formatting in pod is very plain; it's mainly limited to bold, italic, underlined, monospaced, and a few other formats.  There is also a code for linking between pod documents or to another section within the same document.  Formatting codes consist of either:

* A single uppercase letter, followed by a less-than sign (<), the content to be formatted, and a greater-than sign (>), e.g. <code>B<bolded text></code>, ''or''
* A single uppercase letter, two or more less-than signs (<<), a space, the content to be formatted, another space, and the same number of greater-than signs as were used before, e.g. <code>B<< bolded text >></code>.  This form is often used for code snippets containing a greater-than sign, which would otherwise end the formatting code.

Commands in pod include four levels of headings, bulleted and numbered lists, and commands to mark sections as being in another language.  The latter feature allows for special formatting to be given to parsers that support it.

==See also==
* [[Comparison of documentation generators]]

==References==
* Wall, Larry; Christiansen, Tom; & Orwant, Jon (2000). ''[[Programming Perl]]'' (3rd ed.). Sebastopol: O'Reilly & Associates. {{ISBN|0-596-00027-8}}.
* Chapter 15, "Working with Pod", in [[brian d foy|foy, brian d]] (2007). ''[[Mastering Perl]]''. Sebastopol: [[O'Reilly Media]]. {{ISBN|0-596-52724-1}}.
* Section 5.2, "Embedding Documentation in Shell Scripts", in Albing, Carl; Vossen, JP; & Cameron Newham. (2007). ''bash Cookbook: Solutions and Examples for bash Users''; O'Reilly & Associates. {{ISBN|0-596-52678-4}}.
{{Reflist}}

==External links==
* [http://perldoc.perl.org/perlpod.html perlpod (documentation on pod for people writing documents in it)]
* [http://perldoc.perl.org/perlpodspec.html perlpodspec (documentation on pod for people writing parsers for it)]
* [https://metacpan.org/source/RJBS/perl-5.18.1/pod The Perl manpages in raw pod format]
* [ftp://ftp.ora.com/pub/labs/pseudopod.html (PseudoPOD)]{{dead link|date=May 2025|bot=medic}}{{cbignore|bot=medic}}
* [https://metacpan.org/source/RJBS/perl-5.18.1/lib The directory contains many modules with embedded pod formatting]
* The [https://metacpan.org/module/Getopt::Euclid Getopt::Euclid module] parses input to a Perl script automatically based on pod tags
* The [https://metacpan.org/module/Pod::Simple::Wiki Pod::Simple::Wiki] converts pod into various [[Wiki]] formats
* The [https://metacpan.org/pod/Pod::Markdown Pod::Markdown] converts pod into [[Markdown]]

{{Perl}}
{{Document markup languages}}

[[Category:Source code documentation formats]]
[[Category:Lightweight markup languages]]
[[Category:Perl]]