From: Ricardo Signes <rjbs@cpan.org>
Date: Sat, 17 Apr 2010 18:34:28 +0000 (-0400)
Subject: clarification of multi-bracket format
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=a3d78747dc6076a86b29e59f911247652002f29b;p=p5sagit%2Fp5-mst-13.2.git

clarification of multi-bracket format
---

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 826dea5..415d13c 100644
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -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:
 
diff --git a/pod/perlpodspec.pod b/pod/perlpodspec.pod
index b7c3122..0bf84e0 100644
--- a/pod/perlpodspec.pod
+++ b/pod/perlpodspec.pod
@@ -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