/ 
Perl6-Doc-0.34_1
River stage one • 2 direct dependents • 2 total dependents
/ Synopsis_26

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:

4 POD Errors

The following errors were encountered while parsing the POD:

Around line 44:

Deleting unknown formatting code D<>

Around line 48:

Deleting unknown formatting code D<>

Around line 101:

Non-ASCII character seen before =encoding in 'C«:key»'. Assuming UTF-8

Around line 2222:

'=end table :nested' is invalid. (Stack: =begin code; =begin code; =begin code; =begin item; =begin nested; =begin nested; =begin nested; =begin code; =begin code; =begin code; =begin code; =begin code; =begin code; =begin nested; =begin nested; =begin nested; =begin nested; =begin nested; =begin nested; =begin nested; =begin nested; =begin nested; =begin code; =begin nested; =begin code; =begin code; =begin nested; =begin item; =begin item; =begin code; =begin code; =begin code; =begin nested; =begin code; =begin code; =begin item; =begin item; =begin item; =begin code; =begin item; =begin code; =begin code; =begin nested; =begin nested; =begin nested; =begin code; =begin table)