Synopsis_26 - Documentation
Damian Conway <
Maintainer: Damian Conway Date: 9 Apr 2005 Last Modified: 25 Apr 2007
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".
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.
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.
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