clarification of multi-bracket format
authorRicardo Signes <rjbs@cpan.org>
Sat, 17 Apr 2010 18:34:28 +0000 (14:34 -0400)
committerRicardo Signes <rjbs@cpan.org>
Mon, 19 Apr 2010 16:26:33 +0000 (12:26 -0400)
pod/perlpod.pod
pod/perlpodspec.pod

index 826dea5..415d13c 100644 (file)
@@ -558,8 +558,8 @@ This will produce: "C<$a E<lt>=E<gt> $b>"
 
 A more readable, and perhaps more "plain" way is to use an alternate
 set of delimiters that doesn't require a single ">" to be escaped.  With
-the Pod formatters that are standard starting with perl5.5.660, doubled
-angle brackets ("<<" and ">>") may be used I<if and only if there is
+the Pod formatters that are standard starting with perl5.5.660 (circa 2000),
+doubled angle brackets ("<<" and ">>") may be used I<if and only if there is
 whitespace right after the opening delimiter and whitespace right
 before the closing delimiter!>  For example, the following will
 do the trick:
@@ -582,6 +582,12 @@ And they all mean exactly the same as this:
 
     C<$a E<lt>=E<gt> $b>
 
+The multiple-bracket form does not affect the interpretation of the contents of
+the formatting code, only how it must end.  That means that the examples above
+are also exactly the same as this:
+
+    C<< $a E<lt>=E<gt> $b >>
+
 As a further example, this means that if you wanted to put these bits of
 code in C<C> (code) style:
 
index b7c3122..0bf84e0 100644 (file)
@@ -429,6 +429,18 @@ themselves.  That is, these are all synonymous:
 
 and so on.
 
+Finally, the multiple-angle-bracket form does I<not> alter the interpretation
+of nested formatting codes, meaning that the following four example lines are
+identical in meaning:
+
+  B<example: C<$a E<lt>=E<gt> $b>>
+
+  B<example: C<< $a <=> $b >>>
+
+  B<example: C<< $a E<lt>=E<gt> $b >>>
+
+  B<<< example: C<< $a E<lt>=E<gt> $b >> >>>
+
 =back
 
 In parsing Pod, a notably tricky part is the correct parsing of