 | This article includes a list of general references, but it lacks sufficient corresponding inline citations .(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.
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:
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 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.
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.
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. [1] 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 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 formats like: WikiWikiWeb, Kwiki, TWiki, UseModWiki, TiddlyWiki, Textile, MediaWiki, MoinMoin or Confluence using Pod::Simple::Wiki.
This document is syntactically correct pod, which attempts to follow the major conventions on section naming as well. [2]
=head1 NAMEMy::Module - An example module=head1 SYNOPSIS use My::Module; my $object = My::Module->new(); print $object->as_string;=head1 DESCRIPTIONThis module does not really exist, itwas made for the sole purpose ofdemonstrating how POD works.=head2 Methods=over 12=item C<new>Returns a new My::Module object.=item C<as_string>Returns a stringified representation ofthe object. This is mainly for debuggingpurposes.=back=head1 LICENSEThis is released under the Artistic License. See L<perlartistic>.=head1 AUTHORJuerd - L<http://juerd.nl/>=head1 SEE ALSOL<perlpod>, L<perlpodspec>=cutPod files are written in an ASCII-compatible 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 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:
B<bolded text>, orB<< 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.
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".
YAML(see § History and name) is a human-readable data serialization language. It is commonly used for configuration files and in applications where data is being stored or transmitted. YAML targets many of the same communications applications as Extensible Markup Language (XML) but has a minimal syntax that intentionally differs from Standard Generalized Markup Language (SGML). It uses Python-style indentation to indicate nesting and does not require quotes around most string values.
Doxygen is a documentation generator and static analysis tool for software source trees. When used as a documentation generator, Doxygen extracts information from specially-formatted comments within the code. When used for analysis, Doxygen uses its parse tree to generate diagrams and charts of the code structure. Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code.
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.
A delimiter is a sequence of one or more characters for specifying the boundary between separate, independent regions in plain text, mathematical expressions or other data streams. An example of a delimiter is the comma character, which acts as a field delimiter in a sequence of comma-separated values. Another example of a delimiter is the time gap used to separate letters and words in the transmission of Morse code.
In the written form of many languages, indentation describes empty space, a.k.a. white space, used around text to signify an important aspect of the text such as:
A lightweight markup language (LML), also termed a simple or humane markup language, is a markup language with simple, unobtrusive syntax. It is designed to be easy to write using any generic text editor and easy to read in its raw form. Lightweight markup languages are used in applications where it may be necessary to read the raw document as well as the final rendered output.
Raku is a member of the Perl family of programming languages. Formerly known as Perl 6, it was renamed in October 2019. Raku introduces elements of many modern and historical languages. Compatibility with Perl was not a goal, though a compatibility mode is part of the specification. The design process for Raku began in 2000.
An INI file is a configuration file for computer software that consists of a text-based content with a structure and syntax comprising key–value pairs for properties, and sections that organize the properties. The name of these configuration files comes from the filename extension INI, for initialization, used in the MS-DOS operating system which popularized this method of software configuration. The format has become an informal standard in many contexts of configuration, but many applications on other operating systems use different file name extensions, such as conf and cfg.
LAMP is an acronym denoting one of the most common software stacks for the web's most popular applications. Its generic software stack model has largely interchangeable components.
Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber and Aaron Swartz created Markdown in 2004 as a markup language that is intended to be easy to read in its source code form. Markdown is widely used for blogging and instant messaging, and also used elsewhere in online forums, collaborative software, documentation pages, and readme files.
In computing, a shebang is the character sequence consisting of the characters number sign and exclamation mark at the beginning of a script. It is also called sharp-exclamation, sha-bang, hashbang, pound-bang, or hash-pling.
Raku rules are the regular expression, string matching and general-purpose parsing facility of the Raku programming language, and are a core part of the language. Since Perl's pattern-matching constructs have exceeded the capabilities of formal regular expressions for some time, Raku documentation refers to them exclusively as regexes, distancing the term from the formal definition.
This comparison of programming languages compares the features of language syntax (format) for over 50 computer programming languages.
In computer programming, a comment is a programmer-readable explanation or annotation in the source code of a computer program. They are added with the purpose of making the source code easier for humans to understand, and are generally ignored by compilers and interpreters. The syntax of comments in various programming languages varies considerably.
RDoc, designed by Dave Thomas, is an embedded documentation generator for the Ruby programming language. It analyzes Ruby source code, generating a structured collection of pages for Ruby objects and methods. Code comments can be added in a natural style. RDoc is included as part of the Ruby core distribution. The RDoc software and format are successors to the Ruby Document format.
Sean Michael Burke is a Perl programmer, author, and linguist. He was a columnist for The Perl Journal from 1998 and has written several dozen Perl modules for CPAN, as well as books for O'Reilly Media.
Doxia is a content generation framework that provides its users with powerful techniques for generating static and dynamic content. Doxia can be used in web-based publishing context to generate static sites, in addition to being incorporated into dynamic content generation systems like blogs, wikis and content management systems. Doxia is now a subproject of Apache Maven which uses it to convert APT markup documentation into HTML or other formats.
The following outline is provided as an overview of and topical guide to the Perl programming language: