Plain Old Documentation (pod) is a
lightweight markup language used to document the
Perl
Perl is a high-level, general-purpose, interpreted, dynamic programming language. Though Perl is not officially an acronym, there are various backronyms in use, including "Practical Extraction and Reporting Language".
Perl was developed ...
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
Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing data. It defines a set of rules for encoding electronic document, documents in a format that is both human-readable and Machine-r ...
,
TeX
Tex, TeX, TEX, may refer to:
People and fictional characters
* Tex (nickname), a list of people and fictional characters with the nickname
* Tex Earnhardt (1930–2020), U.S. businessman
* Joe Tex (1933–1982), stage name of American soul singer ...
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
Larry Arnold Wall (born September 27, 1954) is an American computer programmer, linguist, and author known for creating the Perl programming language and the patch tool.
Early life and education
Wall grew up in Los Angeles and Bremerton, Wash ...
,
Tom Christiansen, and Jon Orwant.
Pod makes it easy to write
manual pages, which are well suited to user-oriented documents. In contrast, other documentation systems, such as Python's
Docstring or Java's
Javadoc
Javadoc (also capitalized as JavaDoc or javadoc) is an API documentation generator for the Java programming language. Based on information in Java source code, Javadoc generates documentation formatted as HTML and other formats via extensions. ...
, 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
Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance, and use. As a form of knowledge managem ...
in the Perl world. This includes Perl itself, nearly all publicly released
modules, many
scripts, most design documents, many articles o
Perl.comand other Perl-related web sites,
and the
Parrot virtual machine
Parrot is a discontinued register-based process virtual machine designed to run dynamic languages efficiently. It is possible to compile Parrot assembly language and Parrot intermediate representation (PIR, an intermediate language) to Parr ...
.
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 perldoc tool, or converted into Unix
man pages 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 scripts, which can then be easily converted to man pages.
[Embedding POD documentation in a shell script](_blank)
(retrieved 10 Jan 2011) Such uses rely on language-specific hacks to hide the pod part(s), such as (in bash) prefixing the POD section with the line
:<<=cut
which works by calling bash's
no-op :
command, with the whole block of Pod as a
here document as input to it.
Pure pod files usually have the extension
.pod
, but pod is mostly used directly in Perl
code, which typically uses the
.pl
and
.pm
extensions. (The Perl
interpreter's
parser
Parsing, syntax analysis, or syntactic analysis is a process of analyzing a string of symbols, either in natural language, computer languages or data structures, conforming to the rules of a formal grammar by breaking it into parts. The term '' ...
is designed to ignore pod in Perl code.) In source code files, the documentation is generally placed after the
__END__
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
A wiki ( ) is a form of hypertext publication on the internet which is collaboratively edited and managed by its audience directly through a web browser. A typical wiki contains multiple pages that can either be edited by the public or l ...
formats like:
WikiWikiWeb,
Kwiki,
TWiki,
UseModWiki,
TiddlyWiki,
Textile
Textile is an Hyponymy and hypernymy, umbrella term that includes various Fiber, fiber-based materials, including fibers, yarns, Staple (textiles)#Filament fiber, filaments, Thread (yarn), threads, and different types of #Fabric, fabric. ...
,
MediaWiki
MediaWiki is free and open-source wiki software originally developed by Magnus Manske for use on Wikipedia on January 25, 2002, and further improved by Lee Daniel Crocker,mailarchive:wikipedia-l/2001-August/000382.html, Magnus Manske's announc ...
,
MoinMoin or
Confluence
In geography, a confluence (also ''conflux'') occurs where two or more watercourses join to form a single channel (geography), channel. A confluence can occur in several configurations: at the point where a tributary joins a larger river (main ...
using Pod::Simple::Wiki.
Example
This document is syntactically correct pod, which attempts to follow the major conventions on section naming as well.
Formatting details
Pod files are written in an
ASCII
ASCII ( ), an acronym for American Standard Code for Information Interchange, is a character encoding standard for representing a particular set of 95 (English language focused) printable character, printable and 33 control character, control c ...
-compatible
encoding
In communications and Data processing, information processing, code is a system of rules to convert information—such as a letter (alphabet), letter, word, sound, image, or gesture—into another form, sometimes data compression, shortened or ...
, such as
Latin-1 or
UTF-8
UTF-8 is a character encoding standard used for electronic communication. Defined by the Unicode Standard, the name is derived from ''Unicode Transformation Format 8-bit''. Almost every webpage is transmitted as UTF-8.
UTF-8 supports all 1,112,0 ...
. 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 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.
B
, ''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.
B<< bolded text >>
. 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. .
* Chapter 15, "Working with Pod", in
foy, brian d (2007). ''
Mastering Perl''. Sebastopol:
O'Reilly Media
O'Reilly Media, Inc. (formerly O'Reilly & Associates) is an American learning company established by Tim O'Reilly that provides technical and professional skills development courses via an online learning platform. O'Reilly also publishes b ...
. .
* 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. .
External links
perlpod (documentation on pod for people writing documents in it)*
ttps://metacpan.org/source/RJBS/perl-5.18.1/pod The Perl manpages in raw pod format*
tp://ftp.ora.com/pub/labs/pseudopod.html (PseudoPOD)The directory contains many modules with embedded pod formatting* Th
Getopt::Euclid moduleparses input to a Perl script automatically based on pod tags
* Th
Pod::Simple::Wikiconverts pod into various
Wiki
A wiki ( ) is a form of hypertext publication on the internet which is collaboratively edited and managed by its audience directly through a web browser. A typical wiki contains multiple pages that can either be edited by the public or l ...
formats
* Th
Pod::Markdownconverts pod into
Markdown
{{Document markup languages
Source code documentation formats
Lightweight markup languages
Perl