A heading

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

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

=end pod </pre></blockquote>Alternatively you can indicate an entire file contains only Pod, by giving it a <code>.pod</code> suffix. <h3><a name="Delimited blocks"><a name="25832096">Delimited blocks </a></a></h3> Delimited blocks are bounded by <code>=begin</code> and <code>=end</code> markers, both of which are followed by a valid identifier<a name="_nb_in_1" href="#_nb_out_1">1</a>, which is the <a name="typename"><dfn>typename</dfn></a> of the block. Typenames that are entirely lowercase (for example: <code>=begin head1</code>) or entirely uppercase (for example: <code>=begin SYNOPSI/code) are reserved. After the typename, the rest of the <code>=begin</code> 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: <blockquote><a name=""><a name="25836360"><table> <tr> <th> Value is... </th> <th> Specify with... </th> <th> Or with... </th> <th> Or with... </th> </tr> <tr> <td> Boolean (true) </td> <td> <code>:key</code> </td> <td> <code>:key(1)</code> </td> <td> <code>key => 1</code> </td> </tr> <tr> <td> Boolean (false) </td> <td> <code>:!key</code> </td> <td> <code>:key(0)</code> </td> <td> <code>key => 0</code> </td> </tr> <tr> <td> String </td> <td> <code>:key<str></code> </td> <td> <code>:key('str')</code> </td> <td> <code>key => 'str'</code> </td> </tr> <tr> <td> List </td> <td> <code>:key<1 2 3></code> </td> <td> <code>:key[1,2,3]</code> </td> <td> <code>key => [1,2,3]</code> </td> </tr> <tr> <td> Hash </td> <td> <code>:key{a=>1, b=>2}</code> </td> <td> </td> <td> <code>key => {a=>1, b=>2}</code> </td> </tr> <tr> <td> Code </td> <td> <code>:key{ sqrt($_) }</code> </td> <td> </td> <td> </td> </tr> </table></a></a> </blockquote>All option keys and values must, of course, be constants since Perldoc is a specification language, not a programming language. See <a href="http://dev.perl.org/perl6/doc/design/syn/S02.html#Literals">Synopsis 2</a> for details of the various Perl 6 pair notations. The configuration section may be extended over subsequent lines by starting those lines with an <code>=</code> 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 <code>=end</code> marker line. For most block types, these contents may be indented if you wish, without them being treated as <a href="#Code blocks">code blocks</a>. Unlike Perl 5, indented text is only treated as code within <code>=pod</code>, <a href="#Nesting blocks"><code>=nested</code></a>, <a href="#Lists"><code>=item</code></a>, <code>=code</code>, and <a href="#Semantic blocks">semantic</a> blocks. The general syntax is: <blockquote><pre>=begin <var>BLOCK_TYPE</var> <var>OPTIONAL CONFIG INF/var = <var>OPTIONAL EXTRA CONFIG INF/var <var>BLOCK CONTENT/var =end <var>BLOCK_TYPE</var> </pre></blockquote>For example: <blockquote><pre>=begin table :caption<Table of Contents> Constants 1 Variables 10 Subroutines 33 Everything else 57 =end table </pre></blockquote><blockquote><pre>=begin Name :required = :width(50) The applicant's full name =end Name </pre></blockquote><blockquote><pre>=begin Contact :optional The applicant's contact details =end Contact </pre></blockquote>Note that no blank lines are required around the directives; blank lines within the contents are always treated as part of the contents. This is a universal feature of Pod. Note also that in the following specifications, a "blank line" is a line that is either empty or that contains only whitespace characters. That is, a blank line matches the Perl 6 pattern: <code>/^^ \h* $$/</code>. Pod uses blank lines as delimiters, rather than empty lines, the principle of least surprise. <h3><a name="Paragraph blocks"><a name="25859448">Paragraph blocks </a></a></h3> Paragraph blocks are introduced by a <code>=for</code> marker and terminated by the next Pod directive or the first blank line (which is not considered to be part of the block's contents). The <code>=for</code> marker is followed by the name of the block and optional configuration information. The general syntax is: <blockquote><pre>=for <var>BLOCK_TYPE</var> <var>OPTIONAL CONFIG INF/var = <var>OPTIONAL EXTRA CONFIG INF/var <var>BLOCK DAT/var </pre></blockquote>For example: <blockquote><pre>=for table :caption<Table of Contents> Constants 1 Variables 10 Subroutines 33 Everything else 57 </pre></blockquote><blockquote><pre>=for Name :required = :width(50) The applicant's full name </pre></blockquote><blockquote><pre>=for Contact :optional The applicant's contact details </pre></blockquote><h3><a name="Abbreviated blocks"><a name="25872664">Abbreviated blocks </a></a></h3> Abbreviated blocks are introduced by an <code>'='</code> sign in the first column, which is followed immediately by the typename of the block. The rest of the line is treated as block data, rather than as configuration. The content terminates at the next Pod directive or the first blank line (which is not part of the block data). The general syntax is: <blockquote><pre>=<var>BLOCK_TYPE</var> <var>BLOCK DAT/var <var>MORE BLOCK DAT/var

</pre></blockquote>For example: <blockquote><pre>=table Constants 1 Variables 10 Subroutines 33 Everything else 57 </pre></blockquote><blockquote><pre>=Name The applicant's full name =Contact The applicant's contact details </pre></blockquote>Note that abbreviated blocks cannot specify configuration information. If configuration is required, use a <code>=for</code> or <code>=begin</code>/<code>=end</code> instead. <h3><a name="Block equivalence"><a name="25882808">Block equivalence </a></a></h3> The three block specifications (delimited, paragraph, and abbreviated) are treated identically by the underlying documentation model, so you can use whichever form is most convenient for a particular documentation task. In the descriptions that follow, the abbreviated form will generally be used, but should be read as standing for all three forms equally. For example, although <a href="#Headings">Headings</a> shows only: <blockquote><pre>=head1 Top Level Heading </pre></blockquote>this automatically implies that you could also write that block as: <blockquote><pre>=for head1 Top Level Heading </pre></blockquote>or: <blockquote><pre>=begin head1 Top Level Heading =end head1 </pre></blockquote><h3><a name="Standard configuration options"><a name="25887640">Standard configuration options </a></a></h3> Pod predefines a small number of standard configuration options that can be applied uniformly to built-in block types. These include: <dl><dt><code>:nested</code> </dt><dd>This option specifies that the block is to be nested within its current context. For example, nesting might be applied to block quotes, to textual examples, or to commentaries. In addition the <a href="#Code blocks"><code>=code</code></a>, <a href="#Lists"><code>=item</code></a>, <a href="#I/O blocks"><code>=input</code></a>, and <a href="#I/O blocks"><code>=output</code></a> blocks all have implicit nesting. Nesting of blocks is usually rendered by adding extra indentation to the block contents, but may also be indicated in others ways: by boxing the contents, by changing the font or size of the nested text, or even by folding the text (so long as a visible placeholder is provided). Occasionally it is desirable to nest content by more than one level: <blockquote><pre>=begin para :nested =begin para :nested =begin para :nested "We're going deep, deep, I<deep> undercover!" =end para =end para =end para </pre></blockquote>This can be simplified by giving the <code>:nested</code> option a positive integer value: <blockquote><pre>=begin para :nested(3) "We're going deep, deep, I<deep> undercover!" =end para </pre></blockquote>You can also give the option a value of zero, to defeat any implicit nesting that might normally be applied to a paragraph. For example, to specify a block of code that should appear without its usual nesting: <blockquote><pre>=comment Don't nest this code block in the usual way... =begin code :nested(0) </pre></blockquote><blockquote><pre> 1 2 3 4 5 6 123456789012345678901234567890123456789012345678901234567890 |------|-----------------------|---------------------------| line instruction comments number code </pre></blockquote><blockquote><pre>=end code </pre></blockquote>Note that <code>:!nested</code> could also be used for this purpose: <blockquote><pre>=begin code :!nested </pre></blockquote></dd>

<dt><code>:numbered</code> </dt><dd>This option specifies that the block is to be numbered. The most common use of this option is to create <a href="#Numbered headings">numbered headings</a> and <a href="#Ordered lists">ordered lists</a>, but it can be applied to any block. It is up to individual renderers to decide how to display any numbering associated with other types of blocks. </dd>

<dt><code>:term</code> </dt><dd>This option specifies that a list item is the definition of a term. See <a href="#Definition lists">Definition lists</a>. </dd> <dt><code>:formatted</code> </dt><dd>This option specifies that the contents of the block should be treated as if they had one or more <a href="#Formatting codes">formatting codes</a> placed around them. For example, instead of: <blockquote><pre>=for comment The next para is both important and fundamental, so doubly emphasize it... </pre></blockquote><blockquote><pre>=begin para B<I< Warning: Do not immerse in water. Do not expose to bright light. Do not feed after midnight. >> =end para </pre></blockquote>you can just write: <blockquote><pre>=begin para :formatted Warning: Do not immerse in water. Do not expose to bright light. Do not feed after midnight. =end para </pre></blockquote>The internal representations of these two versions are exactly the same, except that the second one retains the <code>:formatted</code> option information as part of the resulting block object. Like all formatting codes, codes applied via a <code>:formatted</code> are inherently cumulative. For example, if the block itself is already inside a formatting code, that formatting code will still apply, in addition to the extra "basis" and "important" formatting specified by <code>:formatted</code>. </dd>

<dt><code>:like</code> </dt><dd>This option specifies that a block or config has the same formatting properties as the type named by its value. This is useful for creating related <a href="#Block pre-configuration">configurations</a>. For example: <blockquote><pre>=config head2 :like<head1> :formatted </pre></blockquote></dd>

<dt><code>:allow</code> </dt><dd>This option expects a list of formatting codes that are to be recognized within any <code>V<></code> codes that appear in (or are implicitly applied to) the current block. The option is most often used on <code>=code</code> blocks to allow mark-up within those otherwise verbatim blocks, though it can be used in any block that contains verbatim text. See <a href="#Formatting within code blocks">Formatting within code blocks</a>. </dd>

</dl><h2><a name="Blocks"><a name="25942464">Blocks </a></a></h2> Pod offers notations for specifying a range of standard block types... <h3><a name="Headings"><a name="25929040">Headings </a></a></h3> Pod provides an unlimited number of levels of heading, specified by the <code>=head</code><var>/var block marker. For example: <blockquote><pre>=head1 A Top Level Heading </pre></blockquote><blockquote><pre>=head2 A Second Level Heading </pre></blockquote><blockquote><pre>=head3 A third level heading </pre></blockquote><blockquote><pre>=head86 A "Missed it by I<that> much!" heading </pre></blockquote>While Pod parsers are required to recognize and distinguish all levels of heading, Pod renderers are only required to provide distinct renderings of the first four levels of heading (though they may, of course, provide more than that). Headings at levels without distinct renderings would typically be rendered like the lowest distinctly rendered level. <h4><a name="Numbered headings"><a name="25951484">Numbered headings </a></a></h4> You can specify that a heading is numbered using the <code>:numbered</code> option. For example: <blockquote><pre>=for head1 :numbered The Problem </pre></blockquote><blockquote><pre>=for head1 :numbered The Solution </pre></blockquote><blockquote><pre>=for head2 :numbered Analysis </pre></blockquote><blockquote><pre>=for head3 Overview </pre></blockquote><blockquote><pre>=for head3 Details </pre></blockquote><blockquote><pre>=for head2 :numbered Design </pre></blockquote><blockquote><pre>=for head1 :numbered The Implementation </pre></blockquote>which would produce: <blockquote>1. The Problem 2. The Solution <blockquote>2.1. Analysis <blockquote>Overview Details </blockquote> 2.2: Design </blockquote> 3. The Implementation </blockquote> It is usually better to preset a numbering scheme for each heading level, in a series of <a href="#Block pre-configuration">configuration blocks</a>: <blockquote><pre>=config head1 :numbered =config head2 :numbered =config head3 :!numbered </pre></blockquote><blockquote><pre>=head1 The Problem =head1 The Solution =head2 Analysis =head3 Overview =head3 Details =head2 Design =head1 The Implementation </pre></blockquote>Alternatively, as a short-hand, if the first whitespace-delimited word in a heading consists of a single literal <code>#</code> character, the <code>#</code> is removed and the heading is treated as if it had a <code>:numbered</code> option: <blockquote><pre>=head1 # The Problem =head1 # The Solution =head2 # Analysis =head3 Overview =head3 Details =head2 # Design =head1 # The Implementation </pre></blockquote>Note that, even though renderers are not required to distinctly render more than the first four levels of heading, they are required to correctly honour arbitrarily nested numberings. That is: <blockquote><pre>=head6 # The Rescue of the Kobayashi Maru </pre></blockquote>should produce something like: <blockquote>2.3.8.6.1.9. The Rescue of the Kobayashi Maru </blockquote> <h3><a name="Ordinary paragraph blocks"><a name="25983852">Ordinary paragraph blocks </a></a></h3> Ordinary paragraph blocks consist of text that is to be formatted into a document at the current level of nesting, with whitespace squeezed, lines filled, and any special <a href="#Formatting codes">inline mark-up</a> applied. Ordinary paragraphs consist of one or more consecutive lines of text, each of which starts with a non-whitespace character at column 1. The paragraph is terminated by the first blank line or block directive. For example: <blockquote><pre>=head1 This is a heading block </pre></blockquote><blockquote><pre>This is an ordinary paragraph. Its text will be squeezed and short lines filled. It is terminated by the first blank line. </pre></blockquote><blockquote><pre>This is another ordinary paragraph. Its text will also be squeezed and short lines filled. It is terminated by the trailing directive on the next line. =head2 This is another heading block </pre></blockquote>Within a <code>=pod</code>, <code>=item</code>, <code>=nested</code>, <code>=EN/code, or <a href="#Semantic blocks">semantic</a> block, ordinary paragraphs do not require an explicit marker or delimiters, but there is also an explicit <code>para</code> marker (which may be used anywhere): <blockquote><pre>=para This is an ordinary paragraph. Its text will be squeezed and short lines filled. </pre></blockquote>and likewise the longer <code>=for</code> and <code>=begin</code>/<code>=end</code> forms. For example: <blockquote><pre>=begin para This is an ordinary paragraph. Its text will be squeezed and short lines filled.

This is I&lt;still&gt; part of the same paragraph,
which continues until an...
<strong>=end para</strong>
</pre></blockquote><p>As the previous example implies, when any form of explicit <code>para</code> block
is used, any whitespace at the start of each line is removed, so
the paragraph text no longer has to begin at column 1. In addition,
within a delimited <code>=begin para</code>/<code>=end para</code> block, any blank lines are
preserved.
</p>
<h3><a name="Code blocks"><a name="25977324">Code blocks </a></a></h3>
<p>Code blocks are used to specify pre-formatted text (typically source
code), which should be rendered without rejustification, without
whitespace-squeezing, and without recognizing any inline formatting
codes. Code blocks also have an implicit <a href="#Nesting blocks">nesting</a>
associated with them. Typically these blocks are used to show examples
of code, mark-up, or other textual specifications, and are rendered
using a fixed-width font.
</p>
<p>A code block may be implicitly specified as one or more lines of text,
each of which starts with a whitespace character. The block is
terminated by a blank line. For example:
</p>
<blockquote><pre>This ordinary paragraph introduces a code block:

$this = 1 * code('block');
$which.is_specified(:by&lt;indenting&gt;);
</pre></blockquote><p>Implicit code blocks may only be used within <code>=pod</code>, <code>=item</code>,
<code>=nested</code>, <code>=END</code>, or <a href="#Semantic blocks">semantic</a> blocks.
</p>
<p>There is also an explicit <code>=code</code> block (which can be specified within
<em>any</em> other block type, not just <code>=pod</code>, <code>=item</code>, etc.):
</p>
<blockquote><pre>The C&lt;loud_update()&gt; subroutine adds feedback:

=begin code

sub loud_update ($who, $status) { say "$who -> $status";

silent_update($who, $status);
}

=end code </pre></blockquote>As the previous example demonstrates, within an explicit <code>=code</code> block the code can start at the first column. Furthermore, lines that start with whitespace characters have that whitespace preserved exactly (in addition to the implicit nesting of the code). Explicit <code>=code</code> blocks may also contain empty lines. <h4><a name="Formatting within code blocks"><a name="26022044">Formatting within code blocks </a></a></h4> Although <code>=code</code> blocks automatically disregard all <a href="#Formatting codes">formatting codes</a>, occasionally you may still need to specify some formatting within a code block. For example, you may wish to emphasize a particular keyword in an example (using a <code>B<></code> code). Or you may want to indicate that part of the example is metasyntactic (using the <code>R<></code> code). Or you might need to insert a non-ASCII character (using the <code>E<></code> code). You can specify a list of formatting codes that should still be recognized within a code block using the <code>:allow</code> option. The value of the <code>:allow</code> option must be a list of the (single-letter) names of one or more formatting codes. Those codes will then remain active inside the code block. For example: <blockquote><pre>=begin code :allow sub demo { B<say> 'Hello R<name>'; } =end code </pre></blockquote>would be rendered: <blockquote><pre>sub demo { say 'Hello <var>name</var>'; } </pre></blockquote>Although code blocks are verbatim by default, it can still occasionally be useful to explicitly <code>:allow</code> the verbatim formatting code (<code>V<></code>). That's because, although the contents of an explicit <code>=code</code> block are allowed to start in column 1, they are not allowed to start with an equals sign in that first column<a name="_nb_in_2" href="#_nb_out_2">2</a>. So, if an <code>=</code> is needed in column 1, it must be declared <a href="#Verbatim text">verbatim</a>: <blockquote><pre>=begin code :allow<V>

V<=> in the first column is always a Perldoc directive

Do you want additional personnel details? <strong>K&lt;y&gt;</strong>

Height:  180cm/5'11"
Weight:  104kg/230lb
Age:     49

Print? <strong>K&lt;n&gt;</strong>
=end output
</pre></blockquote><h3><a name="Lists"><a name="26058624">Lists </a></a></h3>
<p>Lists in Pod are specified as a series of contiguous <code>=item</code> blocks. No
special "container" directives or other delimiters are required to
enclose the entire list. For example:
</p>
<blockquote><pre>The seven suspects are:
</pre></blockquote><blockquote><pre>=item  Happy
=item  Dopey
=item  Sleepy
=item  Bashful
=item  Sneezy
=item  Grumpy
=item  Keyser Soze
</pre></blockquote><p>List items have one implicit level of nesting:
</p>
<blockquote><p>The seven suspects are:
</p>
<ul><li>Happy
</li>
<li>Dopey
</li>
<li>Sleepy
</li>
<li>Bashful
</li>
<li>Sneezy
</li>
<li>Grumpy
</li>
<li>Keyser Soze
</li>
</ul></blockquote>
<p>Lists may be multi-level, with items at each level specified using the
<code>=item1</code>, <code>=item2</code>, <code>=item3</code>, etc. blocks. Note that <code>=item</code> is just
an abbreviation for <code>=item1</code>. For example:
</p>
<blockquote><pre>=item1  Animal
=item2     Vertebrate
=item2     Invertebrate
</pre></blockquote><blockquote><pre>=item1  Phase
=item2     Solid
=item2     Liquid
=item2     Gas
=item2     Chocolate
</pre></blockquote><p>which would be rendered something like:
</p>
<p><blockquote>&bull; Animal
</blockquote></p>
<p><blockquote><blockquote>&ndash; Vertebrate
</blockquote></blockquote></p>
<p><blockquote><blockquote>&ndash; Invertebrate
</blockquote></blockquote></p>
<p><blockquote>&bull; Phase
</blockquote></p>
<p><blockquote><blockquote>&ndash; Solid
</blockquote></blockquote></p>
<p><blockquote><blockquote>&ndash; Liquid
</blockquote></blockquote></p>
<p><blockquote><blockquote>&ndash; Gas
</blockquote></blockquote></p>
<p><blockquote><blockquote>&ndash; Chocolate
</blockquote></blockquote></p>
<p>Perldoc parsers must issue a warning if a "level-<var>N+1</var>" <code>=item</code> block
(e.g. an <code>=item2</code>, <code>=item3</code>, etc.) appears anywhere except where there
is a preceding "level-<var>N</var>" <code>=item</code> in the same surrounding block. That
is, an <code>=item3</code> should only be specified if an <code>=item2</code> appears
somewhere before it, and that <code>=item2</code> should itself only appear if
there is a preceding <code>=item1</code>.
</p>
<p>Note that item blocks within the same list are not physically nested.
That is, lower-level items should <em>not</em> be specified inside
higher-level items:
</p>
<blockquote><pre>=comment WRONG...
=begin item1          --------------
The choices are:                    | 
=item2 Liberty        ==&lt; Level 2   |==&lt;  Level 1
=item2 Death          ==&lt; Level 2   |
=item2 Beer           ==&lt; Level 2   |
=end item1            --------------
</pre></blockquote><blockquote><pre>=comment CORRECT...
=begin item1          ---------------
The choices are:                     |==&lt; Level 1
=end item1            ---------------
=item2 Liberty        ==================&lt; Level 2
=item2 Death          ==================&lt; Level 2
=item2 Beer           ==================&lt; Level 2
</pre></blockquote><h4><a name="Ordered lists"><a name="5766976">Ordered lists </a></a></h4>
<p>An item is part of an ordered list if the item has a <code>:numbered</code>
configuration option:
</p>
<blockquote><pre>=for item1 :numbered
Visito
</pre></blockquote><blockquote><pre>=for item2 :numbered
Veni
</pre></blockquote><blockquote><pre>=for item2 :numbered
Vidi
</pre></blockquote><blockquote><pre>=for item2 :numbered
Vici
</pre></blockquote><p>This would produce something like:
</p>
<blockquote><p>1. Visito
</p>
<blockquote><p>1.1. Veni
</p>
<p>1.2. Vidi
</p>
<p>1.3. Vici
</p>
</blockquote>
</blockquote>
<p>although the numbering scheme is entirely at the discretion of the
renderer, so it might equally well be rendered:
</p>
<blockquote><p>1. Visito
</p>
<blockquote><p>1a. Veni
</p>
<p>1b. Vidi
</p>
<p>1c. Vici
</p>
</blockquote>
</blockquote>
<p>or even:
</p>
<blockquote><p>A: Visito
</p>
<blockquote><p>&nbsp;&nbsp;(i) Veni
</p>
<p>&nbsp;(ii) Vidi
</p>
<p>(iii) Vici
</p>
</blockquote>
</blockquote>
<p>Alternatively, if the first word of the item consists of a single <code>#</code>
character, the item is treated as having a <code>:numbered</code> option:
</p>
<blockquote><pre>=item1  # Visito
=item2     # Veni
=item2     # Vidi
=item2     # Vici
</pre></blockquote><p>To specify an <em>unnumbered</em> list item that starts with a literal <code>#</code>, either
make it verbatim:
</p>
<blockquote><pre>=item <strong>V&lt;#&gt;</strong> introduces a comment
</pre></blockquote><p>or explicitly mark the item itself as being unnumbered:
</p>
<blockquote><pre>=for item <strong>:!numbered</strong>
# introduces a comment
</pre></blockquote><p>The numbering of successive <code>=item1</code> list items increments
automatically, but is reset to 1 whenever any other kind of non-ambient
Perldoc block appears between two <code>=item1</code> blocks. For example:
</p>
<blockquote><pre>The options are:
</pre></blockquote><blockquote><pre>=item1 # Liberty
=item1 # Death
=item1 # Beer
</pre></blockquote><blockquote><pre>The tools are:
</pre></blockquote><blockquote><pre>=item1 # Revolution
=item1 # Deep-fried peanut butter sandwich
=item1 # Keg
</pre></blockquote><p>would produce:
</p>
<blockquote><p>The options are:
</p>
<blockquote><p>1. Liberty
</p>
<p>2. Death
</p>
<p>3. Beer
</p>
</blockquote>
<p>The tools are:
</p>
<blockquote><p>1. Revolution
</p>
<p>2. Deep-fried peanut butter sandwich
</p>
<p>3. Keg
</p>
</blockquote>
</blockquote>
<p>The numbering of nested items (<code>=item2</code>, <code>=item3</code>, etc.) only resets
(to 1) when the higher-level item's numbering either resets or increments.
</p>
<p>To prevent a numbered <code>=item1</code> from resetting after a non-item block,
you can specify the <code>:continued</code> option:
</p>
<blockquote><pre>=for item1
# Retreat to remote Himalayan monastery

I<????>

<li value="2">The early bird gets the worm. In deciding whether to become an early riser, it is worth considering whether you would actually enjoy annelids for breakfast. </li>

</ol>As you can see, folk wisdom is often of dubious value. </blockquote> <h3><a name="Nesting blocks"><a name="26124676">Nesting blocks </a></a></h3> Any block can be nested by specifying an <code>:nested</code> option on it: <blockquote><pre>=begin para :nested We are all of us in the gutter,E<NL> but some of us are looking at the stars! =end para </pre></blockquote>However, qualifying each nested paragraph individually quickly becomes tedious if there are many in a sequence, or if multiple levels of nesting are required: <blockquote><pre>=begin para :nested We are all of us in the gutter,E<NL> but some of us are looking at the stars! =end para =begin para :nested(2) -- Oscar Wilde =end para </pre></blockquote>So Pod provides a <code>=nested</code> block that marks all its contents as being nested: <blockquote><pre>=begin nested We are all of us in the gutter,E<NL> but some of us are looking at the stars! =begin nested -- Oscar Wilde =end nested =end nested </pre></blockquote>Nesting blocks can contain any other kind of block, including implicit paragraph and code blocks. <h3><a name="Tables"><a name="26221488">Tables </a></a></h3> Simple tables can be specified in Perldoc using a <code>=table</code> block. The table may be given an associated description or title using the <code>:caption</code> option. Columns are separated by whitespace, vertical lines (<code>|</code>), or border intersections (<code>+</code>). Rows can be specified in one of two ways: either one row per line, with no separators; or multiple lines per row with explicit horizontal separators (whitespace, intersections (<code>+</code>), or horizontal lines: <code>-</code>, <code>=</code>, <code>_</code>) between every row. Either style can also have an explicitly separated header row at the top. Each individual table cell is separately formatted, as if it were a nested <code>=para</code>. This means you can create tables compactly, line-by-line: <blockquote><pre>=table The Shoveller Eddie Stevens King Arthur's singing shovel Blue Raja Geoffrey Smith Master of cutlery Mr Furious Roy Orson Ticking time bomb of fury The Bowler Carol Pinnsler Haunted bowling ball </pre></blockquote>or line-by-line with multi-line headers: <blockquote><pre>=table Superhero | Secret | | Identity | Superpower ==============|=================|================================ The Shoveller | Eddie Stevens | King Arthur's singing shovel Blue Raja | Geoffrey Smith | Master of cutlery Mr Furious | Roy Orson | Ticking time bomb of fury The Bowler | Carol Pinnsler | Haunted bowling ball </pre></blockquote>or with multi-line headers and multi-line data: <blockquote><pre>=begin table :caption('The Other Guys') </pre></blockquote><blockquote><pre> Secret Superhero Identity Superpower ============= =============== =================== The Shoveller Eddie Stevens King Arthur's singing shovel </pre></blockquote><blockquote><pre>Blue Raja Geoffrey Smith Master of cutlery </pre></blockquote><blockquote><pre>Mr Furious Roy Orson Ticking time bomb of fury </pre></blockquote><blockquote><pre>The Bowler Carol Pinnsler Haunted bowling ball </pre></blockquote><blockquote><pre>=end table </pre></blockquote><h3><a name="Named blocks"><a name="26239040">Named blocks </a></a></h3> Blocks whose names are not recognized as Pod built-ins are assumed to be destined for specialized renderers or parser plug-ins. For example: <blockquote><pre>=begin Xhtml <object type="video/quicktime" data="onion.mov"> =end Xhtml </pre></blockquote>or: <blockquote><pre>=Image http://www.perlfoundation.org/images/perl_logo_32x104.png </pre></blockquote>Named blocks are converted by the Perldoc parser to block objects; specifically, to objects of a subclass of the standard <code>Perldoc::Block::Named</code> class. For example, the blocks of the previous example would be converted to objects of the classes <code>Perldoc::Block::Named::Xhtml</code> and <code>Perldoc::Block::Named::Image</code> respectively. Both of those classes would be automatically created as subclasses of the <code>Perldoc::Block::Named</code> class (unless they were already defined via a prior <a href="#Modules"><code>=use directive</code></a>). The resulting object's <code>.typename</code> method retrieves the short name of the block type: <code>'Xhtml'</code>, <code>'Image'</code>, etc. The object's <code>.config</code> method retreives the list of configuration options (if any). The object's <code>.contents</code> method retrieves a list of the block's verbatim contents. Named blocks for which no explicit class has been defined or loaded are usually not rendered by the standard renderers. Note that all block names consisting entirely of lower-case or entirely of upper-case letters are reserved. See <a href="#Semantic blocks">Semantic blocks</a>. <h3><a name="Comments"><a name="26257432">Comments </a></a></h3> Comments are Pod blocks that are never rendered by any renderer. They are, of course, still included in any internal Perldoc representation, and are accessible via the Perldoc API. Comments are useful for meta-documentation (documenting the documentation): <blockquote><pre>=comment Add more here about the algorithm </pre></blockquote>and for temporarily removing parts of a document: <blockquote><pre>=item # Retreat to remote Himalayan monastery

# Learn the hidden mysteries of space and time

# Achieve enlightenment

=begin comment =item # Prophet! =end comment </pre></blockquote>Note that, since the Perl interpreter never executes embedded Perldoc blocks, <code>comment</code> blocks can also be used as (nestable!) block comments in Perl 6: <blockquote><pre>=begin comment for my $file (@files) { system("rm -rf $file"); } =end comment </pre></blockquote><h3><a name="The C<=END> block"><a name="26264780">The <code>=EN/code block </a></a></h3> The <code>=EN/code block is special in that all three of its forms (<a href="#Delimited blocks">delimited</a>, <a href="#Paragraph blocks">paragraph</a>, and <a href="#Abbreviated blocks">abbreviated</a>) are terminated only by the end of the current file. That is, neither <code>=EN/code nor <code>=for EN/code are terminated by the next blank line, and <code>=end EN/code has no effect within a <code>=begin EN/code block. A warning is issued if an explicit <code>=end EN/code appears within a document. An <code>=EN/code block indicates the end-point of any ambient material within the document. This means that the parser will treat all the remaining text in the file as Perldoc, even if it is not inside an explicit block. In other words, apart from its special end-of-file termination behaviour, an <code>=EN/code block is in all other respects identical to a <code>=pod</code> block. <h3><a name="Data blocks"><a name="26277512">Data blocks </a></a></h3> Named Perldoc blocks whose typename is <code>DAT/code are the Perl 6 equivalent of the Perl 5 <code>__DATA__</code> section. The difference is that <code>=DAT/code blocks are just regular Pod blocks and may appear anywhere within a source file, and as many times as required. <a href="http://perldoc.perl.org/http://dev.perl.org/perl6/doc/design/syn/S02.html#Literals.html">Synopsis 2</a> describes the new Perl 6 interface for inline data. <h3><a name="Semantic blocks"><a name="26279848">Semantic blocks </a></a></h3> All other uppercase block typenames are reserved for specifying standard documentation, publishing, or source components. In particular, all the standard components found in Perl and manpage documentation have reserved uppercase typenames. Standard semantic blocks include: <blockquote><pre>=NAME =VERSION =SYNOPSIS =DESCRIPTION =USAGE =INTERFACE =METHOD =SUBROUTINE =OPTION =DIAGNOSTIC =ERROR =WARNING =DEPENDENCY =BUG =SEEALSO =ACKNOWLEDGEMENT =AUTHOR =COPYRIGHT =DISCLAIMER =LICENCE =LICENSE =TITLE =SECTION =CHAPTER =APPENDIX =TOC =INDEX =FOREWORD =SUMMARY =DEFAULT =PURPOSE </pre></blockquote>The plural forms of each of these keywords are also reserved, and are aliases for the singular forms. Most of these blocks would typically be used in their full delimited forms: <blockquote><pre>=begin SYNOPSIS use Perldoc::Parser

my Perldoc::Parser $parser .= new();

my $tree = $parser.parse($fh);
=end SYNOPSIS
</pre></blockquote><p>Semantic blocks can be considered to be variants of the <code>=head1</code> block
in most respects (and most renderers will treat them as such). The main
difference is that, in a <code>=head1</code> block, the heading is the contents of
the block; whereas, in a semantic block, the heading is derived from the
typename of the block itself and the block contents are instead treated as
the <code>=para</code> or <code>=code</code> block(s) belonging to the heading.
</p>
<p>The use of these special blocks is not required; you can still just write:
</p>
<blockquote><pre>=head1 SYNOPSIS
=begin code
use Perldoc::Parser

my Perldoc::Parser $parser .= new();

my $tree = $parser.parse($fh);
=end code
</pre></blockquote><p>However, using the keywords adds semantic information to the
documentation, which may assist various renderers, summarizers, coverage
tools, document refactorers, and other utilities. This is because a
semantic block <em>encloses</em> the text it controls (unlike a <code>=head1</code>,
which merely precedes its corresponding text), so using semantic blocks
produces a more explicitly structured document.
</p>
<p>Note that there is no requirement that semantic blocks be rendered in
a particular way (or at all). Specifically, it is not necessary to
preserve the capitalization of the keyword. For example, the
<code>=SYNOPSIS</code> block of the preceding example might be rendered like so:
</p>
<blockquote><p><strong>3.&nbsp;&nbsp;<em>Synopsis</em></strong>
</p>
<blockquote><pre>use Perl6::Perldoc::Parser;

my $rep = Perl6::Perldoc::Parser.parse($fh, :all_pod); </pre></blockquote></blockquote> <h2><a name="Formatting codes"><a name="26204352">Formatting codes </a></a></h2> Formatting codes provide a way to add inline mark-up to a piece of text within the contents of (most types of) block. Formatting codes are themselves a type of block, and most of them may nest sequences of any other type of block (most often, other formatting codes). In particular, you can nest comment blocks in the middle of a formatting code: <blockquote><pre>B=begin comment and repeatedly =end comment and with emphasis.> </pre></blockquote>All Pod formatting codes consist of a single capital letter followed immediately by a set of angle brackets. The brackets contain the text or data to which the formatting code applies. You can use a set of single angles (<code><...></code>), a set of double angles (<code>«...»</code>), or multiple single-angles (<code><<<...>>></code>). Within angle delimiters, you cannot use sequences of the same angle characters that are longer than the delimiters: <blockquote><pre>=comment These are errors...

C< $foo<<bar>> > The Perl 5 heredoc syntax was: C< <<END_MARKER > </pre></blockquote>You can use sequences of angles that are the same length as the delimiters, but they must be balanced. For example: <blockquote><pre>C< $foo<bar> > C<< $foo<<bar>> >> </pre></blockquote>If you need an unbalanced angle, either use different delimiters: <blockquote><pre>strong«$foo < $bar» The Perl 5 heredoc syntax was: strong« <<END_MARKER » </pre></blockquote>or delimiters with more consecutive angles than your text contains: <blockquote><pre>strong<<$foo < $bar>> The Perl 5 heredoc syntax was: strong<<< <<END_MARKER >>> </pre></blockquote>A formatting code ends at the matching closing angle bracket(s), or at the end of the enclosing block or formatting code in which the opening angle bracket was specified, whichever comes first. Pod parsers are required to issue a warning whenever a formatting code is terminated by the end of an outer block rather than by its own delimiter (unless the user explicitly disables the warning). <h3><a name="Significance indicators"><a name="26327424">Significance indicators </a></a></h3> Pod provides three formatting codes that flag their contents with increasing levels of significance: <ul><li>The <code>U<></code> formatting code specifies that the contained text is unusual or distinctive; that it is of minor significance. Typically such content would be rendered in an underlined style. </li> <li>The <code>I<></code> formatting code specifies that the contained text is important; that it is of major significance. Such content would typically be rendered in italics or in <code> ... </code> tags </li> <li>The <code>B<></code> formatting code specifies that the contained text is the basis or focus of the surrounding text; that it is of fundamental significance. Such content would typically be rendered in a bold style or in <code> ... </code> tags. </li>

</ul><h3><a name="Definitions"><a name="26342116">Definitions </a></a></h3> The <code>D<></code> formatting code indicates that the contained text is a definition, introducing a term that the adjacent text elucidates. For example: <blockquote><pre>There ensued a terrible moment of D<coyotus interruptus>: a brief suspension of the effects of gravity, accompanied by a sudden to-the-camera realisation of imminent downwards acceleration. </pre></blockquote>A definition may be given synonyms, which are specified after a vertical bar and separated by semicolons: <blockquote><pre>A D<Formatting code|formatting codes;formatters> provides a way to add inline mark-up to a piece of text. </pre></blockquote>A definition would typically be rendered in italics or <code> <dfn>...</dfn> </code> tags and will often be used as a link target for subsequent instances of the term (or any of its specified synonyms) within a hypertext. <h3><a name="Example specifiers"><a name="26348620">Example specifiers </a></a></h3> Perldoc provides formatting codes for specifying inline examples of input, output, code, and metasyntax: <ul><li>The <code>T<></code> formatting code specifies that the contained text is terminal output; that is: something that a program might print out. Such content would typically be rendered in a <samp>fixed-width font</samp> or with <code> <code>...</code> </code> tags. The contents of a <code>T<></code> code are always <a href=" #Space-preserving text">space-preserved </a> (as if they had an implicit <code>S<...></code> around them). The <code>T<></code> code is the inline equivalent of the <code>=output</code> block. </li>

<li>The <code>K<></code> formatting code specifies that the contained text is keyboard input; that is: something that a user might type in. Such content would typically be rendered in a <kbd>fixed-width font</kbd> (preferably a different font from that used for the <code>T<></code> formatting code) or with <code> <kbd>...</kbd> </code> tags. The contents of a <code>K<></code> code are always <a href=" #Space-preserving text">space-preserved</a>. The <code>K<></code> code is the inline equivalent of the <code>=input</code> block. </li>

<li>The <code>C<></code> formatting code specifies that the contained text is code; that is, something that might appear in a program or specification. Such content would typically be rendered in a <code>fixed-width font</code> (preferably a different font from that used for the <code>T<></code> or <code>K<></code> formatting codes) or with <code> <samp>...</samp> </code> tags. The contents of a <code>C<></code> code are <a href=" #Space-preserving text">space-preserved</a> and <a href=" #Verbatim text">verbatim</a>. The <code>C<></code> code is the inline equivalent of the <code>=code</code> block. To include other formatting codes in a <code>C<></code> code, you can lexically <a href="#Block pre-configuration">reconfigure</a> it: <blockquote><pre>=begin para =config C<> :allow<E I> Perl 6 makes extensive use of the C<E<laquo>> and C<E<raquo>> characters, for example, in a hash look-up: C<%hashI<E<laquo>>keyI<E<raquo>>> =end para </pre></blockquote>To enable entities in every <code>C<...></code> put a <code>=config C<> :allow<E></code> at the top of the document </li>

<li>The <code>R<></code> formatting code specifies that the contained text is a replaceable item, a placeholder, or a metasyntactic variable. It is used to indicate a component of a syntax or specification that should eventually be replaced by an actual value. For example: <blockquote><pre>The basic C<ln> command is: C<ln> R<source_file> R<target_file> </pre></blockquote>or: <blockquote><pre>Then enter your details at the prompt:

</ul><h3><a name="Verbatim text"><a name="26404796">Verbatim text </a></a></h3> The <code>V<></code> formatting code treats its entire contents as being verbatim, disregarding every apparent formatting code within it. For example: <blockquote><pre>The B<V< V<> >> formatting code disarms other codes such as V< I<>, C<>, B<>, and M<> >. </pre></blockquote>Note, however that the <code>V<></code> code only changes the way its contents are parsed, not the way they are rendered. That is, the contents are still wrapped and formatted like plain text, and the effects of any formatting codes surrounding the <code>V<></code> code are still applied to its contents. For example the previous example is rendered: <blockquote>The V<> formatting code disarms other codes such as I<>, C<>, B<>, and M<> . </blockquote> You can prespecify formatting codes that remain active within a <code>V<></code> code, using the <a href="#Formatting within code blocks"><code>:allow</code></a> option. <h3><a name="Inline comments"><a name="26422220">Inline comments </a></a></h3> The <code>Z<></code> formatting code indicates that its contents constitute a zero-width comment, which should not be rendered by any renderer. For example: <blockquote><pre>The "exeunt" command Z<Think about renaming this command?> is used to quit all applications. </pre></blockquote>In Perl 5 POD, the <code>Z<></code> code was widely used to break up text that would otherwise be considered mark-up: <blockquote><pre>In Perl 5 POD, the Z<><> code was widely used to break up text that would otherwise be considered mark-up. </pre></blockquote>That technique still works, but it's now easier to accomplish the same goal using a verbatim formatting code: <blockquote><pre>In Perl 5 POD, the V<Z<>> code was widely used to break up text that would otherwise be considered mark-up. </pre></blockquote>Moreover, the <code>C<></code> code automatically treats its contents as being verbatim, which often eliminates the need for the <code>V<></code> as well: <blockquote><pre>In Perl 5 POD, the C<Z<>> code was widely used to break up text that would otherwise be considered mark-up. </pre></blockquote>The <code>Z<></code> formatting code is the inline equivalent of a <a href="#Comments"><code>=comment</code> block</a>. <h3><a name="Links"><a name="26445052">Links </a></a></h3> The <code>L<></code> code is used to specify all kinds of links, filenames, citations, and cross-references (both internal and external). A link specification consists of a scheme specifier terminated by a colon, followed by an external address (in the scheme's preferred syntax), followed by an internal address (again, in the scheme's syntax). All three components are optional, though at least one must be present in any link specification. Usually, in schemes where an internal address makes sense, it will be separated from the preceding external address by a <code>#</code>, unless the particular addressing scheme requires some other syntax. When new addressing schemes are created specifically for Perldoc it is strongly recommended that <code>#</code> be used to mark the start of internal addresses. Standard schemes include: <dl><dt><code>http:</code> and <code>https:</code> </dt><dd>A standard web URL. For example: <blockquote><pre>This module needs the LAME library (available from L<http://www.mp3dev.org/mp3/>) </pre></blockquote>If the link does not start with <code>//</code> it is treated as being relative to the location of the current document: <blockquote><pre>See also: L<http:tutorial/faq.html> and L<http:../examples/index.html> </pre></blockquote></dd>

<dt><code>file:</code> </dt><dd>A filename on the local system. For example: <blockquote><pre>Next, edit the global config file (that is, either L<file:/usr/local/lib/.configrc> or L<file:~/.configrc>). </pre></blockquote>Filenames that don't begin with a <code>/</code> or a <code>~</code> are relative to the current document's location: <blockquote><pre>Then, edit the local config file (that is, either L<file:.configrc> or L<file:CONFIG/.configrc>. </pre></blockquote></dd>

<dt><code>mailto:</code> </dt><dd>An email address. Typically, activating this type of link invokes a mailer. For example: <blockquote><pre>Please forward bug reports to L<mailto:devnull@rt.cpan.org> </pre></blockquote></dd>

<dt><code>man:</code> </dt><dd>A link to the system manpages. For example: <blockquote><pre>This module implements the standard Unix L<man:find(1)> facilities. </pre></blockquote></dd>

<dt><code>doc:</code> </dt><dd>A link to some other documentation, typically a module or part of the core documentation. For example: <blockquote><pre>You may wish to use L<doc:Data::Dumper> to view the results. See also: L<doc:perldata>. </pre></blockquote></dd>

<dt><code>defn:</code> </dt><dd>A link to the <a href="#Definitions">definition</a> of the specified term within the current document. For example: <blockquote><pre>He was highly prone to D<lexiphania>: an unfortunate proclivity for employing grandiloquisms (for example, words such as "proclivity", "grandiloquism" and indeed "lexiphania"). </pre></blockquote>and later, to link back to the definition <blockquote><pre>To treat his chronic L<defn:lexiphania> the doctor prescribed an immediate glossoligation or, if that proved ineffective, a complete cephalectomy. </pre></blockquote></dd>

<dt><code>isbn:</code> and <code>issn:</code> </dt><dd>The International Standard Book Number or International Standard Serial Number for a publication. For example: <blockquote><pre>The Perl Journal was a registered serial publication (L<issn:1087-903>) </pre></blockquote></dd>

</dl>To refer to a specific section within a webpage, manpage, or Perldoc document, add the name of that section after the main link, separated by a <code>#</code>. For example: <blockquote><pre>Also see: L<man:bash(1)#Compound Commands>, L<doc:perlsyn#For Loops>, and L<http://dev.perl.org/perl6/syn/S04.html#The_for_statement> </pre></blockquote>To refer to a section of the current document, omit the external address: <blockquote><pre>This mechanism is described under L<doc:#Special Features> below. </pre></blockquote>The scheme name may also be omitted in that case: <blockquote><pre>This mechanism is described under L<#Special Features> below. </pre></blockquote>Normally a link is presented as some rendered version of the link specification itself. However, you can specify an alternate presentation by prefixing the link with the desired text and a vertical bar. Whitespace is not significant on either side of the bar. For example: <blockquote><pre>This module needs the L<LAME library|http://www.mp3dev.org/mp3/>.

You could also write the code L<in Latin | doc:Lingua::Romana::Perligata> </pre></blockquote><h3><a name="Placement links"><a name="26504884">Placement links </a></a></h3> A second kind of link—the <code>P<></code> or placement link—works in the opposite direction. Instead of directing focus out to another document, it allows you to draw the contents of another document into your own. In other words, the <code>P<></code> formatting code takes a URI and (where possible) places the contents of the corresponding document inline in place of the code itself. <code>P<></code> codes are handy for breaking out standard elements of your documentation set into reusable components that can then be incorporated directly into multiple documents. For example: <blockquote><pre>=COPYRIGHT P<file:/shared/docs/std_copyright.pod> </pre></blockquote><blockquote><pre>=DISCLAIMER P<http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt> </pre></blockquote>might produce: <blockquote>Copyright This document is copyright (c) MegaGigaTeraPetaCorp, 2006. All rights reserved. Disclaimer ABSOLUTELY NO WARRANTY IS IMPLIED. NOT EVEN OF ANY KIND. WE HAVE SOLD YOU THIS SOFTWARE WITH NO HINT OF A SUGGESTION THAT IT IS EITHER USEFUL OR USABLE. AS FOR GUARANTEES OF CORRECTNESS...DON'T MAKE US LAUGH! AT SOME TIME IN THE FUTURE WE MIGHT DEIGN TO SELL YOU UPGRADES THAT PURPORT TO ADDRESS SOME OF THE APPLICATION'S MANY DEFICIENCIES, BUT NO PROMISES THERE EITHER. WE HAVE MORE LAWYERS ON STAFF THAN YOU HAVE TOTAL EMPLOYEES, SO DON'T EVEN *THINK* ABOUT SUING US. HAVE A NICE DAY. </blockquote> If a renderer cannot find or access the external data source for a placement link, it must issue a warning and render the URI directly in some form, possibly as an outwards link. For example: <blockquote>Copyright See: <a href="file:/shared/docs/std_copyright.pod">std_copyright.pod</a> Disclaimer See: <a href="http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt">http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt</a> </blockquote> You can use any of the following URI forms (see <a href="#Links">Links</a>) in a placement link: <ul><li><code>http:</code> and <code>https:</code> </li> <li><code>file:</code> </li> <li><code>man:</code> </li> <li><code>doc:</code> </li> <li><code>toc:</code> </li> </ul>The <code>toc:</code> form is a special pseudo-scheme that inserts a table of contents in place of the <code>P<></code> code. After the colon, list the block types that you wish to include in the table of contents. For example, to place a table of contents listing only top- and second-level headings: <blockquote><pre>P<toc: head1 head2> </pre></blockquote>To place a table of contents that lists the top four levels of headings, as well as any tables: <blockquote><pre>P<toc: head1 head2 head3 head4 table> </pre></blockquote>To place a table of diagrams (assuming a user-defined <code>Diagram</code> block): <blockquote><pre>P<toc: Diagram> </pre></blockquote>Note also that, for <code>P<toc:...></code>, all <a href="#Semantic blocks">semantic blocks</a> are treated as equivalent to <code>head1</code> headings, and the <code>=item1</code>/<code>=item</code> equivalence is preserved. <h3><a name="Space-preserving text"><a name="26551976">Space-preserving text </a></a></h3> Any text enclosed in an <code>S<></code> code is formatted normally, except that every whitespace character in it—including any newline—is preserved. These characters are also treated as being non-breaking (except for the newlines, of course). For example: <blockquote><pre>The emergency signal is: S< dot dot dot dash dash dash dot dot dot>. </pre></blockquote>would be formatted like so: <blockquote>The emergency signal is: dot dot dot   dash dash dash    dot dot dot. </blockquote> rather than: <blockquote>The emergency signal is: dot dot dot dash dash dash dot dot dot. </blockquote> <h3><a name="Ambient aliases"><a name="26553048">Ambient aliases </a></a></h3> The <code>A<></code> formatting code specifies an alias to an ambient antecedent. This is like a <a href="#Placement links">placement link</a>, except that the text that is inserted to replace the <code>A<></code> formatting code is some portion of the <a href="#General syntactic structure">ambient section(s)</a> of the current document, rather than the entire contents of some external document. Hence, the <code>A<></code> code makes it possible to incorporate pieces of ambient text (typically source code) into Pod documentation. Specifically, the <code>A<></code> code is replaced by searching backwards through all preceding non-Pod parts of the document, to locate the nearest prior substring that matches the contents of the <code>A<></code> code. The contents of an <code>A<></code> code can specify a back-reference of this type in one of two ways: <ul><li>as a prefix keyword, or </li> <li>as a delimited text range. </li> </ul>By default, <code>A<></code> aliases are "keyword oriented". That is, the contents of an <code>A<></code> block are treated as a keyword or prefix that introduces the desired text. That text is located by searching backwards from the location of the <code>A<></code> code, to find the nearest preceding instance of the specified prefix in any previous ambient block. The text that is then used to replace the <code>A<></code> is the first "symbol" following that located prefix. In this context, a "symbol" is defined as a sequence of non-whitespace characters terminated by a transition from an identifier character to a non-identifier character. For example, in the following: <blockquote><pre>class Pet {

has $name;

Overview of the M<TT: $CLASSNAME > class (version M<TT: $VERSION>)

M<TT: get_description($CLASSNAME) > </pre></blockquote>The <code>M<></code> formatting code is the inline equivalent of a <a href="#Named blocks">named block</a>. Internally an <code>M<></code> code is converted to an object derived from the <code>Perldoc::FormattingCode::Named</code> class. The name of the scheme becomes the final component of the object's classname. For instance, the <code>M<></code> code in the previous example would be converted to a <code>Perldoc::FormattingCode::Named::T/code object, whose <code>.typename</code> method retrieves the string <code>"TT"</code> and whose <code>.contents</code> method retrieves a list of the formatting code's (verbatim, unformatted) contents. If the formatting code is unrecognized, the contents of the code (i.e. everything after the first colon) would normally be rendered as ordinary text. <h2><a name="Encoding"><a name="26716452">Encoding </a></a></h2> By default, Perldoc assumes that documents are Unicode, encoded in one of the three common schemes (UTF-8, UTF-16, or UTF-32). The particular scheme a document uses is autodiscovered by examination of the first few bytes of the file (where possible). If the autodiscovery fails, UTF-8 is assumed, and parsers may treat any non-UTF-8 bytes later in the document as fatal errors. At any point in a document, you can explicitly set or change the encoding of its content using the <code>=encoding</code> directive: <blockquote><pre>=encoding ShiftJIS </pre></blockquote><blockquote><pre>=encoding Macintosh </pre></blockquote><blockquote><pre>=encoding KOI8-R </pre></blockquote>The specified encoding is used from the start of the next line in the document. If a second <code>=encoding</code> directive is encountered, the current encoding changes again after that line. Note, however, that the second encoding directive must itself be encoded using the first encoding scheme. This requirement also applies to an <code>=encoding</code> directive at the very beginning of the file. That is, it must itself be encoded in the default UTF-8, -16, or -32. However, as a special case, the autodiscovery mechanism will (as far as possible) also attempt to recognize "self-encoded" <code>=encoding</code> directives that begin at the first byte of the file. For example, at the start of a ShiftJIS-encoded file you can specify <code>=encoding ShiftJI/code in the ShiftJIS encoding. An <code>=encoding</code> directive affects any ambient code between the Perldoc as well. That is, Perl 6 uses <code>=encoding</code> directives to determine the encoding of its source code as well as that of any documentation. Note that, like <code>=alias</code>, <code>=encoding</code> is a fundamental Perldoc directive, not an abbreviated block form. Hence there is no paragraph or delimited form of the <code>=encoding</code> directive. <h2><a name="Block pre-configuration"><a name="26733616">Block pre-configuration </a></a></h2> The <code>=config</code> directive allows you to prespecify standard configuration information that is applied to every block of a particular type. For example, to specify particular formatting for different levels of heading, you could preconfigure all the heading directives with appropriate formatting schemes: <blockquote><pre>=config head1 :formatted :numbered =config head2 :like<head1> :formatted =config head3 :formatted =config head4 :like<head3> :formatted </pre></blockquote>The general syntax for configuration directives is: <blockquote><pre>=config <var>BLOCK_TYPE</var> <var>CONFIG OPTION/var = <var>OPTIONAL EXTRA CONFIG OPTION/var </pre></blockquote>Like <code>=alias</code> and <code>=encoding</code>, a <code>=config</code> is a directive, not a block. Hence, there is no paragraph or delimited form of the <code>=config</code> directive. Each <code>=config</code> specification is lexically scoped to the surrounding block in which it is specified. Note that, if a particular block later explicitly specifies a configuration option with the same key, that option overrides the pre-configured option. For example, given the heading configurations in the previous example, to specify a non-basic second-level heading: <blockquote><pre>=for head2 :formatted Details </pre></blockquote>The <code>:like</code> option causes the current formatting options for the named block type to be (lexically) replaced by the complete formatting information of the block type specified as the <code>:like</code>'s value. That other block type must already have been preconfigured. Any additional formatting specifications are subsequently added to that config. For example: <blockquote><pre>=comment In the current scope make =head2 an "important" variant of =head1 =config head2 :like<head1> :formatted </pre></blockquote>Incidentally, this also means you can arrange for an explicit <code>:formatted</code> option to augment an existing <code>=config</code>, rather than replacing it. Like so: <blockquote><pre>=comment Mark this =head3 (but only this one) as being important (in addition to the normal formatting)... =head3 :like<head3> :formatted </pre></blockquote><h3><a name="Pre-configuring formatting codes"><a name="26758184">Pre-configuring formatting codes </a></a></h3> You can also lexically preconfigure a <a href="#Formatting codes">formatting code</a>, by naming it with a pair of angles as a suffix. For example: <blockquote><pre>=comment Always allow E<> codes in any (implicit or explicit) V<> code... =config V<> :allow<E> </pre></blockquote><blockquote><pre>=comment All inline code to be marked as important... =config C<> :formatted </pre></blockquote>Note that, even though the formatting code is named using single-angles, the preconfiguration applies regardless of the actual delimiters used on subsequent instances of the code. <h2><a name="Modules"><a name="26764208">Modules </a></a></h2> Perldoc provides a mechanism by which you can extend the syntax, semantics, or content of your documentation: the <code>=use</code> directive. Specifying a <code>=use</code> causes a Perldoc processor to load the corresponding Perldoc module at that point, or to throw an exception if it cannot. Such modules can specify additional content that should be included in the document. Alternatively, they can register classes that handle new types of block directives or formatting codes. Note that a module loaded via a <code>=use</code> statement can affect the content or the interpretation of subsequent blocks, but not the initial parsing of those blocks. Any new block types must still conform to the general syntax described in this document. Typically, a module will change the way that renderers parse the contents of specific blocks. A <code>=use</code> directive may be specified with either a module name or a URI: <blockquote><pre>=use <var>MODULE_NAME</var> <var>OPTIONAL CONFIG DAT/var = <var>OPTIONAL EXTRA CONFIG DAT/var </pre></blockquote><blockquote><pre>=use <var>UR/var </pre></blockquote>If a URI is given, the specified file is treated as a source of Pod to be included in the document. Any Pod blocks are parsed out of the contents of the <code>=use</code>'d file, and added to the main file's Pod representation at that point. If a module name is specified, with a language prefix of <code>pod:</code>, then the corresponding <code>.pod</code> file is searched for in the <code>$PERL6DO/code "documentation path". If none is found, the corresponding <code>.pm</code> file is then searched for in the library path (<code>$PERL6LI/code). If either file is found, the Pod is parsed out of it and the resulting block objects inserted into the main file's representation. If a module name is specified with any prefix except <code>pod:</code>, or without a prefix at all, then the corresponding <code>.pm</code> file (or another language's equivalent code module) is searched for in the appropriate module library path. If found, the code module <code>require</code>'d into the Pod parser (usually to add a class implementing a particular Pod extension). If no such code module is found, a suitable <code>.pod</code> file is searched for instead, the contents parsed as Pod, and the resulting block objects inserted into the main file's representation. You can use fully and partially specified module names (as with Perl 6 modules): <blockquote><pre>=use Perldoc::Plugin::XHTML-1.2.1-(*) </pre></blockquote>Any options that are specified after the module name: <blockquote><pre>=use Perldoc::Plugin::Image :Jpeg prefix=>'http://dev.perl.org' </pre></blockquote>are passed to the internal <code>require</code> that loads the corresponding module. Collectively these alternatives allow you to create standard documentation inserts or stylesheets, to include Pod extracted from other code files, or to specify new types of documentation blocks and formatting codes: <ul><li>To create a standard Pod insertion or stylesheet, create a <code>.pod</code> file and install it in your documentation path. Load it with either: <blockquote><pre>=use <var>Pod::Insertion::Name</var> </pre></blockquote>or: <blockquote><pre>=use pod:<var>Pod::Insertion::Name</var> </pre></blockquote>or: <blockquote><pre>=use file:<var>/full/path/spec/Pod/Insertion/Name.pod</var> </pre></blockquote>or even: <blockquote><pre>=use http://<var>www.website.com/Pod/Insertion/Name.pod</var> </pre></blockquote></li>

<li>To insert the Pod from a <code>.pm</code> file (for example, to have your class documentation include documentation from a base class): <blockquote><pre>=use pod:<var>Some::Other::Module</var> </pre></blockquote></li>

<li>To implement a new Pod block type or formatting code, create a <code>.pm</code> file and load it with either: <blockquote><pre>=use <var>New::Perldoc::Subclass</var> </pre></blockquote>or (more explicitly): <blockquote><pre>=use perl6:<var>New::Perldoc::Subclass</var> </pre></blockquote></li>

<li>To create a module that inserts Pod and also <code>require</code>'s a parser extension, install a <code>.pod</code> file that contains a nested <code>=use</code> that imports the necessary plug-in code. Then load the Pod file as above. A typical example would be a Perldoc extension that also needs to specify some <a href="#Block pre-configuration">preconfiguration</a>: <blockquote><pre>=use <var>Hybrid::Content::Plus::Extension</var> </pre></blockquote>Then, in the file <var>some_perl_doc_dir/Hybrid/Content/Plus/Extension.pod</var>: <blockquote><pre>=begin code :allow<R> =comment This file sets some config and also enables the Graph block </pre></blockquote><blockquote><pre>=config Graph :formatted </pre></blockquote><blockquote><pre>=use perl6:Perldoc::Plugin::Graph-(*)-cpan:MEGAGIGA =end code </pre></blockquote></li>

</ul>Note that <code>=use</code> is a fundamental Perldoc directive, like <code>=begin</code> or <code>=encoding</code>, so there is no paragraph or delimited form of <code>=use</code>. <h1><a name="SUMMARY"><a name="26835124">SUMMARY </a></a></h1> <h2><a name="Directives"><a name="26835352">Directives </a></a></h2> <blockquote><a name=""><a name="26835592"><table> <tr> <th> Directive </th> <th> Specifies </th> </tr> <tr> <td> <code>=alias</code> </td> <td> Explicitly define an alias </td> </tr> <tr> <td> <code>=begin</code> </td> <td> Start of an explicitly terminated block </td> </tr> <tr> <td> <code>=config</code> </td> <td> Lexical modifications to a block or formatting code </td> </tr> <tr> <td> <code>=encoding</code> </td> <td> Encoding scheme for subsequent text </td> </tr> <tr> <td> <code>=end</code> </td> <td> Explicit termination of a <code>=begin</code> block </td> </tr> <tr> <td> <code>=for</code> </td> <td> Start of an implicitly (blank-line) terminated block </td> </tr> <tr> <td> <code>=use</code> </td> <td> Transclusion of content; loading of a Perldoc module </td> </tr> </table></a></a> </blockquote><h2><a name="Blocks"><a name="26835820">Blocks </a></a></h2> <blockquote><a name=""><a name="26838648"><table> <tr> <th> Block typename </th> <th> Specifies </th> </tr> <tr> <td> <code>=code</code> </td> <td> Verbatim pre-formatted sample source code </td> </tr> <tr> <td> <code>=comment</code> </td> <td> Content to be ignored by all renderers </td> </tr> <tr> <td> <code>=head</code><var>/var </td> <td> /emth-level heading </td> </tr> <tr> <td> <code>=input</code> </td> <td> Pre-formatted sample input </td> </tr> <tr> <td> <code>=item</code> </td> <td> First-level list item </td> </tr> <tr> <td> <code>=item</code><var>/var </td> <td> /emth-level list item </td> </tr> <tr> <td> <code>=nested</code> </td> <td> Nest block contents within the current context </td> </tr> <tr> <td> <code>=output</code> </td> <td> Pre-formatted sample output </td> </tr> <tr> <td> <code>=para</code> </td> <td> Ordinary paragraph </td> </tr> <tr> <td> <code>=table</code> </td> <td> Simple rectangular table </td> </tr> <tr> <td> <code>=DAT/code </td> <td> Perl 6 data section </td> </tr> <tr> <td> <code>=EN/code </td> <td> No ambient blocks after this point </td> </tr> <tr> <td> <code>=</code><var>RESERVE/var </td> <td> Semantic blocks (<code>=SYNOPI/code, <code>=BUG/code, etc.) </td> </tr> <tr> <td> <code>=</code><var>Typename</var> </td> <td> User-defined block </td> </tr> </table></a></a> </blockquote><h2><a name="Formatting codes"><a name="26838876">Formatting codes </a></a></h2> <blockquote><a name=""><a name="26839068"><table> <tr> <th> Formatting code </th> <th> Specifies </th> </tr> <tr> <td> <code>A<...></code> </td> <td> Ambient back-reference </td> </tr> <tr> <td> <code>B<...></code> </td> <td> Basis/focus of sentence (typically rendered bold) </td> </tr> <tr> <td> <code>C<...></code> </td> <td> Code (typically rendered fixed-width) </td> </tr> <tr> <td> <code>D<...|...;...></code> </td> <td> Definition (<code>D<<var>defined term</var>|<var>synonym</var>;<var>synonym</var>;...></code>) </td> </tr> <tr> <td> <code>E<...></code> </td> <td> Entity name or numeric codepoint </td> </tr> <tr> <td> <code>I<...></code> </td> <td> Important (typically rendered in italics) </td> </tr> <tr> <td> <code>K<...></code> </td> <td> Keyboard input (typically rendered fixed-width) </td> </tr> <tr> <td> <code>L<...|...></code> </td> <td> Link (<code>L<<var>display text</var>|<var>destination UR/var></code>) </td> </tr> <tr> <td> <code>M<...:...></code> </td> <td> Module-defined code (<code>M<<var>scheme</var>:<var>contents</var>></code>) </td> </tr> <tr> <td> <code>N<...></code> </td> <td> Note (not rendered inline) </td> </tr> <tr> <td> <code>P<...></code> </td> <td> Placement link </td> </tr> <tr> <td> <code>R<...></code> </td> <td> Replaceable component or metasyntax </td> </tr> <tr> <td> <code>S<...></code> </td> <td> Space characters to be preserved </td> </tr> <tr> <td> <code>T<...></code> </td> <td> Terminal output (typically rendered fixed-width) </td> </tr> <tr> <td> <code>U<...></code> </td> <td> Unusual (typically rendered with underlining) </td> </tr> <tr> <td> <code>V<...></code> </td> <td> Verbatim (internal formatting codes ignored) </td> </tr> <tr> <td> <code>X<...|..,..;...></code> </td> <td> Index entry (<code>X<<var>display text</var>|<var>entry</var>,<var>subentry</var>;...></code>) </td> </tr> <tr> <td> <code>Z<...></code> </td> <td> Zero-width comment (contents never rendered) </td> </tr> </table></a></a> </blockquote><h1>Notes</h1> <a name="_nb_out_1" href="#_nb_in_1">1</a>A valid identifier is a sequence of alphanumerics and/or underscores, beginning with an alphabetic or underscore <a name="_nb_out_2" href="#_nb_in_2">2</a>Because an <code>=</code> in the first column is always the start of a Pod directive

</body> </html>

11 POD Errors

The following errors were encountered while parsing the POD:

Around line 103:

Deleting unknown formatting code O<>

Deleting unknown formatting code A<>

Unknown E content in E</var>

Around line 441:

Deleting unknown formatting code N<>

Deleting unknown formatting code D<>

Around line 651:

'=end code </pre></blockquote><h3><a name="I/O blocks"><a name="26038992">I/O blocks </a></a></h3> Pod also provides blocks for specifying the input and output of programs. The <code>=input</code> block is used to specify pre-formatted keyboard input, which should be rendered without rejustification or squeezing of whitespace. The <code>=output</code> block is used to specify pre-formatted terminal or file output which should also be rendered without rejustification or whitespace-squeezing. Note that, like <code>=code</code> blocks, both <code>=input</code> and <code>=output</code> blocks have an implicit level of nesting. They are also like <code>=code</code> blocks in that they are typically rendered in a fixed-width font, though ideally all three blocks would be rendered in distinct font/weight combinations (for example: regular serifed for code, bold sans-serif for input, and regular sans-serif for output). Unlike <code>=code</code> blocks, both <code>=input</code> and <code>=output</code> blocks honour any nested formatting codes. This is particularly useful since a sample of input will often include prompts (which are, of course, output). Likewise a sample of output may contain the occasional interactive component. Pod provides <a href="#Example specifiers">special formatting codes</a> (<code>K<></code> and <code>T<></code>) to indicate embedded input or output, so you can use the block type that indicates the overall purpose of the sample (i.e. is it demonstrating an input operation or an output sequence?) and then use the "contrasting" formatting code within the block. For example, to include a small amount of input in a sample of output: <blockquote><pre>=begin output Name: Baracus, B.A. Rank: Sgt Serial: 1PTDF007' is invalid. (Stack: [empty])

Around line 1104:

'=item' outside of any '=over'

Around line 1108:

Deleting unknown formatting code D<>

Deleting unknown formatting code A<>

Around line 1243:

Non-ASCII character seen before =encoding in '(<code>«...»</code>),'. Assuming CP1252

Around line 1378:

A non-empty Z<>

Around line 1663:

Unknown directive: =DESCRIPTION

Around line 1926:

You forgot a '=back' before '=head1'

Around line 1929:

Deleting unknown formatting code T<>

Deleting unknown formatting code A<>

Unknown E content in E</var>

Around line 2143:

Deleting unknown formatting code N<>

Deleting unknown formatting code A<>

Deleting unknown formatting code D<>

To install Perl6::Perldoc, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Perl6::Perldoc

CPAN shell

perl -MCPAN -e shell
install Perl6::Perldoc

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

A heading

Overview of the <strong>M&lt;TT: $CLASSNAME &gt;</strong> class (version <strong>M&lt;TT: $VERSION&gt;</strong>)

Module Install Instructions

Overview of the <strong>M<TT: $CLASSNAME ></strong> class (version <strong>M<TT: $VERSION></strong>)