=begin pod =for comment This file is deliberately specified in Perl 6 Pod format Clearly a Perl 6 -> Perl 5 documentation translator is a high priority ;-) =head1 TITLE Synopsis 26 - Documentation =head1 AUTHOR Damian Conway |mailto:damian@conway.org>> =head1 VERSION =table Maintainer: Damian Conway Date: 9 Apr 2005 Last Modified: 22 Nov 2006 =head1 Perldoc Perldoc is an easy-to-use markup language with a simple, consistent underlying document object model. Perldoc can be used for writing language documentation, for documenting programs and modules, as well as for other types of document composition. Perldoc allows for multiple syntactic I, all of which map onto the same set of standard document objects. The standard dialect is named "Pod". =head1 The Pod Dialect B is an evolution of Perl 5's L|doc:perlpod> (POD) markup. Compared to Perl 5 POD, Perldoc's Pod dialect 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. Every directive starts with an equals sign (C<=>) in the first column. The content of a document is specified within one or more D. Every Pod block may be declared in any of three equivalent forms: L|#Delimited blocks>, L|#Paragraph blocks>, or L|#Abbreviated blocks>. 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 an C block), but renderers will usually ignore such blocks. 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 between POD and ambient text. The Perl 6 Pod format is different. A 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 Alternatively you can indicate an entire file contains only Pod, by giving it a C<.pod> suffix. =head3 Delimited blocks Delimited blocks are bounded by C<=begin> and C<=end> markers, both of which are followed by a valid identifierN, 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, and is specified using Perl6ish C<:key> or C<< key=>value >> pairs (which must, of course, be constants since Perldoc is a specification language, not a programming language). See L for a summary of the Perl 6 pair notation. The configuration section may be extended over subsequent lines by starting those lines with an C<=> 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 C<=end> marker line. The general syntax is: =begin code :allow< R > =begin R R = R R =end R =end code For example: =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 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, rather than empty lines, as delimiters on the principle of least surprise. =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: =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 =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: =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 C<=for> or C<=begin>/C<=end> instead. =head3 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 L<#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 =head3 Standard configuration options Pod predefines a small number of standard configuration options that can be applied uniformly to built-in block types. These include: =begin item :term> 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 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: =begin para :nested =begin para :nested =begin para :nested "We're going deep, deep, I undercover!" =end para =end para =end para This can be simplified by giving the C<:nested> option a positive integer value: =for code :allow =begin para B<:nested(3)> "We're going deep, deep, I undercover!" =end para 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: =for 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 =end code Note that C<:!nested> could also be used for this purpose: =begin code :!nested =end item =begin item :term> 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. It is up to individual renderers to decide how to display any numbering associated with other types of blocks. =end item =for item :term> This option specifies that a list item is the definition of a term. See L<#Definition lists>. =begin item :term> 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: =for comment The next para is both important and fundamental, so doubly emphasize it... =begin para B> =end para you can just write: =for 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 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 item =begin item :term> 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. For example: =config head2 :like :formatting =end item =for item :term> 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>. =head2 Blocks Pod offers notations for specifying a 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: =head1 A Top Level Heading =head2 A Second Level Heading =head3 A third level heading =head86 A "Missed it by I much!" heading 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: =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: =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: =for code :allow B<=config head1 :numbered =config head2 :numbered =config head3 :!numbered> =head1 The Problem =head1 The Solution =head2 Analysis =head3 Overview =head3 Details =head2 Design =head1 The Implementation 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: =head1 # The Problem =head1 # The Solution =head2 # Analysis =head3 Overview =head3 Details =head2 # Design =head1 # The Implementation 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: =head6 # The Rescue of the Kobayashi Maru 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 currently 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 column 1. The paragraph is terminated by the first blank line or opening block directive. For example: =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 Within a C<=pod>, C<=item>, or C<=nested> block, ordinary paragraphs do not require an explicit marker or delimiters, but there is also an explicit C marker (which may be used anywhere): =para This is an ordinary paragraph. Its text will be squeezed and short lines filled. and likewise the longer C<=for> and C<=begin>/C<=end> forms. For example: =begin para This is an ordinary paragraph. Its text will be squeezed and short lines filled. =end para As the previous example implies, when any form of explicit C 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. =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. The block is 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<=nested>, or C<=END> 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 first column. Furthermore, lines that start with whitespace characters have that 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 :allow< B R > sub demo { B 'Hello R'; } =end code would be rendered: =begin code :allow< B R > sub demo { B 'Hello R'; } =end code Although code blocks are verbatim by default, it can still occasionally be useful to explicitly C<:allow> the verbatim formatting code (C>). That's because, although the contents of an explicit C<=code> block are allowed to start in column 1, they are not allowed to start with an equals sign in that first columnN in the first column is I the start of a Pod directive>. So, if an C<=> is needed in column 1, it must be declared L: =begin code :allow =begin code :allow B> in the first column is always a Perldoc directive =end code =end code =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 particular 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: =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: 105kg/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: The seven suspects are: =item Happy =item Dopey =item Sleepy =item Bashful =item Sneezy =item Grumpy =item Keyser Soze 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: =item1 Animal =item2 Vertebrate =item2 Invertebrate =item1 Phase =item2 Solid =item2 Liquid =item2 Gas =item2 Chocolate 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 It is an error for a "level-R" C<=item> block (e.g. an C<=item2>, C<=item3>, etc.) to appear anywhere except where there is a preceding "level-R" C<=item>. That is, an C<=item3> can only be specified if an C<=item2> appears somewhere before it, and that C<=item2> can 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: =comment WRONG... =begin item1 -------------- The choices are: | =item2 Liberty ==< Level 2 |==< Level 1 =item2 Death ==< Level 2 | =item2 Beer ==< Level 2 | =end item1 -------------- =comment CORRECT... =begin item1 --------------- The choices are: |==< Level 1 =end item1 --------------- =item2 Liberty ==================< Level 2 =item2 Death ==================< Level 2 =item2 Beer ==================< Level 2 =head4 Ordered lists An item is part of an ordered list if the item has a C<:numbered> configuration option: =for item1 :numbered Visito =for item2 :numbered Veni =for item2 :numbered Vidi =for item2 :numbered Vici 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 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: =item1 # Visito =item2 # Veni =item2 # Vidi =item2 # Vici To specify an I list item that starts with a literal C<#>, either make it verbatim: =for code :allow =item B> introduces a comment or explicitly mark the item itself as being unnumbered: =for code :allow =for item B<:!numbered> # introduces a comment The numbering of successive C<=item1> list items increments automatically, but is reset to 1 whenever any other kind of non-ambient Perldoc block appears between to C<=item1> blocks. For example: The options are: =item1 # Liberty =item1 # Death =item1 # Beer The tools are: =item1 # Revolution =item1 # Deep-fried peanut butter sandwich =item1 # Keg 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 Definition lists To create term/definition lists, specify the term as a configuration value of the item, and the definition as the item's contents: =begin code :allow =for item B<:term> Affected with a high degree of intellectual independence. =for item B<:term> Uncommon patience in planning a revenge that is worth while. =for item B<:term> Conforming to a local and mutable standard of right. Having the quality of general expediency. =end code An item that's specified as a term can still be numbered: =begin code :allow =for item B<:numbered> :term Devoid of consideration for the selfishness of others. =for item B<:numbered> :term The one unpardonable sin against one's fellows. =end code =head4 Unordered lists List items that do not specify either the C<:numbered> or C<:term> options are unordered. Typically, such lists are rendered with bullets. For example: =item1 Reading =item2 Writing =item3 'Rithmetic might be rendered: =for para :nested(1) EReading =for para :nested(2) EWriting =for para :nested(3) E'Rithmetic =head4 Multi-paragraph list items Use the delimited form of the C<=item> block to specify items that contain multiple paragraphs. For example: 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. 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 =head3 Nesting blocks Any block can be nested by specifying an C<:nested> option on it: =for 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 However, qualifying each nested paragraph individually quickly becomes tedious if there are many in a sequence, or if multiple levels of nesting are required: =for 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 So Pod provides a C<=nested> block that marks all its contents as being nested: =for 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> Nesting blocks can contain any other kind of block, including implicit paragraph and code blocks. =head3 Tables Simple tables can be specified in Perldoc using a C<=table> block. The table may be given a label using the C<:caption> option. Columns are separated by whitespace, vertical lines (C<|>), or border intersections (C<+>). 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. Each individual table cell is separately formatted, as if it were a nested C<=para>. This means you can create tables compactly, line-by-line: =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 or line-by-line with multi-line headers: =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 or with multi-line headers I multi-line data: =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 =head3 Named blocks Blocks whose names are not recognized as Pod built-ins are assumed to be destined for specialized renderers or parser plug-ins. For example: =begin Xhtml