Author: jani
Date: 2010-07-31 11:49:53 +0200 (Sat, 31 Jul 2010)
New Revision: 31883
Modified:
docs/Perl6/Spec/S26-documentation.pod
Log:
[S26] Attempts at clarifying language
Modified: docs/Perl6/Spec/S26-documentation.pod
===================================================================
--- docs/Perl6/Spec/S26-documentation.pod 2010-07-31 08:15:21 UTC (rev
31882)
+++ docs/Perl6/Spec/S26-documentation.pod 2010-07-31 09:49:53 UTC (rev
31883)
@@ -13,7 +13,7 @@
=table
Maintainer: Damian Conway
Date: 9 Apr 2005
- Last Modified: 30 Jul 2009
+ Last Modified: 31 Jul 2010
=end VERSION
=head1
@@ -39,28 +39,31 @@
of comments in Perl 6.
Every directive starts either with an equals sign (C<=>) followed
-immediately by an identifier N<as specified in Synopsis 2>, or with a
+immediately by an identifier N<as specified in Synopsis 2>, or with
C<#=> followed immediately by whitespace or an opening bracket.
Directives that start with C<=> can be indented like the code they
interleave, but their initial C<=> must still be the first non-whitespace
character on their line. Directives that start with C<#=> can be placed
-anywhere that a Perl 6 comment can appear (though they are meaningful
-only in a subset of those places; see L<#Declarator blocks>).
+anywhere that a Perl 6 comment can appear, though they are meaningful
+only in a subset of those places; see L<#Declarator blocks>.
-If a directive is indented from the left margin, the column at which the
-first character of its opening delimiter appears is thereafter
-considered the first column of the entire block's contents. That is, an
-indented Pod block is considered to have a I<virtual left margin>,
-determined by the indentation of its opening delimiter. As with Perl 6
-heredocs, the virtual margin treats leading tabs as aligning to tabstops
-spaced every C<($?TABSTOP // 8)> characters.
+An indented Pod block is considered to have a I<virtual left margin>,
+determined by the indentation of its opening delimiter.
+In other words, if a directive is indented from the left margin, the
+column at which the first character of its opening delimiter appears is
+thereafter considered the first column of the entire block's contents.
+
+As with Perl 6 heredocs, the virtual margin treats leading tabs as
+aligning to tabstops spaced every C<($?TABSTOP // 8)> characters.
+
=head2
Pod blocks
The content of a document is specified within one or more D<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
style>|#Declarator blocks>. The first three forms are all equivalent; the
@@ -70,8 +73,8 @@
within a Pod block is treated as "ambient" material. Typically this
would be the source code of the program that the Pod is documenting. Pod
parsers still parse this text into the internal representation of the
-file (representing it as a C<Pod6::Block::Ambient> block), but renderers
-will I<usually> ignore such blocks (but see L<#Aliases>).
+file, representing it as a C<Pod6::Block::Ambient> block. Renderers
+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>
