clarification of multi-bracket format

2 files changed, 20 insertions, 2 deletions

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 826dea54dc..415d13c0d8 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 b7c3122f02..0bf84e0910 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