Changeset 14843 for docs/Perl6/Spec

Timestamp:

11/25/06 01:43:22 (2 years ago)

Author:

audreyt

Message:

* S26: Documentation spec, 2006-11-22 edition, from Damian.

Files:

• docs/Perl6/Spec/Documentation.pod (modified) (58 diffs)

docs/Perl6/Spec/Documentation.pod

@@ +1 @@
+=begin pod
+
 =for comment
     This file is deliberately specified in Perl 6 Pod format
@@ -6 +8 @@
 =head1 TITLE
 
-[DRAFT] Synopsis 26 - Documentation
-
-
-=head1 AUTHORS
-
-Damian Conway <damian@conway.org>
-
-Ingy dE<ouml>t Net <ingy@cpan.org>
+Synopsis 26 - Documentation
+
+
+=head1 AUTHOR
+
+Damian Conway <L<C<damian@conway.org>|mailto:damian@conway.org>>
 
 
 =head1 VERSION
 
-=for table
-    Maintainer:     Damian Conway <damian@conway.org>
+=table
+    Maintainer:     Damian Conway
     Date:           9 Apr 2005
-    Last Modified:  7 Oct 2006
+    Last Modified:  22 Nov 2006
 
 
@@ -27 +27 @@
 
 Perldoc is an easy-to-use markup language with a simple, consistent
-underlying document object model. Perldoc can be used for writing the
-documentation for Perl 5 and Perl 6, and for Perl programs and modules,
-as well as for other types of document composition.
+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<dialects>, all of which map onto
 the same set of standard document objects. The standard dialect is named
-L<"Pod"|#The Pod Dialect>.
+"Pod".
 
 
 =head1 The Pod Dialect
 
-I<Pod> is an evolution of Perl 5's Plain Ol' Documentation (POD) markup.
-Compared to Perl 5 POD, Perldoc's Pod dialect is much more uniform,
-somewhat more compact, and considerably more expressive.
+B<Pod> is an evolution of Perl 5's L<I<Plain Ol' Documentation>|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 blocks are specified using I<directives>, which always start with an
-C<=> in the first column. Every Pod block directive may be written in
-any of three equivalent forms: I<delimited style>, I<paragraph style>,
-or I<abbreviated style>.
+Pod documents are specified using D<directives>, 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<blocks>. Every
+Pod block may be declared in any of three equivalent forms:
+L<I<delimited style>|#Delimited blocks>, L<I<paragraph style>|#Paragraph
+blocks>, or L<I<abbreviated style>|#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<Perldoc::Block::Ambient> 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<pod> block:
+
+=begin code :allow<B>
+    B<=begin pod>
+
+    =head1 A heading
+
+    This is Pod too. Specifically, this is a simple C<para> 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.
 
 
@@ -55 +92 @@
 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 typename of the block. Typenames
+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.
@@ -62 +99 @@
 configuration information for the block. This information is used in
 different ways by different types of blocks, and is specified using
-Perl6ish C<:key{value}> or C<< key=>value >> pairs (which must, of
+Perl6ish C<:key<value>> or C<< key=>value >> pairs (which must, of
 course, be constants since Perldoc is a specification language, not a
 programming language).
-See L<Synposis 2|http://dev.perl.org/perl6/doc/design/syn/S02.html#Literals>
+See L<Synopsis 2|http://dev.perl.org/perl6/doc/design/syn/S02.html#Literals>
 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
-horizontal whitespace character.
+whitespace character.
 
 The lines following the opening delimiter and configuration are the data
@@ -85 +122 @@
 For example:
 
-     =begin table  :title<Table of Contents>
+     =begin table  :caption<Table of Contents>
          Constants           1
          Variables           10
          Subroutines         33
          Everything else     57
-     =end Table
+     =end table
 
      =begin Name  :required
@@ -101 +138 @@
      =end Contact
 
-Note that no blank lines are required around the directives, and blank
+Note that no blank lines are required around the directives; blank
 lines within the contents are always treated as part of the contents.
-
-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 C</^\s*?$/>. Pod uses blank lines, rather than empty lines, as
-delimiters (on the principle of least surprise).
+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</^^ \h* $$/>. Pod uses
+blank lines, rather than empty lines, as delimiters on the principle of
+least surprise.
 
 
@@ -115 +154 @@
 the next Pod directive or the first blank line (which is I<not>
 considered to be part of the block's contents). The C<=for> marker is
-followed by the name of the directive and optional
-configuration information. The general syntax is:
+followed by the name of the block and optional configuration
+information. The general syntax is:
 
 =begin code :allow< R >
@@ -122 +161 @@
      =                R<OPTIONAL EXTRA CONFIG INFO>
      R<BLOCK DATA>
-
 =end code
 
 For example:
 
-     =for table  :title<Table of Contents>
+     =for table  :caption<Table of Contents>
          Constants           1
          Variables           10
@@ -137 +175 @@
      The applicant's full name
 
-     =for Contact  :optional
+     =for Contact  :optional   
      The applicant's contact details
-
-Once again, blank lines are not required around the directive (this is a
-universal feature of Pod).
 
 
@@ -170 +205 @@
      =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 equivalent 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.
+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
+     =head1 Top Level Heading
 
 this automatically implies that you could also write that block as:
 
      =for head1
-     TOP LEVEL HEADING
+     Top Level Heading
 
 or:
 
      =begin head1
-     TOP LEVEL HEADING
+     Top Level Heading
      =end head1
 
@@ -201 +239 @@
 applied uniformly to built-in block types. These include:
 
-=begin item  :term<C<:indented>>
-
-This option specifies that the block is to be indented by a particular
-amount. If the indentation amount includes a sign (i.e. C<+> or C<->) then
-the indentation is relative to the indentation of the surrounding construct;
-unsigned indentations are absolute offsets from the first column.
-
-If a simple number is used (e.g. C<:indent(4)>) it indicates "columns" (for
-fixed-width renderers) or "ems" for variable-width renderers. You can also
-specify a unit after the number. For example:
-
-    =for para :indented<1 tab>
-
-    =for para :indented<1 em>
-
-    =for para :indented<1 col>
-
-    =for para :indented<1 lvl>
-
-    =for para :indented<4 sp>
+=begin item :term<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<C<=code>|#Code blocks>,
+L<C<=item>|#Lists>, L<C<=input>|#I/O blocks>, and L<C<=output>|#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<deep> undercover!"
+    =end para
+    =end para
+    =end para
+
+This can be simplified by giving the C<:nested> option a positive integer
+value:
+
+=for code :allow<B>
+    =begin para B<:nested(3)>
+    "We're going deep, deep, I<deep> 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<without> its usual
+nesting:
+
+=for code :allow<B>
+    =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
@@ -227 +296 @@
 
 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.
+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
@@ -234 +303 @@
 
 =end item
-
-=for item  :term<C<:bulleted>>
-This option specifies that a list item has a bullet. See L<#Unordered lists>.
 
 =for item  :term<C<:term>>
@@ -249 +315 @@
 For example, instead of:
 
-    =comment The next para is important, so emphasize it...
+    =for comment
+        The next para is both important and fundamental,
+        so doubly emphasize it...
+
     =begin para
     B<I<
     Warning: Do not immerse in water. Do not expose to bright light.
     Do not feed after midnight.
-    >>
+
     =end para
 
 you can just write:
 
-    =comment The next para is important, so emphasize it...
-    =begin para :formatted<B I>
+=for code :allow<B>
+    =begin para B<:formatted<B I>>
     Warning: Do not immerse in water. Do not expose to bright light.
     Do not feed after midnight.
     =end para
 
-Like all formatting codes, these 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 bold and italic
-formatting specified by C<:formatted<B I>>. It is also possible to
-I<remove> formatting using a C<:formatted> option, by specifying the
-formatting code(s) with a minus sign before them:
-
-    =comment The next para is less important, so de-emphasize it...
-    =begin para :formatted<-B>
-    Fire. The Untamed Element. Oldest of Man's Mysteries. Giver of
-    warmth. Destroyer of forests. Right now I<this> building is on fire.
-    Yes! The building is on fire! Leave the building! Enact the age-old
-    drama of self-preservation!
-    =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<B I>>.
 =end item
 
-=for item :term<C<:like<R<typename>>>>
+=begin item :term<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>.
+related L<configurations|#Block pre-configuration>. For example:
+
+    =config head2  :like<head1> :formatting<I>
+
+=end item
 
 =for item  :term<C<:allow>>
 This option expects a list of formatting codes that are to be recognized
-within any C<V<>> codes nested inside 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<any> block that
-contains verbatim text. See L<#Formatting within code blocks>.
-
+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
+allow mark-up within those otherwise verbatim blocks, though it can be
+used in I<any> block that contains verbatim text. See L<#Formatting
+within code blocks>.
 
 
@@ -302 +369 @@
 =head3 Headings
 
-Pod provides an unlimited number of levels of heading, specifed by the
-T<=headR<N>> directive. For example:
-
-    =head1 A TOP LEVEL HEADING
+Pod provides an unlimited number of levels of heading, specified by the
+C<=head>R<N> block marker. For example:
+
+    =head1 A Top Level Heading
 
     =head2 A Second Level Heading
@@ -314 +381 @@
 
 While Pod parsers are required to recognize and distinguish all levels
-of heading, Pod formatters are only required to provide distinct
+of heading, Pod renderers are only required to provide distinct
 I<renderings> of the first four levels of heading (though they may, of
 course, provide more than that). Headings at levels without distinct
@@ -320 +387 @@
 rendered level.
 
+
 =head4 Numbered headings
 
-You can specify that a heading is numbered using the C<:numbered> option. The
-value of this option should be a sequence of characters containing a C<#>. If
-the value is omitted (i.e. C<:numbered>), then it defaults to C<'#.'>.
-
-The C<#> is replaced by the ordinal number of the heading block (within
-its particular heading level):
+You can specify that a heading is numbered using the C<:numbered> option. For
+example:
 
     =for head1 :numbered
@@ -335 +399 @@
     The Solution
 
-    =for head2 :numbered<#:>
+    =for head2 :numbered
     Analysis
 
-    =for head3 :numbered<(#)>
+    =for head3 
     Overview
 
-    =for head3 :numbered<(#)>
+    =for head3
     Details
 
-    =for head2 :numbered<#:>
+    =for head2 :numbered
     Design
 
@@ -352 +416 @@
 which would produce:
 
-=begin indent :formatted<B>
+=begin nested :formatted<B>
 1. The Problem
 
 2. The Solution
 
-=begin indent
-2.1: Analysis
-
-=begin indent
-(2.1.1) Overview
-
-(2.1.2) Details
-=end indent
+=begin nested
+2.1. Analysis
+
+=begin nested
+Overview
+
+Details
+=end nested
 
 2.2: Design
-=end indent
+=end nested
 
 3: The Implementation
-=end indent
+=end nested
 
 It is usually better to preset a numbering scheme for each heading
 level, in a series of L<configuration blocks|#Block pre-configuration>:
 
-    =config head1 :numbered
-    =config head2 :numbered<#:>
-    =config head3 :numbered<(#)>
+=for code :allow<B>
+    B<=config head1 :numbered
+    =config head2 :numbered
+    =config head3 :!numbered>
 
     =head1 The Problem
@@ -394 +459 @@
     =head1 # The Solution
     =head2   # Analysis
-    =head3     # Overview
-    =head3     # Details
+    =head3       Overview
+    =head3       Details
     =head2   # Design
     =head1 # The Implementation
@@ -407 +472 @@
 should produce something like:
 
-=para :indented
+=nested
 B<2.3.8.6.1.9. The Rescue of the Kobayashi Maru>
 
@@ -415 +480 @@
 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 inline mark-up (see
-L<#Formatting codes>) applied.
-
-Ordinary paragraphs consist of one or more 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:
-
-     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 a heading block, not associated with the previous para
-
-Within a C<=begin pod>/C<=end pod> block, ordinary paragraphs do not
-require an explicit marker or delimiters, but there I<is> an explicit
-C<para> marker available:
+squeezed, lines filled, and any special L<inline mark-up|#Formatting codes>
+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<para> marker (which may be used anywhere):
 
      =para
@@ -450 +519 @@
      =end para
 
-As the previous example implies, when any form of explicit C<para>
-directive is used all whitespace at the start of each line is removed.
-Hence the ordinary paragraph text no longer has to begin at column 1.
+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, so
+the paragraph text no longer has to begin at column 1.
 
 
 =head3 Code blocks
 
-Code blocks are used to specify pre-formatted text, which should
-be rendered without rejustification, without whitespace-squeezing, and without
-recognizing any inline formatting codes. Typically these blocks are used
-to show examples of code, data, or I/O, and are set using a fixed-width font.
-
-A code block is 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:
-
-     This I<ordinary> paragraph introduces a following
-     B<code> block:
+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<nesting|#Nesting blocks>
+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');
-        $that.is_specified(:by<indenting>);
-
-There is also an explicit C<code> directive, which allows the contents
-of code blocks to start at the first column, to start with whitespace
-characters that are preserved exactly, and to contain blank lines:
-
+        $which.is_specified(:by<indenting>);
+=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<any> other block type, not just C<=pod>, C<=item>, etc.):
+
+=begin code :allow<B>
      The C<loud_update()> subroutine adds feedback:
 
-     =begin code
+     B<=begin code>
 
      sub loud_update ($who, $status) {
@@ -486 +562 @@
      }
 
-     =end code
-
-The only limitation on the contents of a C<code> block is that they cannot
-begin with an C<=> in the first column. If this is required, the leading C<=>
-must be made C<verbatim|#Verbatim text>:
-
-    =begin code :allow<V>
-
-    V<=> in the first column is always a Perldoc directive
-
-    =end code
-
-Renderers would normally indent the contents of any C<code> block (whether
-it was implicitly or explicitly specified), but this can be overridden using
-the C<:indented> option:
-
-    =comment
-        Indent this code block to the same column
-        as the surrounding text
-
-    =begin code :indented(+0)
+     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<formatting
+codes|#Formatting codes>, 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<B<>> code). Or
+you may want to indicate that part of the example is metasyntactic
+(using the C<R<>> code). Or you might need to insert a non-ASCII
+character (using the C<E<>> 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 {
-        say "Hello World";
+        B<say> 'Hello R<name>';
     }