Skip to content

Instantly share code, notes, and snippets.

@tadzik
Created August 9, 2011 12:07
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save tadzik/1133875 to your computer and use it in GitHub Desktop.
Save tadzik/1133875 to your computer and use it in GitHub Desktop.
┌─[tadzik@yavin4]─[~/src/nom] (nom)*
└─[%]─> ./perl6 --doc S26-mini.pod
TITLE
Synopsis 26 - Documentation
AUTHOR
Damian Conway <L<C<damian@conway.org>|mailto:damian@conway.org>>
VERSION
Maintainer: Damian Conway
Date: 9 Apr 2005
Last Modified: 31 Jul 2010
Pod
D<Pod> is an easy-to-use markup language with a simple, consistent underlying document object model. Pod can be used for writing language documentation, for documenting programs and modules, as well as for other types of document composition.
Pod is an evolution of Perl 5's L<I<Plain Ol' Documentation>|doc:perlpod> (POD) markup. Compared to POD, Perl 6's Pod 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 D<directives|directive>, which are used to declare configuration information and to delimit blocks of textual content. All Pod directives are considered to be special types of comments in Perl 6.
Every directive starts either with an equals sign (C<=>) followed immediately by an identifier N<as specified in Synopsis 2>, or with C<#=> followed immediately by whitespace or an opening bracket.
Directives that start with C<=> can be indented like the code they interleave, but their initial C<=> must still be the first non-whitespace character on their line. Directives that start with C<#=> can be placed anywhere that a Perl 6 comment can appear, though they are meaningful only in a subset of those places; see L<#Declarator blocks>.
An indented Pod block is considered to have a I<virtual left margin>, determined by the indentation of its opening delimiter.
In other words, if a directive is indented from the left margin, the column at which the first character of its opening delimiter appears is thereafter considered the first column of the entire block's contents.
As with Perl 6 heredocs, the virtual margin treats leading tabs as aligning to tabstops spaced every C<($?TABSTOP // 8)> characters.
Pod blocks
The content of a document is specified within one or more D<blocks|block>. Every Pod block may be declared in any of four forms:
L<I<delimited style>|#Delimited blocks>, L<I<paragraph style>|#Paragraph blocks>, L<I<abbreviated style>|#Abbreviated blocks>, or L<I<declarator style>|#Declarator blocks>. The first three forms are all equivalent; the fourth is distinct.
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 C<Pod6::Block::Ambient> block. Renderers will I<usually> ignore such blocks, but see L<#Aliases>.
In Perl 5's POD format, once a POD directive is encountered, the parser considers everything that follows to be POD, until an explicit C<=cut> directive is encountered, at which point the parser flips back to parsing ambient source code. The Perl 6 Pod format is different. All Pod directives have a defined terminator and the 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 C<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>
Delimited blocks
Delimited blocks are bounded by C<=begin> and C<=end> markers, both of which are followed by a valid Perl 6 identifier, which is the D<typename> of the block. Typenames that are entirely lowercase (for example: C<=begin head1>) or entirely uppercase (for example: C<=begin SYNOPSIS>) are reserved.
After the typename, the rest of the C<=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:
Value is... Specify with... Or with... Or with...
Boolean (true) C«:key» C«:key(1)» C«key => 1»
Boolean (false) C«:!key» C«:key(0)» C«key => 0»
String C«:key<str>» C«:key('str')» C«key => 'str'»
List C«:key<1 2 3>» C«:key[1,2,3]» C«key => [1,2,3]»
Hash C«:key{a=>1, b=>2}» C«key => {a=>1, b=>2}»
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment