Plain Old Documentation, commonly abbreviated as POD, is a simple platform-independent documentation tool for the computer language Perl. POD may refer to: POD (brand), a brand of digital amplifier and effects modellers Parachute Opening Device, a device that automatically opens a parachute at a certain height when the user doesnt open it manually Pocket Oxford English Dictionary The Path of Daggers, the eighth book of The Wheel... A platform-independent model is a model of a software or business system that is independent of the specific technological platform used to implement it. ... The term computer language is a more expansive and alternate term for the more commonly-used term programming language. ... Perl is a dynamic programming language created by Larry Wall and first released in 1987. ...

Intent

POD is designed to be a simple, clean language with just enough syntax to be useful. It purposefully does not include built-in mechanisms for fonts, images, colors or tables; instead it attempts to be just large enough to be useful. Some of its goals are: For other uses, see Syntax (disambiguation). ... In typography, a typeface is a co-ordinated set of character designs, which usually comprises an alphabet of letters, a set of numerals and a set of punctuation marks. ... Image of the Wikimedia Commons logo. ... Color is an important part of the visual arts. ... A table is a mode of visual communication that maps the logical structure of a set of data into a hierarchical matrix. ...

• Easy to parse
• Easy to convert to other languages, such as HTML or TeX
• Easy to include sample code in
• 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!

Although the author of perlpod notes that "The Pod format is not necessarily sufficient for writing a book", books have in fact been written in an extended version of POD; this special version included formatting codes for tables and footnotes, and is used by O'Reilly & Associates to produce several Perl books, most notably Programming Perl by Larry Wall, Tom Christiansen, and Jon Orwant. A slightly extended, modified version of Pod, called MOD, was used to write Higher-Order Perl, by Mark Jason Dominus. HTML, short for Hypertext Markup Language, is the predominant markup language for the creation of web pages. ... TeX (IPA: as in Greek, often in English; written with a lowercase e in imitation of the logo) is a typesetting system created by Donald Knuth. ... OReilly Media (formerly OReilly & Associates, IPA /əraɪli/) is an American media company established by Tim OReilly, primarily focusing on books related to computer programming. ... Programming Perl book cover Programming Perl, best known as the camel book among hackers, is a book about writing programs or scripts using the Perl programming language. ... Larry Wall Larry Wall (born September 27, 1954) is a programmer, linguist, and author, most widely known for his creation of the Perl programming language in 1987. ... Tom Christiansen (also nicknamed tchrist) is a well-known Unix developer and user especially known for his many contributions to the Perl programming language. ... Higher-Order Perl (Transforming programs with programs), ISBN 1-55860-701-3 (ISBN-13: 978-1-55860-701-9), 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... Mark Jason Dominus (born 1969) is one of the founders of Kibology. ...

Use

POD is the language used for most documentation 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. A Perl module is a discrete component of software for the Perl programming language. ... This article or section should be merged with script programming language In computer applications, a script, roughly speaking, is a computer program that automates the sort of task that a user might otherwise do interactively at the keyboard. ... Parrot is a register-based virtual machine being developed using the C programming language and intended to run dynamic languages efficiently. ...

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. Almost all substantial UNIX and Unix-like operating systems have extensive documentation available as an electronic manual, split into multiple sections called man pages (short for manual pages and based on the command used to display them). ...

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 is designed to ignore POD in Perl code.) An interpreter is a computer program that executes other programs. ... A parser is a computer program or a component of a program that analyses the grammatical structure of an input, with respect to a given formal grammar, a process known as parsing. ...

Sample POD document

This document is syntactically correct POD, which attempts to follow the major conventions on section naming as well.

 =head1 NAME podsample - A sample POD document =head1 SYNOPSIS $here->isa(Piece::Of::Code); print <<"END"; This indented block will not be scanned for formatting codes or directives, and spacing will be preserved. END =head1 DESCRIPTION Here's some normal text. It includes text that is B<bolded>, I<italicized>, U<underlined>, and C<$code>-formatted. =head2 An Example List =over 4 =item * This is a bulleted list. =item * Here's another item. =back 4 =begin html <img src="fig1.png" align="right" alt="Figure 1." /> <p> Here's some embedded HTML. In this block I can include images, apply <span style="color: green"> styles</span>, or do anything else I can do with HTML. POD parsers that aren't outputting HTML will completely ignore it. </p> =end html =head1 SEE ALSO L<perlpod>, L<perldoc>, L<Pod::Parser>. =head1 COPYRIGHT Copyright 2005 J. Random Hacker <jrh@cpan.org>. 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. =cut 

J. Random, followed by a term for a category of people, capitalized, to make an appearance of a personal name, is a placeholder name for an undistinguished, average person from the category, e. ...

POD formatting details

POD files are written in an ASCII-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. There are 95 printable ASCII characters, numbered 32 to 126. ... Look up encoding in Wiktionary, the free dictionary. ... ISO 8859-1, more formally cited as ISO/IEC 8859-1 or less formally as Latin-1, is part 1 of ISO/IEC 8859, a standard character encoding defined by ISO. It encodes what it refers to as Latin alphabet no. ... Unicode is an industry standard designed to allow text and symbols from all of the writing systems of the world to be consistently represented and manipulated by computers. ...

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". For information on the programming language Whitespace, see Whitespace programming language. ... ASCII art, an artistic medium relying primarily on computers for presentation, consists of pictures pieced together from characters (preferably from the 95 printable characters defined by ASCII). ...

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<bolded text>, 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

• Perl
• Larry Wall
• Sean M. Burke

Perl is a dynamic programming language created by Larry Wall and first released in 1987. ... Larry Wall Larry Wall (born September 27, 1954) is a programmer, linguist, and author, most widely known for his creation of the Perl programming language in 1987. ... Sean M. Burke is a Perl programmer with a passion for linguistics. ...

References

• Wall, Larry; Christiansen, Tom; & Orwant, Jon (2000). Programming Perl (3rd ed.). Sebastopol: O'Reilly & Associates. ISBN 0-12-345678-9.

Programming Perl book cover Programming Perl, best known as the camel book among hackers, is a book about writing programs or scripts using the Perl programming language. ...

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 [1].
• The directory [2] contains many modules with embedded POD formatting.
• The Getopt::Euclid module parses input to a Perl script automatically based on POD tags