=begin pod =comment This file is deliberately specified in Perl 6 Pod format =TITLE Synopsis 26 - Documentation =begin VERSION =table Maintainer: Damian Conway Date: 9 Apr 2005 Last Modified: 25 Jul 2014 =end VERSION =head1 Pod D 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|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. =head2 General syntactic structure Pod documents are specified using D, 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, or with a C<#=> or 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<#=> or 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, 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. =head2 Pod blocks The content of a document is specified within one or more D. Every Pod block may be declared in any of four forms: L|#Delimited blocks>, L|#Paragraph blocks>, L|#Abbreviated blocks>, or L|#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 block. Renderers will I 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 block: =begin code :allow B<=begin pod> =head1 A heading This is Pod too. Specifically, this is a simple C block $this = pod('also'); # Specifically, a code block B<=end pod> =end code =head3 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 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: =for table :nested 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» 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}» All option keys and values must, of course, be constants since Pod is a specification language, not a programming language. Specifically, option values cannot be closures. See Synopsis 2 for details of the various Perl 6 pair notations. The configuration section may be extended over subsequent lines by starting those lines with an C<=> in the first (virtual) 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 matching C<=end> marker line. For most block types, these contents may be indented if you wish, without them being treated as L. Unlike Perl 5, indented text is only treated as code within C<=pod>, L|#Nesting blocks>, L|#Lists>, C<=code>, and L blocks. The general syntax is: =begin code :allow< R > =begin R R = R R =end R =end code For example: =begin code =begin table :caption Constants 1 Variables 10 Subroutines 33 Everything else 57 =end table =begin Name :required = :width(50) The applicant's full name =end Name =begin Contact :optional The applicant's contact details =end Contact =end code 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: C. Pod uses blank lines as delimiters, rather than empty lines, to minimize unpleasant surprises when stray spaces or tabs mysteriously turn up in hitherto empty lines. =head3 Paragraph blocks Paragraph blocks are introduced by a C<=for> marker and terminated by the next Pod directive or the first blank line (which is I considered to be part of the block's contents). The C<=for> marker is followed by the name of the block and optional configuration information. The general syntax is: =begin code :allow< R > =for R R = R R =end code For example: =begin code =for table :caption Constants 1 Variables 10 Subroutines 33 Everything else 57 =for Name :required = :width(50) The applicant's full name =for Contact :optional The applicant's contact details =end code =head3 Abbreviated blocks Abbreviated blocks are introduced by an C<'='> 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: =begin code :allow< R > =R R R =end code For example: =begin code =table Constants 1 Variables 10 Subroutines 33 Everything else 57 =Name The applicant's full name =Contact The applicant's contact details =end code Note that abbreviated blocks cannot specify configuration information. If configuration is required, use a C<=for> or C<=begin>/C<=end> instead. =head3 Declarator blocks The fourth form of Pod block differs from the first three in that it does not specify an explicit typename. Instead, it obtains its identity and purpose from the Perl 6 source code to which it is attached; specifically, from some nearby declarator. Declarator blocks are introduced by a special Perl comment: either C<#=> or C<#|>, which must be immediately followed by either by a space or an opening bracket. If followed by a space, the block is terminated by the end of line; if followed by one or more opening brackets, the block is terminated by the matching sequence of closing brackets. That is, declarator Pod blocks are syntactically like ordinary Perl 6 single-line comments and embedded comments. The general syntax is: =begin code :allow< R > #| R #|{ R R } #= R #={ R R } =end code except that the bracketed forms may use I valid Perl 6 bracket delimiter (including repeated opening brackets), as described in Synopsis 2. Declarator Pod blocks must either precede or immediately follow a valid Perl 6 declarator, and are then said to be "attached" to it. They are primarily intended to simplify the documentation of code interfaces. Declarator blocks that start with C<#|> attach to the declarator immediately after them (separated only by whitespace). Declarator blocks that start with C<#=> attach to the declarator declared at the start of the line immediately before them. In all other respects they act just like comments (i.e. they are themselves whitespace as far as ambient source code is concerned). This means multiple declarator blocks can be specified in a row and will all attach to the same declarator. For example: =begin code #| Base class for comms necromancy hierarchy class Magic::Necrotelecomnicon { has $.elemental; #= Source of all power has $!true_name; # Source of all self-protection (not documented) method cast(#|{ A spell } Spell $s) #= Initiate a specified spell normally #= (do not use for class 7 spells) { do_raw_magic($s); } method kast( #= Initiate a specified spell abnormally Spell $s #= The spell to be abnormally initiated ) { do_raw_magic($s, :alternative); } #| This subroutine does the real work sub do_raw_magic ( Spell $s, #= Which spell to invoke *%options #= How to invoke it ) {...} } sub fu (Any $bar) #=[ This text stored in C<&fu.WHY>, not in C<$bar.WHY>, (because C_{is the declarator at the I of the preceding line) ] multi sub baz(Int $count, Str $name) #=[ This text stored in C<&baz:(Int,Str).WHY> (i.e. the C<.WHY> of the variant, not of the entire multisub) ] #| Attaches to the specific parameterized role, rather than the role group itself role R[::T] {} role R {} =end code A declarator can have multiple leading and/or trailing Pod comments, in which case they are concatenated with an intermediate newline when their object's C<.WHY> return value is stringified: #| This is a special chainsaw #| (Why, you ask?) my SwissArmy $chainsaw #= (It has a rocket launcher!) say $chainsaw.WHY; # prints: This is a special chainsaw # (Why, you ask?) # (It has a rocket launcher!) The individual leading and trailing Pod comments can be retrieved via the returned Pod object's C<.leading> and C<.trailing> methods: say $chainsaw.WHY.leading; # prints: This is a special chainsaw (Why, you ask?) say $chainsaw.WHY.trailing; # prints: (It has a rocket launcher!) The Pod object representing each Declarator block is still appended to the current surrounding Pod object (e.g. to C<$=pod> at the top level). Each such block representation is an object of class C, and has a C<.WHEREFORE> method that returns the code object or metaobject created by the declarator to which the documentation is attached. In other words, C<.WHY> and C<.WHEREFORE> are inverse operations: =code .WHY ---------------------------- | | | v ----------------- ----------------- | Declared code | | Documentation | | object | | object | ----------------- ----------------- ^ | | | ---------------------------- .WHEREFORE When the L block|#How Pod is parsed and processed> renders these Pod objects, it automatically includes information about the declarator as well. For instance, the earlier Necrotelecomnicon example might produce something like: =begin output Name: Magic::Necrotelecomnicon: Desc: Base class for comms necromancy hierarchy Attrs: .elemental : Source of all power Methods: .cast(Spell $s) : Initiate a specified spell normally .kast(Spell $s) : Initiate a specified spell abnormally Subroutines: do_raw_magic( : This subroutine does the real work Spell $s, : Which spell to invoke *%options : How to invoke it ) =end output Note, however, that the exact rendering used for declarator blocks is implementation dependent, and may also be pre-empted explicitly by some L configuration statement|#How Pod is parsed and processed> within the document, such as: DOC use Pod::Markovian; or: DOC INIT { use Pod::Eiffelish::Long; say eiffelish_long($=pod); exit; } =head3 Block equivalence The first 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 L<#Headings> shows only: =begin code =head1 Top Level Heading =end code this automatically implies that you could also write that block as: =begin code =for head1 Top Level Heading =end code or: =begin code =begin head1 Top Level Heading =end head1 =end code Declarator blocks are distinct from these three forms. They do not have typenames of their own, but rather take their meaning and identity from the declared object or type to which they are attached. In general, they are used specifically to describe that declarand. =head3 Standard configuration options Pod predefines a small number of standard configuration options that can be applied uniformly to any built-in block type. These include: =begin defn C<:nested> 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 L|#Code blocks>, L|#Lists>, L|#I/O blocks>, and L|#I/O blocks> 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 other 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: =begin code =begin para :nested =begin para :nested =begin para :nested "We're going deep, deep, I undercover!" =end para =end para =end para =end code This can be simplified by giving the C<:nested> option a positive integer value: =begin code :allow =begin para B<:nested(3)> "We're going deep, deep, I undercover!" =end para =end code 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 I its usual nesting: =begin code :allow =comment Don't nest this code block in the usual way... B<=begin code :nested(0)> 1 2 3 4 5 6 123456789012345678901234567890123456789012345678901234567890 |------|-----------------------|---------------------------| line instruction comments number code V<=end code> =end code Note that C<:!nested> could also be used for this purpose: =begin code =Z<>begin code :!nested =end code =end defn =begin defn C<:numbered> This option specifies that the block is to be numbered. The most common use of this option is to create L and L, but it can be applied to any block. The numbering conventions for headings and lists are specified in those sections, but it is up to individual renderers to decide how to display any numbering associated with other types of blocks. Note that numbering is never explicit; it is always implied by context. =end defn =begin defn C<:formatted> This option specifies that the contents of the block should be treated as if they had one or more L placed around them. For example, instead of: =begin code =for comment The next para is both important and fundamental, so doubly emphasize it... =begin para B> =end para =end code you can just write: =begin code :allow =begin para B<:formatted> Warning: Do not immerse in water. Do not expose to bright light. Do not feed after midnight. =end para =end code The internal representations of these two versions are exactly the same, except that the second one retains the C<:formatted> option information as part of the resulting block object. Like all formatting codes, codes applied via a C<:formatted> 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 C<:formatted>. =end defn =begin defn C<:like> 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 L or for making user-defined synonyms for existing types. For example: =begin code =config head2 :like :formatted =config Subhead :like =end code =end defn =begin defn C<:allow> This option expects a list of formatting codes that are to be recognized within any C> codes that appear in (or are implicitly applied to) the current block. The option is most often used on C<=code> blocks to allow mark-up within those otherwise verbatim blocks, though it can be used in I block that contains verbatim text. See L<#Formatting within code blocks>. =end defn =begin defn C<:margin> This option specifies a character that indicates the left margin of the contents of the block. Normally this left margin is determined by the column at which the C<=> of the opening block-delimiter occurs. For example: =begin code =head1 Indenting Pod blocks =begin para This text is flush with the (virtual) left margin of the Pod block because that margin is implicitly specified by the C<=> of the C<=begin> =end para =end code However, by using the C<:margin> option it is possible to specify a character that acts like an explicit margin when it occurs as the first non-whitespace character on any line within the block. For example: =begin code =head1 Indenting Pod blocks =begin para :margin<|> |This text is flush with the (virtual) left margin of |the Pod block because that margin is explicitly marked |by the C<|>, as specified by the block's C<:margin<|>> option. =end para =end code The virtual margin can even be to the left of the opening delimiter, which can be convenient to guide subsequent indentations. For example: =begin code sub foo { V<=begin> pod :margin<|> |=head1 Hey Look: Indented Pod! | |You can indent Pod in Perl 6 |which makes code look cleaner |when documentation is interspersed | | my $this is Code; | |=end pod ... } =end code When a C<:margin> option is used, each subsequent line (until the corresponding closing delimiter is encountered) simply has any text matching C automatically removed. This may include a line that then becomes the closing delimiter, as in the above example. Any line from which such a margin marker is removed automatically resets the implicit margin for subsequent lines of the block, setting it to the length of the "marginalized" indent that was just removed. This implicit margin is then used until the next line with an explicit margin marker is encountered, or the block terminates. =end defn =head2 Block types Pod offers notations for specifying a wide range of standard block types... =head3 Headings Pod provides an unlimited number of levels of heading, specified by the C<=head>R block marker. For example: =begin code =head1 A Top Level Heading =head2 A Second Level Heading =head3 A third level heading =head86 A "Missed it by I much!" heading =end code While Pod parsers are required to recognize and distinguish all levels of heading, Pod renderers are only required to provide distinct I 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. =head4 Numbered headings You can specify that a heading is numbered using the C<:numbered> option. For example: =begin code =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 =end code which would produce: =begin nested :formatted 1. The Problem 2. The Solution =begin nested 2.1. Analysis =begin nested Overview Details =end nested 2.2: Design =end nested 3. The Implementation =end nested It is usually better to preset a numbering scheme for each heading level, in a series of L: =begin code :allow B<=config head1 :numbered Z<>=config head2 :numbered Z<>=config head3 :!numbered> =head1 The Problem =head1 The Solution =head2 Analysis =head3 Overview =head3 Details =head2 Design =head1 The Implementation =end code Alternatively, as a short-hand, if the first whitespace-delimited word in a heading consists of a single literal C<#> character, the C<#> is removed and the heading is treated as if it had a C<:numbered> option: =begin code =head1 # The Problem =head1 # The Solution =head2 # Analysis =head3 Overview =head3 Details =head2 # Design =head1 # The Implementation =end code Note that, even though renderers are not required to distinctly render more than the first four levels of heading, they I required to correctly honour arbitrarily nested numberings. That is: =begin code =head6 # The Rescue of the Kobayashi Maru =end code should produce something like: =nested B<2.3.8.6.1.9. The Rescue of the Kobayashi Maru> =head3 Ordinary paragraph blocks 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 L applied. Ordinary paragraphs consist of one or more consecutive lines of text, each of which starts with a non-whitespace character at (virtual) column 1. The paragraph is terminated by the first blank line or block directive. For example: =begin code =head1 This is a heading block This is an ordinary paragraph. Its text will be squeezed and short lines filled. It is terminated by the first blank line. 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 This is yet another ordinary paragraph, at the first virtual column set by the previous directive =end code Within a C<=pod>, C<=item>, C<=defn>, C<=nested>, C<=finish>, or L block, ordinary paragraphs do not require an explicit marker or delimiters, but there is also an explicit C marker (which may be used anywhere): =begin code :allow B<=para> This is an ordinary paragraph. Its text will be squeezed and short lines filled. =end code and likewise the longer C<=for> and C<=begin>/C<=end> forms. For example: =begin code :allow B<=begin para> This is an ordinary paragraph. Its text will be squeezed and short lines filled. This is I part of the same paragraph, which continues until an... B<=end para> =end code As the previous example implies, when any form of explicit C block is used, any whitespace at the start of each line is removed during rendering. In addition, within a delimited C<=begin para>/C<=end para> block, any blank lines are preserved. =head3 Code blocks 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 L 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. A code block may be implicitly specified as one or more lines of text, each of which starts with a whitespace character at the block's virtual left margin. The implicit code block is then terminated by a blank line. For example: =begin code This ordinary paragraph introduces a code block: $this = 1 * code('block'); $which.is_specified(:by); =end code Implicit code blocks may only be used within C<=pod>, C<=item>, C<=defn>, C<=nested>, C<=finish>, or L blocks. There is also an explicit C<=code> block (which can be specified within I other block type, not just C<=pod>, C<=item>, etc.): =begin code :allow The C subroutine adds feedback: B<=begin code> sub loud_update ($who, $status) { say "$who -> $status"; silent_update($who, $status); } B<=end code> =end code As the previous example demonstrates, within an explicit C<=code> block the code can start at the (virtual) left margin. Furthermore, lines that start with whitespace characters after that margin have subsequent whitespace preserved exactly (in addition to the implicit nesting of the code). Explicit C<=code> blocks may also contain empty lines. =head4 Formatting within code blocks Although C<=code> blocks automatically disregard all L, 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 C> code). Or you may want to indicate that part of the example is metasyntactic (using the C> code). Or you might need to insert a non-ASCII character (using the C> code). You can specify a list of formatting codes that should still be recognized within a code block using the C<:allow> option. The value of the C<:allow> 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: =begin code =begin code :allow< B R > sub demo { B 'Hello R'; } =end code =end code would be rendered: =begin code :allow< B R > sub demo { B 'Hello R'; } =end code Note that the use of the C<:allow> option also makes it possible for verbatim L (such as C> and C>) to L. =head3 I/O blocks Pod also provides blocks for specifying the input and output of programs. The C<=input> block is used to specify pre-formatted keyboard input, which should be rendered without rejustification or squeezing of whitespace. The C<=output> block is used to specify pre-formatted terminal or file output which should also be rendered without rejustification or whitespace-squeezing. Note that, like C<=code> blocks, both C<=input> and C<=output> blocks have an implicit level of nesting. They are also like C<=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 C<=code> blocks, both C<=input> and C<=output> 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 L (C> and C>) 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 you could use the C> formatting code: =begin code :allow =begin output Name: Baracus, B.A. Rank: Sgt Serial: 1PTDF007 Do you want additional personnel details? B> Height: 180cm/5'11" Weight: 104kg/230lb Age: 49 Print? B> =end output =end code =head3 Lists Lists in Pod are specified as a series of contiguous C<=item> blocks. No special "container" directives or other delimiters are required to enclose the entire list. For example: =begin code The seven suspects are: =item Happy =item Dopey =item Sleepy =item Bashful =item Sneezy =item Grumpy =item Keyser Soze =end code List items have one implicit level of nesting: =begin nested The seven suspects are: =item Happy =item Dopey =item Sleepy =item Bashful =item Sneezy =item Grumpy =item Keyser Soze =end nested Lists may be multi-level, with items at each level specified using the C<=item1>, C<=item2>, C<=item3>, etc. blocks. Note that C<=item> is just an abbreviation for C<=item1>. For example: =begin code =item1 Animal =item2 Vertebrate =item2 Invertebrate =item1 Phase =item2 Solid =item2 Liquid =item2 Gas =item2 Chocolate =end code which would be rendered something like: =for para :nested E Animal =for para :nested(2) E Vertebrate =for para :nested(2) E Invertebrate =for para :nested E Phase =for para :nested(2) E Solid =for para :nested(2) E Liquid =for para :nested(2) E Gas =for para :nested(2) E Chocolate Pod parsers must issue a warning if a "level-R" C<=item> block (e.g. an C<=item2>, C<=item3>, etc.) appears anywhere except where there is a preceding "level-R" C<=item> in the same surrounding block. That is, an C<=item3> should only be specified if an C<=item2> appears somewhere before it, and that C<=item2> should itself only appear if there is a preceding C<=item1>. Note that item blocks within the same list are not physically nested. That is, lower-level items should I be specified inside higher-level items: =begin code =comment WRONG... =begin item1 -------------- The choices are: | =item2 Liberty ==< Level 2 |==< Level 1 =item2 Death ==< Level 2 | =item2 Beer ==< Level 2 | =end item1 -------------- =end code =begin code =comment CORRECT... =begin item1 --------------- The choices are: |==< Level 1 =end item1 --------------- =item2 Liberty ==================< Level 2 =item2 Death ==================< Level 2 =item2 Beer ==================< Level 2 =end code =head4 Ordered lists An item is part of an ordered list if the item has a C<:numbered> configuration option: =begin code =for item1 :numbered Visito =for item2 :numbered Veni =for item2 :numbered Vidi =for item2 :numbered Vici =end code This would produce something like: =begin nested 1. Visito =begin nested 1.1. Veni 1.2. Vidi 1.3. Vici =end nested =end nested although the numbering scheme is entirely at the discretion of the renderer, so it might equally well be rendered: =begin nested 1. Visito =begin nested 1a. Veni 1b. Vidi 1c. Vici =end nested =end nested or even: =begin nested A: Visito =begin nested E(i) Veni E(ii) Vidi (iii) Vici =end nested =end nested Alternatively, if the first word of the item consists of a single C<#> character, the item is treated as having a C<:numbered> option: =begin code =item1 # Visito =item2 # Veni =item2 # Vidi =item2 # Vici =end code To specify an I list item that starts with a literal C<#>, either make the octothorpe verbatim: =begin code :allow =item B> introduces a comment =end code or explicitly mark the item itself as being unnumbered: =begin code :allow =for item B<:!numbered> # introduces a comment =end code The numbering of successive C<=item1> list items increments automatically, but is reset to 1 whenever any other kind of non-ambient Pod block appears between two C<=item1> blocks. For example: =begin code The options are: =item1 # Liberty =item1 # Death =item1 # Beer The tools are: =item1 # Revolution =item1 # Deep-fried peanut butter sandwich =item1 # Keg =end code would produce: =begin nested The options are: =begin nested =para 1. Liberty =para 2. Death =para 3. Beer =end nested The tools are: =begin nested =para 1. Revolution =para 2. Deep-fried peanut butter sandwich =para 3. Keg =end nested =end nested The numbering of nested items (C<=item2>, C<=item3>, etc.) only resets (to 1) when the higher-level item's numbering either resets or increments. To prevent a numbered C<=item1> from resetting after a non-item block, you can specify the C<:continued> option: =begin code :allow =for item1 # Retreat to remote Himalayan monastery =for item1 # Learn the hidden mysteries of space and time I =for item1 B<:continued> # Prophet! =end code which produces: =begin nested =para 1. Retreat to remote Himalayan monastery =para 2. Learn the hidden mysteries of space and time =para I =para 3. Prophet! =end nested =head4 Unordered lists List items that are not C<:numbered> are treated as defining unordered lists. Typically, such lists are rendered with bullets. For example: =begin code =item1 Reading =item2 Writing =item3 'Rithmetic =end code might be rendered: =for para :nested(1) EReading =for para :nested(2) EWriting =for para :nested(3) E'Rithmetic As with numbering styles, the bulletting strategy used for different levels within a nested list is entirely up to the renderer. =head4 Multi-paragraph list items Use the delimited form of the C<=item> block to specify items that contain multiple paragraphs. For example: =begin code Let's consider two common proverbs: =begin item :numbered I This is a common myth and an unconscionable slur on the Spanish people, the majority of whom are extremely attractive. =end item =begin item :numbered I In deciding whether to become an early riser, it is worth considering whether you would actually enjoy annelids for breakfast. =end item As you can see, folk wisdom is often of dubious value. =end code which produces: =begin nested =config item :numbered Let's consider two common proverbs: =begin item I This is a common myth and an unconscionable slur on the Spanish people, the majority of whom are extremely attractive. =end item =begin item I In deciding whether to become an early riser, it is worth considering whether you would actually enjoy annelids for breakfast. =end item As you can see, folk wisdom is often of dubious value. =end nested =head4 Definition lists To create term/definition lists, use a C<=defn> block. This is similar in effect to an C<=item> block, in that a series of C<=defn> blocks implicitly defines a list (but which might then be rendered into HTML using C«... » tags, rather than C«...» tags) The first non-blank line of content is treated as a term being defined, and the remaining content is treated as the definition for the term. For example: =begin code =defn MAD Affected with a high degree of intellectual independence. =defn MEEKNESS Uncommon patience in planning a revenge that is worth while. =defn MORAL Conforming to a local and mutable standard of right. Having the quality of general expediency. =end code Like other kinds of list items, definitions can be numbered, using either an option or a leading C<#>: =begin code :allow =for defn B<:numbered> SELFISH Devoid of consideration for the selfishness of others. =defn B<#> SUCCESS The one unpardonable sin against one's fellows. =end code =head3 Nesting blocks Any block can be nested by specifying a C<:nested> option on it: =begin code :allow =begin para B<:nested> We are all of us in the gutter,E but some of us are looking at the stars! =end para =end code However, qualifying each nested paragraph individually quickly becomes tedious if there are many in a sequence, or if multiple levels of nesting are required: =begin code :allow =begin para B<:nested> We are all of us in the gutter,E but some of us are looking at the stars! =end para =begin para B<:nested(2)> -- Oscar Wilde =end para =end code So Pod provides a C<=nested> block that marks all its contents as being nested: =begin code :allow B<=begin nested> We are all of us in the gutter,E but some of us are looking at the stars! B<=begin nested> -- Oscar Wilde B<=end nested> B<=end nested> =end code Nesting blocks can contain any other kind of block, including implicit paragraph and code blocks. Note that the relative physical indentation of the blocks plays no role in determining their ultimate nesting. The preceding example could equally have been specified: =begin code :allow B<=begin nested> We are all of us in the gutter,E but some of us are looking at the stars! B<=begin nested> -- Oscar Wilde B<=end nested> B<=end nested> =end code =head3 Tables Simple tables can be specified in Pod using a C<=table> block. The table may be given an associated description or title using the C<:caption> option. Columns are separated by two or more consecutive whitespace characters (double-space), or by a vertical line (C<|>) or a border intersection (C<+>), either of which must be separated from any content by at least one whitespace character. Note that only one column separator type is allowed in a single line, but different lines are allowed to use different visible column separator types (that style is not recommended). Using a mixture of visible and non-visible column separator types in a table is an error. 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 (C<+>), or horizontal lines: C<->, C<=>, C<_>) between I row. Either style can also have an explicitly separated header row at the top. If rows are using the two-whitespace-character separator, the row cells should be carefully aligned to ensure the table is interpreted as the user intended. Each individual table cell is separately formatted, as if it were a nested C<=para>. Note that table rows are expected to have the same number of cells. This means you can create tables compactly, line-by-line: =begin code =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 =end code or line-by-line with multi-line headers: =begin code =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 =end code or with multi-line headers I multi-line data: =begin code =begin table :caption('The Other Guys') Secret Superhero 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 =end table =end code =head3 Named blocks Blocks whose names contain at least one uppercase and one lowercase letter are assumed to be destined for specialized renderers or parser plug-ins. For example: =begin code =begin Xhtml}