This file was automatically generated from http://svn.pugscode.org/pugs/docs/Perl6/Spec/Documentation.pod on Wed Jun 27 11:57:19 2007 GMT, revision 16750.
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.
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
Pod predefines a small number of standard configuration options that can be applied uniformly to built-in block types. These include:
Pod offers notations for specifying a range of standard block types...
Pod provides an unlimited number of levels of heading, specified by the
=head 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.
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.
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
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 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)