Spec::Documentation(3)

For example:

     =table
         Constants           1
         Variables           10
         Subroutines         33
         Everything else     57

     =Name     The applicant's full name
     =Contact  The applicant's contact details

Note that abbreviated blocks cannot specify configuration information. If configuration is required, use a "=for" or "=begin"/"=end" instead.

Block equivalence

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 #Headings shows only:

     =head1 Top Level Heading

this automatically implies that you could also write that block as:

     =for head1
     Top Level Heading

or:

     =begin head1
     Top Level Heading
     =end head1

Standard configuration options

Pod predefines a small number of standard configuration options that can be applied uniformly to built-in block types. These include:

  Blocks
Pod offers notations for specifying a range of standard block types...

Headings

Pod provides an unlimited number of levels of heading, specified by the "=head"1 block marker. For example:

    =head1 A Top Level Heading

    =head2 A Second Level Heading

    =head3 A third level heading

    =head86 A "Missed it by I<that> much!" heading

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.

Numbered headings

You can specify that a heading is numbered using the ":numbered" option. For example:

    =for head1 :numbered
    The Problem

    =for head1 :numbered
    The Solution

    =for head2 :numbered
    Analysis

    =for head3
    Overview

    =for head3
    Details

    =for head2 :numbered
    Design

    =for head1 :numbered
    The Implementation

which would produce:

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 "#". For example:

To refer to a section of the current document, omit the external address:

The scheme name may also be omitted in that case:

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:

Note that "=use" is a fundamental Perldoc directive, like "=begin" or "=encoding", so there is no paragraph or delimited form of "=use".

SUMMARY

  Directives =begin table :nested
    Directive           Specifies
    _________           ____________________________________________________
    C<=begin>           Start of an explicitly terminated block
    C<=config>          Lexical modifications to a block or formatting code
    C<=encoding>        Encoding scheme for subsequent text
    C<=end>             Explicit termination of a C<=begin> block
    C<=for>             Start of an implicitly (blank-line) terminated block
    C<=use>             Transclusion of content; loading of a Perldoc module

  Blocks =begin table :nested
    Block typename      Specifies
    ______________      ___________________________________________________
    C<=code>            Verbatim pre-formatted sample source code
    C<=comment>         Content to be ignored by all renderers
    C<=head>R<N>        I<N>th-level heading
    C<=input>           Pre-formatted sample input
    C<=item>            First-level list item
    C<=item>R<N>        I<N>th-level list item
    C<=nested>          Nest block contents within the current context
    C<=output>          Pre-formatted sample output
    C<=para>            Ordinary paragraph
    C<=table>           Simple rectangular table
    C<=DATA>            Perl 6 data section
    C<=END>             No ambient blocks after this point
    C<=>R<RESERVED>     Semantic blocks (C<=SYNOPIS>, C<=BUGS>, etc.)
    C<=>R<Typename>     User-defined block

  Formatting codes =config :allow<R V> =begin table :nested
    Formatting code      Specifies
    _______________      ___________________________________________________
    C<B<...>>            Basis/focus of sentence (typically rendered bold)
    C<C<...>>            Code (typically rendered fixed-width)
    C<D<...|...;...>>    Definition (C<D<R<defined term>|R<synonym>;R<synonym>;...>>)
    C<E<...>>            Entity name or numeric codepoint
    C<I<...>>            Important (typically rendered in italics)
    C<K<...>>            Keyboard input (typically rendered fixed-width)
    C<L<...|...>>        Link (C<L<R<display text>|R<destination URI>>>)
    C<M<...:...>>        Module-defined code (C<M<R<scheme>:R<contents>>>)
    C<N<...>>            Note (not rendered inline)
    C<P<...>>            Placement link
    C<V<R><...>>         Replaceable component or metasyntax
    C<S<...>>            Space characters to be preserved
    C<T<...>>            Terminal output (typically rendered fixed-width)
    C<U<...>>            Unusual (typically rendered with underlining)
    C<V<V><...>>         Verbatim (internal formatting codes ignored)
    C<X<...|..,..;...>>  Index entry (C<X<R<display text>|R<entry>,R<subentry>;...>>)
    C<Z<...>>            Zero-width comment (contents never rendered)