Plain Old Documentation
Encyclopedia
Plain Old Documentation, abbreviated pod, is a lightweight markup language
used to document the Perl
programming language.
An extended version of pod that supports tables and footnotes has been used by O'Reilly & Associates to produce several Perl books, most notably Programming Perl
by Larry Wall
, Tom Christiansen, and Jon Orwant. Mark Jason Dominus
used a modified version called mod to write Higher-Order Perl
.
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
, though can be used for user documentation, are designed to facilitate generating developer-oriented documentation about the source code for a software project.
in the Perl world. This includes Perl itself, nearly all publicly-released modules
, many scripts, most design documents, many articles on 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 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. Such uses rely on language-specific hacks to hide the pod part(s).
Pure pod files usually have the extension
code, which typically uses the
interpreter
's parser is designed to ignore pod in Perl code.) In source code files, the documentation is generally placed after the
section naming as well.
-compatible encoding
, such as Latin-1 or Unicode
. 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:
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.
Lightweight markup language
A lightweight markup language is a markup language with a simple syntax, designed to be easy for a human to enter with a simple text editor, and easy to read in its raw form....
used to document the Perl
Perl
Perl is a high-level, general-purpose, interpreted, dynamic programming language. Perl was originally developed by Larry Wall in 1987 as a general-purpose Unix scripting language to make report processing easier. Since then, it has undergone many changes and revisions and become widely popular...
programming language.
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 languages, such as XMLXMLExtensible Markup Language is a set of rules for encoding documents in machine-readable form. It is defined in the XML 1.0 Specification produced by the W3C, and several other related specifications, all gratis open standards....
or TeXTeXTeX is a typesetting system designed and mostly written by Donald Knuth and released in 1978. Within the typesetting system, its name is formatted as .... - Easy to incorporate sample code
- Easy to read without a pod formatter (i.e. in its source-code form)
- Easy to write in—otherwise programmers won't write the documentation!
An extended version of pod that supports tables and footnotes has been used by O'Reilly & Associates to produce several Perl books, most notably Programming Perl
Programming Perl
Programming Perl, ISBN 0-596-00027-8,best known as the Camel Book among programmers, is a book and ebook about writing programs using the Perl programming language, revised as several editions to reflect major language changes since Perl version 4. Editions have been co-written by the creator of...
by Larry Wall
Larry Wall
Larry Wall is a programmer and author, most widely known for his creation of the Perl programming language in 1987.-Education:Wall earned his bachelor's degree from Seattle Pacific University in 1976....
, Tom Christiansen, and Jon Orwant. Mark Jason Dominus
Mark Jason Dominus
Mark•Jason Dominus is one of the founders of Kibology and a leading Perl programmer. He was the managing editor of and was a columnist for The Perl Journal for several years. Mark's other Perl-related articles have appeared in magazines such as Wired and IEEE Software...
used a modified version called mod to write Higher-Order Perl
Higher-Order Perl
Higher-Order Perl , ISBN 1-55860-701-3 , is a book written by Mark Jason Dominus with the goal to teach Perl programmers with a strong C and Unix background how to use techniques with roots in functional programming languages like Lisp that are available in Perl as well, but less known. The book is...
.
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
Docstring
In programming, a docstring is a string literal specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, or even specifically formatted comments like Javadoc documentation, docstrings are not stripped from the source...
or Java's Javadoc
Javadoc
Javadoc is a documentation generator from Sun Microsystems for generating API documentation in HTML format from Java source code.The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some IDEs, such as Netbeans and Eclipse automatically generate...
, though 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 documentationDocumentation
Documentation is a term used in several different ways. Generally, documentation refers to the process of providing evidence.Modules of Documentation are Helpful...
in the Perl world. This includes Perl itself, nearly all publicly-released modules
Perl module
A Perl module is a discrete component of software for the Perl programming language. Technically, it is a particular set of conventions for using Perl's package mechanism that has become universally adopted....
, many scripts, most design documents, many articles on Perl.com and other Perl-related web sites,
and the Parrot virtual machine
Parrot virtual machine
Parrot is a register-based process virtual machine designed to run dynamic languages efficiently. It uses just-in-time compilation for speed to reduce the interpretation overhead. It is currently possible to compile Parrot assembly language and PIR to Parrot bytecode and execute it...
.
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. Such uses rely on language-specific hacks to hide the pod part(s).
Pure pod files usually have the extension
.pod, but pod is mostly used directly in Perlcode, which typically uses the
.pl and .pm extensions. (The Perlinterpreter
Interpreter (computing)
In computer science, an interpreter normally means a computer program that executes, i.e. performs, instructions written in a programming language...
's parser 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).Sample pod document
This document is syntactically correct pod, which attempts to follow the major conventions onsection naming as well.
| Source | HTML result |
|---|---|
| =head1 NAME | NAMEpodsample - A sample pod document SYNOPSIS
DESCRIPTIONHere's some normal text. It includes text that is bolded, italicized, underlined, and $code-formatted.An Example List
Here's some embedded HTML. In this block I can include images, apply styles, or do anything else I can do with HTML. pod parsers that aren't outputting HTML will completely ignore it. SEE ALSOperlpod, perldoc, the Pod::Parser manpage. COPYRIGHTCopyright 2005 J. Random Hacker. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. |
pod formatting details
pod files are written in an ASCIIASCII
The American Standard Code for Information Interchange is a character-encoding scheme based on the ordering of the English alphabet. ASCII codes represent text in computers, communications equipment, and other devices that use text...
-compatible encoding
Character encoding
A character encoding system consists of a code that pairs each character from a given repertoire with something else, such as a sequence of natural numbers, octets or electrical pulses, in order to facilitate the transmission of data through telecommunication networks or storage of text in...
, such as Latin-1 or Unicode
Unicode
Unicode is a computing industry standard for the consistent encoding, representation and handling of text expressed in most of the world's writing systems...
. 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
ASCII art
ASCII art is a graphic design technique that uses computers for presentation and consists of pictures pieced together from the 95 printable characters defined by the ASCII Standard from 1963 and ASCII compliant character sets with proprietary extended characters...
, 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
- PerlPerlPerl is a high-level, general-purpose, interpreted, dynamic programming language. Perl was originally developed by Larry Wall in 1987 as a general-purpose Unix scripting language to make report processing easier. Since then, it has undergone many changes and revisions and become widely popular...
- Larry WallLarry WallLarry Wall is a programmer and author, most widely known for his creation of the Perl programming language in 1987.-Education:Wall earned his bachelor's degree from Seattle Pacific University in 1976....
- DocstringDocstringIn programming, a docstring is a string literal specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, or even specifically formatted comments like Javadoc documentation, docstrings are not stripped from the source...
– Python documentation - Comparison of documentation generators
External links
- perlpod (documentation on pod for people writing documents in it)
- perlpodspec (documentation on pod for people writing parsers for it)
- The Perl manpages in raw pod format can be viewed at http://search.cpan.org/src/NWCLARK/perl-5.8.9/pod/.
- The directory http://search.cpan.org/src/NWCLARK/perl-5.8.9/lib/ contains many modules with embedded pod formatting.
- The Getopt::Euclid module parses input to a Perl script automatically based on pod tags