PATCH: [perl #126177] Document /(?n)/

This adds /n to various places in perlre where it was omitted, and adds
a heading to better structure the document, and a clarifying sentence.

1 files changed, 22 insertions, 12 deletions

diff --git a/pod/perlre.pod b/pod/perlre.pod
index d97cfa39e4..2a4516cdb5 100644
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -22,6 +22,8 @@ find things that, while legal, may not be what you intended.
 
 =head2 Modifiers
 
+=head3 Overview
+
 Matching operations can have various modifiers.  Modifiers
 that relate to the interpretation of the regular expression inside
 are listed below.  Modifiers that alter the way a regular expression
@@ -152,11 +154,16 @@ L<perlop/"s/PATTERN/REPLACEMENT/msixpodualngcer"> are:
 
 Regular expression modifiers are usually written in documentation
 as e.g., "the C</x> modifier", even though the delimiter
-in question might not really be a slash.  The modifiers C</imsxadlup>
+in question might not really be a slash.  The modifiers C</imnsxadlup>
 may also be embedded within the regular expression itself using
 the C<(?...)> construct, see L</Extended Patterns> below.
 
-=head3 /x
+=head3 Details on some modifiers
+
+Some of the modifiers require more explanation than given in the
+L</Overview> above.
+
+=head4 /x
 
 C</x> tells
 the regular expression parser to ignore most whitespace that is neither
@@ -220,7 +227,7 @@ calls "Pattern White Space", namely:
  U+2028 LINE SEPARATOR
  U+2029 PARAGRAPH SEPARATOR
 
-=head3 Character set modifiers
+=head4 Character set modifiers
 
 C</d>, C</u>, C</a>, and C</l>, available starting in 5.14, are called
 the character set modifiers; they affect the character set rules
@@ -1067,9 +1074,9 @@ a backslash if it appears in the comment.
 
 See L</E<sol>x> for another way to have comments in patterns.
 
-=item C<(?adlupimsx-imsx)>
+=item C<(?adlupimnsx-imnsx)>
 
-=item C<(?^alupimsx)>
+=item C<(?^alupimnsx)>
 X<(?)> X<(?^)>
 
 One or more embedded pattern-match modifiers, to be turned on (or
@@ -1107,7 +1114,7 @@ expressions compiled within the scope of a C<use re>.  See
 L<re/"'/flags' mode">.
 
 Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately
-after the C<"?"> is a shorthand equivalent to C<d-imsx>.  Flags (except
+after the C<"?"> is a shorthand equivalent to C<d-imnsx>.  Flags (except
 C<"d">) may follow the caret to override it.
 But a minus sign is not legal with it.
 
@@ -1125,9 +1132,9 @@ anywhere in a pattern has a global effect.
 =item C<(?:pattern)>
 X<(?:)>
 
-=item C<(?adluimsx-imsx:pattern)>
+=item C<(?adluimnsx-imnsx:pattern)>
 
-=item C<(?^aluimsx:pattern)>
+=item C<(?^aluimnsx:pattern)>
 X<(?^:)>
 
 This is for clustering, not capturing; it groups subexpressions like
@@ -1143,7 +1150,7 @@ but doesn't spit out extra fields.  It's also cheaper not to capture
 characters if you don't need to.
 
 Any letters between C<?> and C<:> act as flags modifiers as with
-C<(?adluimsx-imsx)>.  For example,
+C<(?adluimnsx-imnsx)>.  For example,
 
     /(?s-i:more.*than).*million/i
 
@@ -1151,18 +1158,21 @@ is equivalent to the more verbose
 
     /(?:(?s-i)more.*than).*million/i
 
+Note that any C<(...)> constructs enclosed within this one will still
+capture unless the C</n> modifier is in effect.
+
 Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately
-after the C<"?"> is a shorthand equivalent to C<d-imsx>.  Any positive
+after the C<"?"> is a shorthand equivalent to C<d-imnsx>.  Any positive
 flags (except C<"d">) may follow the caret, so
 
     (?^x:foo)
 
 is equivalent to
 
-    (?x-ims:foo)
+    (?x-imns:foo)
 
 The caret tells Perl that this cluster doesn't inherit the flags of any
-surrounding pattern, but uses the system defaults (C<d-imsx>),
+surrounding pattern, but uses the system defaults (C<d-imnsx>),
 modified by any flags specified.
 
 The caret allows for simpler stringification of compiled regular