Clarify perldiag/Ambiguous use of %c{%s%s}

${foo[2]} only warns with built-in keywords. (See the source in
toke.c:S_scan_ident which uses keyword().)

The suggested use of $foo[2] instead of ${foo[2]} does not
always work.

I also added an ‘and’ to clarify the existing text.

1 files changed, 15 insertions, 5 deletions

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 030cdcfc70..fd6f17cd16 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -121,11 +121,21 @@ and a function with the same name, and save yourself a lot of trouble.
 
 =item Ambiguous use of %c{%s%s} resolved to %c%s%s
 
-(W ambiguous) You wrote something like C<${foo[2]}>, which might be
-looking for element number 2 of the array named C<@foo>, in which case
-please write C<$foo[2]>, or you might have meant to pass an anonymous
-arrayref to the function named foo, then do a scalar deref on the
-value it returns.  If you meant that, write C<${foo([2])}>.
+(W ambiguous) You wrote something like C<${foo[2]}> (where foo
+represents the name of a Perl keyword), which might be looking for
+element number 2 of the array named C<@foo>, in which case please write
+C<$foo[2]>, or you might have meant to pass an anonymous arrayref to
+the function named foo, and then do a scalar deref on the value it
+returns.  If you meant that, write C<${foo([2])}>.
+
+In regular expressions, the C<${foo[2]}> syntax is sometimes necessary
+to disambiguate between array subscripts and character classes.
+C</$length[2345]/>, for instance, will be interpreted as C<$length>
+followed by the character class C<[2345]>. If an array subscript is what
+you want, you can avoid the warning by changing C</${length[2345]}/>
+to the unsightly C</${\$length[2345]}/>, by renaming your array to
+something that does not coincide with a built-in keyword, or by
+simply turning off warnings with C<no warnings 'ambiguous';>.
 
 =item Ambiguous use of -%s resolved as -&%s()