TITLE

Synopsis_26 - Documentation

AUTHOR

Damian Conway <damian@conway.org>

VERSION

Maintainer:     Damian Conway
Date:           9 Apr 2005
Last Modified:  25 Apr 2007

Perldoc

Perldoc is an easy-to-use markup language with a simple, consistent underlying document object model. Perldoc can be used for writing language documentation, for documenting programs and modules, as well as for other types of document composition.

Perldoc allows for multiple syntactic dialects, all of which map onto the same set of standard document objects. The standard dialect is named "Pod".

The Pod Dialect

Pod is an evolution of Perl 5's Plain Ol' Documentation (POD) markup. Compared to Perl 5 POD, Perldoc's Pod dialect is much more uniform, somewhat more compact, and considerably more expressive. The Pod dialect also differs in that it is a purely descriptive mark-up notation, with no presentational components.

General syntactic structure

Pod documents are specified using directives, which are used to declare configuration information and to delimit blocks of textual content. Every directive starts with an equals sign (=) in the first column.

The content of a document is specified within one or more blocks. Every Pod block may be declared in any of three equivalent forms: delimited style, paragraph style, or abbreviated style.

Anything in a document that is neither a Pod directive nor contained within a Pod block is treated as "ambient" material. Typically this would be the source code of the program that the Pod is documenting. Pod parsers still parse this text into the internal representation of the file (representing it as a Perldoc::Block::Ambient block), but renderers will usually ignore such blocks.

In Perl 5's POD format, once a POD directive is encountered, the parser considers everything that follows to be POD, until an explicit =cut directive is encountered, at which point the parser flips between POD and ambient text. The Perl 6 Pod format is different. A Pod parser always reverts to "ambient" at the end of each Pod directive or block. To cause the parser to remain in Pod mode, you must enclose the desired Pod region in a pod block:

B<=begin pod>

=head1 A heading

This is Pod too. Specifically, this is a simple C<para> block

    $this = pod('also');  # Specifically, a code block

B<=end pod>

Alternatively you can indicate an entire file contains only Pod, by giving it a .pod suffix.

Delimited blocks

Delimited blocks are bounded by =begin and =end markers, both of which are followed by a valid identifierA valid identifier is a sequence of alphanumerics and/or underscores, beginning with an alphabetic or underscore, which is the typename of the block. Typenames that are entirely lowercase (for example: =begin head1) or entirely uppercase (for example: =begin SYNOPSIS) are reserved.

After the typename, the rest of the =begin marker line is treated as configuration information for the block. This information is used in different ways by different types of blocks, but is always specified using Perl6-ish option pairs. That is, any of:

All option keys and values must, of course, be constants since Perldoc is a specification language, not a programming language. See Synopsis 2 for details of the various Perl 6 pair notations.

The configuration section may be extended over subsequent lines by starting those lines with an = in the first column followed by a whitespace character.

The lines following the opening delimiter and configuration are the data or contents of the block, which continue until the block's =end marker line. For most block types, these contents may be indented if you wish, without them being treated as code blocks. Unlike Perl 5, indented text is only treated as code within =pod, =nested, =item, =code, and semantic blocks.

The general syntax is: