Herbert Breunung > Perl6-Doc > Synopsis_26

Download:
Perl6-Doc-0.36.tar.gz

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Source  

NAME ^

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:

syntax highlighting: