Author: masak Date: 2010-02-17 17:41:32 +0100 (Wed, 17 Feb 2010) New Revision: 29767
Modified: docs/Perl6/Spec/S26-documentation.pod Log: [S26] Added Damian's even more latest changes A nifty command called 'patch' almost managed to apply the updates.diff file Damian sent to p6l. One hunk failed, but I poked it in manually. Also removed one line-ending whitespace. Modified: docs/Perl6/Spec/S26-documentation.pod =================================================================== --- docs/Perl6/Spec/S26-documentation.pod 2010-02-17 13:37:39 UTC (rev 29766) +++ docs/Perl6/Spec/S26-documentation.pod 2010-02-17 16:41:32 UTC (rev 29767) @@ -6,7 +6,7 @@ =TITLE Synopsis 26 - Documentation -=AUTHOR +=for AUTHOR Damian Conway <L<C<dam...@conway.org>|mailto:dam...@conway.org>> =begin VERSION @@ -16,7 +16,8 @@ Last Modified: 16 Aug 2009 =end VERSION -=head1 Pod +=head1 +Pod D<Pod> is an easy-to-use markup language with a simple, consistent underlying document object model. Pod can be used for writing language @@ -32,14 +33,14 @@ =head2 General syntactic structure -Pod documents are specified using D<directives>, 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. +Pod documents are specified using D<directives|directive>, 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, or with a C<#=> followed immediately by -whitespace or an opening bracket. +immediately by an identifier N<as specified in Synopsis 2>, or with a +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 @@ -55,9 +56,10 @@ heredocs, the virtual margin treats leading tabs as aligning to tabstops spaced every C<($?TABSTOP // 8)> characters. -=head2 Pod blocks +=head2 +Pod blocks -The content of a document is specified within one or more D<blocks>. +The content of a document is specified within one or more D<blocks|block>. Every Pod block may be declared in any of four forms: L<I<delimited style>|#Delimited blocks>, L<I<paragraph style>|#Paragraph blocks>, L<I<abbreviated style>|#Abbreviated blocks>, or L<I<declarator @@ -69,7 +71,7 @@ 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<Pod6::Block::Ambient> block), but renderers -will I<usually> ignore such blocks (see L<#Aliases>). +will I<usually> 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> @@ -92,16 +94,13 @@ 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 identifierN< - A valid identifier is a sequence of alphanumerics and/or - underscores, beginning with an alphabetic or underscore ->, which is the D<typename> of the block. Typenames that are entirely -lowercase (for example: C<=begin head1>) or entirely uppercase -(for example: C<=begin SYNOPSIS>) are reserved. +which are followed by a valid Perl 6 identifier, which is the +D<typename> 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 @@ -117,9 +116,10 @@ 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. -See Synopsis 2 for details of the various Perl 6 pair notations. +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 @@ -147,8 +147,11 @@ =begin code =begin table :caption<Table of Contents> Constants 1 + Variables 10 + Subroutines 33 + Everything else 57 =end table @@ -250,8 +253,8 @@ Declarator blocks are introduced by a special Perl comment: 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 an opening bracket, the block is terminated by the matching -closing bracket. +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: @@ -318,10 +321,15 @@ ) { ... } sub fu2 (Any $bar) - #=[ This text stored in C<&fu2.WHY>, I<not> in C<$bar.WHY>, + #=[ This text stored in C<&fu2.WHY>, not in C<$bar.WHY>, (because C<sub fu2> is the declarator at the I<start> 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) + ] =end code If a declarator block is I<not> immediately preceded by an attached line @@ -363,11 +371,12 @@ =end code -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 Pod object has a C<.WHEREFORE> method that returns the -object or metaobject created by the declarator to which they are -attached. +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<Pod6::Block::Declarator>, and has a C<.WHEREFORE> method that returns +the code object or metaobject created by the declarator to which the +documentation is attached. When the L<default C<DOC INIT> block|#How Pod is parsed and processed> renders these Pod objects, it automatically includes information about @@ -452,7 +461,8 @@ Pod predefines a small number of standard configuration options that can be applied uniformly to any built-in block type. These include: -=begin item :term<C<:nested>> +=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 @@ -491,7 +501,7 @@ specify a block of code that should appear I<without> its usual nesting: -=begin code :allow<B> +=begin code :allow<B V> =comment Don't nest this code block in the usual way... B<=begin code :nested(0)> @@ -501,33 +511,34 @@ line instruction comments number code - =end code + V<=end code> =end code Note that C<:!nested> could also be used for this purpose: =begin code - =begin code :!nested + =Z<>begin code :!nested =end code -=end item +=end defn -=begin item :term<C<:numbered>> +=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<numbered headings|#Numbered headings> and L<ordered lists|#Ordered lists>, 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. +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. -=end item +Note that numbering is never explicit; it is always implied by context. -=for item :term<C<:term>> -This option specifies that a list item is the definition of a term. -See L<#Definition lists>. +=end defn -=begin item :term<C<:formatted>> +=begin defn +C<:formatted> This option specifies that the contents of the block should be treated as if they had one or more L<formatting codes|#Formatting codes> placed around them. @@ -565,20 +576,25 @@ inside a formatting code, that formatting code will still apply, in addition to the extra "basis" and "important" formatting specified by C<:formatted<B I>>. -=end item +=end defn -=begin item :term<C<:like>> +=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<configurations|#Block pre-configuration>. For example: +related L<configurations|#Block pre-configuration> or for making +user-defined synonyms for existing types. For example: =begin code =config head2 :like<head1> :formatted<I> + + =config Subhead :like<head2> =end code -=end item +=end defn -=for item :term<C<:allow>> +=defn C<:allow> This option expects a list of formatting codes that are to be recognized within any C<V<>> codes that appear in (or are implicitly applied to) the current block. The option is most often used on C<=code> blocks to @@ -586,7 +602,9 @@ used in I<any> block that contains verbatim text. See L<#Formatting within code blocks>. -=begin item :term<C<:margin>> +=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: @@ -621,7 +639,7 @@ =begin code sub foo { - =begin pod :margin<|> + V<=begin> pod :margin<|> |=head1 Hey Look: Indented Pod! | |You can indent Pod in Perl 6 @@ -647,8 +665,9 @@ margin is then used until the next line with an explicit margin marker is encountered, or the block terminates. +=end defn -=head2 Blocks +=head2 Block types Pod offers notations for specifying a wide range of standard block types... @@ -778,9 +797,9 @@ 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: +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 @@ -794,10 +813,14 @@ 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 + =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<=nested>, C<=END>, or +Within a C<=pod>, C<=item>, C<=defn>, C<=nested>, C<=END>, or L<semantic|#Semantic blocks> block, ordinary paragraphs do not require an explicit marker or delimiters, but there is also an explicit C<para> marker (which may be used anywhere): @@ -823,7 +846,7 @@ =end code As the previous example implies, when any form of explicit C<para> block -is used, any whitespace at the start of each line is removed. +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. @@ -838,7 +861,7 @@ 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 after the block's virtual +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: @@ -849,7 +872,7 @@ $which.is_specified(:by<indenting>); =end code -Implicit code blocks may only be used within C<=pod>, C<=item>, +Implicit code blocks may only be used within C<=pod>, C<=item>, C<=defn>, C<=nested>, C<=END>, or L<semantic|#Semantic blocks> blocks. There is also an explicit C<=code> block (which can be specified within @@ -871,7 +894,7 @@ 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 the margin then have 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. @@ -1134,7 +1157,7 @@ =end code To specify an I<unnumbered> list item that starts with a literal C<#>, either -make it verbatim: +make the octothorpe verbatim: =begin code :allow<B> =item B<V<#>> introduces a comment @@ -1213,38 +1236,10 @@ =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<B> - =for item B<:term<MAD>> - Affected with a high degree of intellectual independence. - - =for item B<:term<MEEKNESS>> - Uncommon patience in planning a revenge that is worth while. - - =for item B<:term<MORAL>> - 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<B> - =for item B<:numbered> :term<SELFISH> - Devoid of consideration for the selfishness of others. - - =for item B<:numbered> :term<SUCCESS> - 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: +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 @@ -1316,6 +1311,43 @@ =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�<DL>...</DL>� tags, rather than C�<UL>...</UL>� 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<B> + =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: @@ -1356,8 +1388,8 @@ 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 not role in determining their ultimate nesting. -The above is exactly equivalent to: +of the blocks plays no role in determining their ultimate nesting. +The preceding example could equally have been specified: =begin code :allow<B> B<=begin nested> @@ -1376,13 +1408,17 @@ The table may be given an associated description or title 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<every> row. Either style -can also have an explicitly separated header row at the top. +Columns are separated by two or more consecutive whitespace characters, +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. +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<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 C<=para>. @@ -1433,8 +1469,9 @@ =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: +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 @@ -1461,24 +1498,25 @@ The resulting object's C<.typename> method retrieves the short name of the block type: C<'Xhtml'>, C<'Image'>, etc. The object's C<.config> -method retreives the list of configuration options (if any). The +method retrieves the list of configuration options (if any). The object's C<.contents> 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 L<#Semantic blocks>. +Note that all block names consisting entirely of lowercase or entirely of +uppercase letters are reserved. See L<#Semantic blocks>. =head3 Pod comments -All Pod blocks are intrinsically Perl 6 comments, but D<Pod comments> -are comments that Pod renderers ignore too. That is, Pod blocks are -never to be rendered by any renderer. They are, of course, still -included in any internal Pod representation, and are accessible via the -Pod API...and via the C<$=POD> variable within a Perl 6 program. +All Pod blocks are intrinsically Perl 6 comments, but +D<Pod comments|Pod comment> are comments that Pod renderers ignore too. +That is, they are Pod blocks that are never to be rendered by any +renderer. They are, of course, still included in any internal Pod +representation, and are accessible via the Pod API...and via the +C<$=POD> variable within a Perl 6 program. Comments are useful for meta-documentation (documenting the documentation): @@ -1513,7 +1551,6 @@ =end code - =head3 The C<=END> block The C<=END> block is special in that all three of its forms @@ -1548,13 +1585,15 @@ just have a C<&postcircumfix:<{ }>> that inorder walks the Pod tree and retrieves every nested Pod object of the requested type?) +C<=DATA> blocks are never rendered by the standard Pod renderers. + =head3 Semantic blocks -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. +All uppercase block typenames except C<=END> and C<=DATA> 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: @@ -1573,7 +1612,7 @@ =WARNING =DEPENDENCY =BUG - =SEEALSO + =SEE-ALSO =ACKNOWLEDGEMENT =AUTHOR =COPYRIGHT @@ -1651,7 +1690,8 @@ =head2 Formatting codes 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 +within the contents of (most types of) Pod block (including all +L<declarator blocks|#Declarator blocks>). 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: @@ -1735,7 +1775,8 @@ The C<D<>> formatting code indicates that the contained text is a B<definition>, introducing a term that the adjacent text -elucidates. For example: +elucidates. It is the inline equivalent of a C<=defn> block. +For example: =begin code :allow<B> There ensued a terrible moment of B<D<coyotus interruptus>>: a brief @@ -1747,7 +1788,7 @@ and separated by semicolons: =begin code :allow<B> - A B<D<Formatting code|formatting codes;formatters>> provides a way + A B<D<formatting code|formatting codes;formatters>> provides a way to add inline mark-up to a piece of text. =end code @@ -1882,7 +1923,7 @@ using a verbatim formatting code: =begin code :allow<B> - In Perl 5 POD, the B�V<�Z<>B�>� code was widely used to break up text + In Perl 5 POD, the B�V<V<Z<>>>� code was widely used to break up text that would otherwise be considered mark-up. =end code @@ -1890,14 +1931,31 @@ verbatim, which often eliminates the need for the C<V<>> as well: =begin code :allow<B> - In Perl 5 POD, the B�C<�Z<>B�>� code was widely used to break up text + In Perl 5 POD, the B�V<C<Z<>>>� code was widely used to break up text that would otherwise be considered mark-up. =end code The C<Z<>> formatting code is the inline equivalent of a L<C<=comment> block|#Comments>. +=head4 Comments as category markers +Most Pod renderers will provide a mechanism that allows particular Pod +blocks to be explicitly excluded or included if they match a particular +pattern. For example, a renderer might be instructed to omit any block +that contains the pattern C</CONFIDENTIAL/>. Corresponding "invisibility +markers" can then be placed inside C<Z<>> comments within any block that +should not normally be displayed. For example: + +=for code :allow<B> + class Widget is Bauble + { + has $.things; #= a collection of other stuff + #={ Z<CONFIDENTIAL> + This variable needs to be replaced for political reasons + } + } + =head3 Links The C<L<>> code is used to specify all kinds of links, filenames, citations, @@ -1917,7 +1975,9 @@ Standard schemes include: -=begin item :term('C<http:> and C<https:>') +=begin defn +C<http:> and C<https:> + A standard web URL. For example: =begin code :allow<B> @@ -1933,9 +1993,10 @@ L<B<http:../examples/index.html>> =end code -=end item +=end defn -=begin item :term<C<file:>> +=begin defn +C<file:> A filename on the local system. For example: @@ -1944,17 +2005,18 @@ L<B<file:/usr/local/lib/.configrc>> or L<B<file:~/.configrc>>). =end code -Filenames that don't begin with a C</> or a C<~> are relative to the current -document's location: +Filenames that don't begin with a C</> or a C<~> are relative +to the current document's location: =begin code :allow<B> Then, edit the local config file (that is, either L<B<file:.configrc>> or L<B<file:CONFIG/.configrc>>. =end code -=end item +=end defn -=begin item :term<C<mailto:>> +=begin defn +C<mailto:> An email address. Typically, activating this type of link invokes a mailer. For example: @@ -1963,9 +2025,10 @@ Please forward bug reports to L<B<mailto:devn...@rt.cpan.org>> =end code -=end item +=end defn -=begin item :term<C<man:>> +=begin defn +C<man:> A link to the system manpages. For example: @@ -1974,12 +2037,13 @@ Unix L<B<man:find(1)>> facilities. =end code -=end item +=end defn -=begin item :term<C<doc:>> +=begin defn +C<doc:> A link to some other documentation, typically a module or part of the -core documentation; things that would normally be read with C<perl -doc>. +core documentation; things that would normally be read with C<perl --doc>. For example: =begin code :allow<B> @@ -1987,30 +2051,35 @@ view the results. See also: L<B<doc:perldata>>. =end code -=end item +=end defn -=begin item :term<C<defn:>> +=begin defn +C<defn:> -A link to the L<definition|#Definitions> of the specified term within -the current document. For example: +A link to the L<block-form|#Definition lists> or L<inline|#Definitions> +definition of the specified term within the current document. For example: =begin code :allow<B> He was highly prone to B<D<lexiphania>>: an unfortunate proclivity for employing grandiloquisms (for example, words such as "proclivity", "grandiloquism", and indeed "lexiphania"). + + B<=defn glossoligation> + Restraint of the tongue (voluntary or otherwise) =end code and later, to link back to the definition =begin code :allow<B> - To treat his chronic L<B<defn:lexiphania>> the doctor prescribed an - immediate glossoligation or, if that proved ineffective, a complete - cephalectomy. +To treat his chronic L<B<defn:lexiphania>> the doctor prescribed an +immediate L<B<defn:glossoligation>> or, if that proved ineffective, +a complete cephalectomy. =end code -=end item +=end defn -=begin item :term<C<isbn:> and C<issn:>> +=begin defn +C<isbn:> and C<issn:> The International Standard Book Number or International Standard Serial Number for a publication. For example: @@ -2020,7 +2089,7 @@ serial publication (L<B<issn:1087-903X>>) =end code -=end item +=end defn To refer to a specific section within a webpage, manpage, or Pod document, add the name of that section after the main link, separated by @@ -2055,6 +2124,8 @@ You could also write the code L<B<in Latin |> doc:Lingua::Romana::Perligata> + + His L<B<lexiphanic|>defn:lexiphania>> tendencies were, alas, incurable. =end code @@ -2062,11 +2133,11 @@ A second kind of linkE<mdash>the C<P<>> or B<placement link>E<mdash>works in the opposite direction. Instead of directing focus out to another -document, it allows you to suck the contents of another document +document, it allows you to assimilate the contents of another document into your own. In other words, the C<P<>> formatting code takes a URI and (where possible) -places the contents of the corresponding document inline in place of the +inserts the contents of the corresponding document inline in place of the code itself. C<P<>> codes are handy for breaking out standard elements of @@ -2140,11 +2211,13 @@ blocks> are treated as equivalent to C<head1> headings, and the C<=item1>/C<=item> equivalence is preserved. +A document may have as many C<P<toc:...>> placements as necessary. + =head3 Alias placements A variation on placement codes is the C<A<>> code, which is replaced -by the contents of the named alias specified within its delimiters. +by the contents of the named alias or object specified within its delimiters. For example: =begin code @@ -2156,14 +2229,33 @@ laid out by A<VENDOR>, as specified at A<TERMS_URL>. =end code -All Perl 6 compile-time variables are automatically alias names as well. -So, for example, a document can refer to its own filename (as C<A<$?FILE>>), -to the subroutine inside which the specific Pod is nested (as C<A<$?ROUTINE>>), -or to the current class (as C<A<$?CLASS>>). +Any compile-time Perl 6 object that starts with a sigil is automatically +available within an alias placement as well. Unless the object is already +a string type, it is converted to a string during document-generation by +implicitly calling C<.perl> on it. -See L<#Aliases> for details of the aliasing macro mechanism. +So, for example, a document can refer to its own filename (as +C<A<$?FILE>>), or to the subroutine inside which the specific Pod is nested +(as C<A<$?ROUTINE>>), or to the current class (as C<A<$?CLASS>>). +Similarly, the value of any program constants defined with sigils can be +easily reproduced in documentation: + # Actual code... + constant $GROWTH_RATE of Num where 0..* = 1.6; + =pod + =head4 Standard Growth Rate + + The standard growth rate is assumed to be A<$GROWTH_RATE>. + +Non-mutating method calls on these objects are also allowed, so a +document can reproduce the surrounding subroutine's signature +(C<A<$?ROUTINE.signature>>) or the type of a constant +(C<A<$GROWTH_RATE.WHAT>>). + +See L<#Aliases> for further details of the aliasing macro mechanism. + + =head3 Space-preserving text Any text enclosed in an C<S<>> code is formatted normally, except that @@ -2188,11 +2280,11 @@ =head3 Entities -To include named Unicode or XHTML entities, use the C<E<>> code. +To include Unicode code points or HTML5 character references in a +Pod document, specify the required D<entity|entities> using the C<E<>> code. -If the contents of the C<E<>> are a number, that number is -treated as the decimal Unicode value for the desired codepoint. -For example: +If the C<E<>> contains a number, that number is treated as the decimal +Unicode value for the desired code point. For example: Perl 6 makes considerable use of E<171> and E<187>. @@ -2204,9 +2296,9 @@ Perl 6 makes considerable use of E<0d171> and E<0d187>. Perl 6 makes considerable use of E<0xAB> and E<0xBB>. -If the contents are not a number, they are interpreted as a Unicode -character name (which is always upper-case), or else as an XHTML entity. -For example: +If the C<E<>> contains anything that is not a number, the contents are +interpreted as a Unicode character name (which is always uppercase), or +else as an HTML5 named character reference. For example: Perl 6 makes considerable use of E<LEFT DOUBLE ANGLE BRACKET> and E<RIGHT DOUBLE ANGLE BRACKET>. @@ -2215,10 +2307,10 @@ Perl 6 makes considerable use of E<laquo> and E<raquo>. -Multiple consecutive entities can be specified in a single C<E<>> code, -separated by semicolons: +Multiple consecutive entities (in any format) can be specified in a +single C<E<>> code, separated by semicolons: - Perl 6 makes considerable use of E<laquo;hellip;raquo>. + Perl 6 makes considerable use of E<LEFT DOUBLE ANGLE BRACKET;hellip;0xBB>. =head3 Indexing terms @@ -2303,10 +2395,10 @@ =end nested -=head3 User-defined formatting codes +=head3 Module-defined formatting codes Modules loaded with a L<C<DOC use>|#How Pod is parsed and processed> -can define classes to implement their own formatting codes, which can +can define classes that implement new formatting codes, which can then be specified using the C<M<>> code. An C<M<>> code must start with a colon-terminated scheme specifier. The rest of the enclosed text is treated as the (verbatim) contents of the formatting code. For example: @@ -2387,7 +2479,7 @@ 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 +heading, you could preconfigure all the heading blocks with appropriate formatting schemes: =begin code @@ -2437,7 +2529,7 @@ =begin code :allow<B> =comment Mark this =head3 (but only this one) as being important - (in addition to the normal formatting)... + (in addition to the normal formatting)... =head3 B<:like<head3>> :formatted<I> =end code @@ -2466,16 +2558,15 @@ The C<=alias> directive provides a way to define lexically scoped synonyms for longer Pod sequences, (meta)object declarators from the -code, or even entire blocks of ambient source. These synonyms can then +code, or even entire chunks of ambient source. These synonyms can then be inserted into subsequent Pod using the L<C<A<> formatting code>|Alias placements>. Note that C<=alias> is a fundamental Pod directive, like C<=begin> or C<=for>; there are no equivalent paragraph or delimited forms. -There are three forms of C<=alias> directive: macro aliases, code block -aliases, and declarator aliases. All three forms are lexically scoped to the -surrounding Pod block. +There are two forms of C<=alias> directive: macro aliases and contextual +aliases. Both forms are lexically scoped to the surrounding Pod block. =head3 Macro aliases @@ -2484,18 +2575,19 @@ certainly not mandatory). The second argument consists of one or more lines of replacement text. -This creates a macro that can be invoked by placing the identifier in an -C<A<>> formatting code, which is then replaced by the text specified by -the innermost lexically visible C<=alias> of that name. +This creates a lexically scoped Perl 6 macro that can be invoked during +document generation by placing the identifier (i.e. the first argument +of the alias) in an C<A<>> formatting code. This formatting code is then +replaced by the text returned by new macro. -The replacement code begins at the first non-whitespace character after -the alias's identifier, and continues to the end of the line. You can -extend the replacement text over multiple lines by starting the -following line(s) with an C<=> (at the same level of indentation as the -C<=alias> directive itself) followed by at least one whitespace. Each -addition line of replacement text uses the original line's (virtual) -left margin, as specified by the indentation of the replacement text on -the C<=alias> line. +The replacement text returned by the alias macro begins at the first +non-whitespace character after the alias's identifier, and continues to +the end of the line. You can extend the replacement text over multiple +lines by starting the following line(s) with an C<=> (at the same level +of indentation as the C<=alias> directive itself) followed by at least +one whitespace. Each addition line of replacement text uses the original +line's (virtual) left margin, as specified by the indentation of the +replacement text on the C<=alias> line. For example: @@ -2515,7 +2607,7 @@ would produce: -=begin output +=begin para :nested The use of Earl Irradiatem Evermore is subject to the terms and conditions laid out by 4D Kingdoms Inc, as specified at: @@ -2523,34 +2615,41 @@ =item L<http://www.4dk.co.uk/eie.io/> =item L<http://www.fordecay.ch/canttouchthis> -=end output +=end para The advantage of using aliases is, obviously, that the same alias can be reused in multiple places in the documentation. Then, if the replacement text ever has to be changed, it need only be modified in a single place: +=begin code =alias PROGNAME Count Krunchem Constantly =alias VENDOR Last Chance Receivers Intl =alias TERMS_URLS L<http://www.c11.com/generic_conditions> +=end code -=head3 Code block aliases +=head3 Contextual aliases If the C<=alias> directive is specified with only a single argument -(that is, only with it's identifier), a D<code alias> is created. In +(that is, with only its identifier), a D<contextual alias> is created. In this form, the C<=alias> directive must be followed immediately (on the -next non-blank line) by a curly-delimited block of ambient code. +next non-blank line) by ambient code. -The single argument is then used as the synonym being created, and the -contents of the block, I<excluding> the outermost curly braces, are used -as the replacement text. +The single argument is then used as the name of the alias being created, +and some portion of the following code is used as the value returned by the +alias macro. Note that the code block following the C<=alias> line is still treated -as real code by the Perl 6 parser, but its contents are I<also> treated -as the replacement text of the alias. +as real code by the Perl 6 parser, but its contents are I<also> used to +create the replacement macro of the alias. This allows the developer to +reproduce chunks of actual source code directly in the documentation, +without having to copy it. -This allows the developer to reproduce chunks of ambient source code -directly in the documentation, without having to copy it. For example: +If the code following the one-argument C<=alias> directive begins with a +sequence of one or more repetitions of any opening bracket character, +the replacement macro returns a string containing everything from the +end of that opening sequence to just before the corresponding closing +bracket sequence. For example: =begin code @@ -2561,8 +2660,7 @@ { my $hash = 0; for $key.split("") -> $char { - $hash *= 33; - $hash += $char.ord; + $hash = $hash*33 + $char.ord; } return $hash; } @@ -2591,32 +2689,28 @@ =end nested +Alternatively, if the C<=alias> directive is I<not> followed by an +opening bracket, it must be followed by a declarator (such as C<my>, +C<class>, C<sub>, etc.) The declared object then becomes the (read-only) +return value of the alias. For example: -=head3 Declarator aliases - -If the C<=alias> directive is specified with I<no> arguments, it creates -a D<declarator alias>. Declarator aliases are a variation on -L<code aliases|#Code aliases>, in which the alias automatically creates a -synonym to the name of the declared object (or type) that starts on the -very next line. - -The name of the synonym created is the actual declarator keyword -(C<my>, C<sub>, C<has>, C<class>, etc.) and the replacement text is -the name of the declared object or type. For example: - =begin code :allow<B> - B<=alias> + B<=alias CLASSNAME> class Database::Handle { - B<=alias> + B<=alias ATTR> has IO $!handle; - B<=alias> - my Bool method open ($filename) {...} + B<=alias OPEN> + my Bool method open ($filename?) {...} + B<=alias DEFNAME> + constant Str DEFAULT_FILENAME = 'db.log'; + =for para - Note that the B<A<method>> method of class B<A<class>> + Note that the B<A<OPEN.name>> method of class B<A<CLASSNAME>> stores the resulting low-level database handle - in its private B<A<has>> attribute. + in its private B<A<ATTR.name>> attribute. By default, + handles are opened to the file "B<A<DEFNAME>>". } =end code @@ -2624,42 +2718,42 @@ This would produce: =nested - Note that the C<open> method of class C<Database::Handle> stores the - resulting low-level database handle in its private C<$!handle> - attribute. +Note that the C<open> method of class C<Database::Handle> stores the +resulting low-level database handle in its private C<$!handle> +attribute. By default, handles are opened to the file "C<db.log>". =head1 How Pod is parsed and processed -Pod is just a set of specialized forms of Perl 6 comment. Every Perl 6 -implementation must provide a special command-line flag that -locates, parses, and processes Pod to produce documentation. -That flag is K<-doc>. +Pod is just a collection of specialized forms of Perl 6 comment. Every +Perl 6 implementation must provide a special command-line flag that +locates, parses, and processes Pod to produce documentation. That flag +is K<--doc>. Hence, to read Pod documentation you would type things like: - perl -doc perlrun + perl --doc perlrun - perl -doc DBI::DBD::Metadata + perl --doc DBI::DBD::Metadata - perl -doc ./lib/My/Module.pm + perl --doc ./lib/My/Module.pm When the Perl 6 interpreter is run in this mode, it sets the compiler -hint C<$?DOC> to true. If the K<-doc> flag is given a value, that value +hint C<$?DOC> to true. If the K<--doc> flag is given a value, that value (with a C<but true> added) is placed in C<$?DOC>. This can be used to specify, for example, the output format desired: - perl -doc=html perldelta > perldelta.html + perl --doc=html perldelta > perldelta.html -Under K<-doc>, the interpreter runs in a special mode, parsing the +Under K<--doc>, the interpreter runs in a special mode, parsing the source code (including the Pod, as it always does) during compilation and building the program's syntax tree. However, during parsing and -initialization under K<-doc>, the interpreter only executes those +initialization under K<--doc>, the interpreter executes any C<BEGIN>, C<CHECK>, and C<INIT> blocks (and equivalents, such as C<use> statements and subroutine declarations) that are preceded by the special prefix: C<DOC> -When the K<-doc> is I<not> specified on the commandline, blocks and +When the K<--doc> is I<not> specified on the commandline, blocks and statements that are preceded by the C<DOC> prefix are not executed at all. By default, once the C<DOC INIT> phase is complete, the interpreter then @@ -2708,17 +2802,17 @@ } The idea is that developers will be able to add their own documentation -mechanisms simply by loading modules that install suitable DOC blocks, -to augment or override the default documentation behaviour. Such -mechanisms can then be built using code written in standard Perl 6 that -accesses C<$=POD>, as well as using the C<.WHY> and C<.WHEREFORE> -introspection methods of any constructs that have attached Pod blocks. +mechanisms simply by loading a module (via a C<DOC use>) to augment or +override the default documentation behaviour. Such mechanisms can then +be built using code written in standard Perl 6 that accesses C<$=POD>, +as well as using the C<.WHY> and C<.WHEREFORE> introspection methods of +any constructs that have attached Pod blocks. Note also that this mechanism means that, on many systems, you can create a self-converting documentation file like so: =begin code - #! /usr/bin/perl6 -doc + #! /usr/bin/perl6 --doc =begin pod @@ -2728,7 +2822,10 @@ convert it to a readable text representation. =head2 Et cetera + ... + =end pod + =end code @@ -2746,7 +2843,7 @@ C<=for> Start of an implicitly (blank-line) terminated block C<=alias> Define a Pod macro -=end table :nested +=end table =head2 Blocks @@ -2756,6 +2853,7 @@ ______________ ___________________________________________________ C<=code> Verbatim pre-formatted sample source code C<=comment> Content to be ignored by all renderers + C<=defn> Definition of a term C<=head>R<N> I<N>th-level heading C<=input> Pre-formatted sample input C<=item> First-level list item @@ -2763,6 +2861,7 @@ C<=nested> Nest block contents within the current context C<=output> Pre-formatted sample output C<=para> Ordinary paragraph + C<=pod> No "ambient" blocks inside C<=table> Simple rectangular table C<=DATA> Perl 6 data section C<=END> No ambient blocks after this point @@ -2777,7 +2876,7 @@ Formatting code Specifies _______________ ___________________________________________________ - C<A<...>> Replaced by contents of specified macro + C<A<...>> Replaced by contents of specified macro/object 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>;...>>)
