perlop.pod: Document current \000 \x behavior

Signed-off-by: David Golden <dagolden@cpan.org>

diff --git a/pod/perlop.pod b/pod/perlop.pod
index 3c6864a..6409f9d 100644 (file)
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -1019,24 +1019,52 @@ and in transliterations.
 X<\t> X<\n> X<\r> X<\f> X<\b> X<\a> X<\e> X<\x> X<\0> X<\c> X<\N> X<\N{}>
 
     Sequence    Note  Description
-    \t                tab             (HT, TAB)
-    \n                newline         (NL)
-    \r                return          (CR)
-    \f                form feed       (FF)
-    \b                backspace       (BS)
-    \a                alarm (bell)    (BEL)
-    \e                escape          (ESC)
-    \033              octal char      (example: ESC)
-    \x1b              hex char        (example: ESC)
-    \x{263a}          wide hex char   (example: SMILEY)
-    \c[          [1]  control char    (example: chr(27))
-    \N{name}     [2]  named Unicode character
-    \N{U+263D}   [3]  Unicode character (example: FIRST QUARTER MOON)
+    \t                tab               (HT, TAB)
+    \n                newline           (NL)
+    \r                return            (CR)
+    \f                form feed         (FF)
+    \b                backspace         (BS)
+    \a                alarm (bell)      (BEL)
+    \e                escape            (ESC)
+    \x{263a}     [1]  hex char          (example: SMILEY)
+    \x1b         [2]  narrow hex char   (example: ESC)
+    \N{name}     [3]  named Unicode character
+    \N{U+263D}   [4]  Unicode character (example: FIRST QUARTER MOON)
+    \c[          [5]  control char      (example: chr(27))
+    \033         [6]  octal char        (example: ESC)
 
 =over 4
 
 =item [1]
 
+The result is the character whose ordinal is the hexadecimal number between the
+braces.  If something other than a hexadecimal digit is encountered, it and
+everything following it up to the closing brace are discarded, and if warnings
+are enabled, a warning is raised.  The leading digits that are hex then
+comprise the entire number.  If the first thing after the opening brace is not
+a hex digit, the generated character is the NULL character.  C<\x{}> is the
+NULL character with no warning given.
+
+=item [2]
+
+The result is the character whose ordinal is the given two-digit hexadecimal
+number.  But, if I<H> is a hex digit and I<G> is not, then C<\xI<HG>...> is the
+same as C<\x0I<HG>...>, and C<\xI<G>...> is the same thing as C<\x00I<G>...>.
+In both cases, the result is two characters, and if warnings are enabled, a
+misleading warning message is raised that I<G> is ignored, when in fact it is
+used.  Note that in the second case, the first character currently is a NULL.
+
+=item [3]
+
+For documentation of C<\N{name}>, see L<charnames>.
+
+=item [4]
+
+C<\N{U+I<wide hex char>}> means the Unicode character whose Unicode ordinal
+number is I<wide hex char>.
+
+=item [5]
+
 The character following C<\c> is mapped to some other character as shown in the
 table:
 
@@ -1070,14 +1098,23 @@ the 7th bit (0x40).
 
 To get platform independent controls, you can use C<\N{...}>.
 
-=item [2]
-
-For documentation of C<\N{name}>, see L<charnames>.
-
-=item [3]
-
-C<\N{U+I<wide hex char>}> means the Unicode character whose Unicode ordinal
-number is I<wide hex char>.
+=item [6]
+
+The result is the character whose ordinal is the given three digit octal
+number.  Some contexts allow 2 or even 1 digit, but any usage without exactly
+three digits, the first being a zero, may give unintended results.  (For
+example, see L<perlrebackslash/Octal escapes>.)  It is best therefore to use
+this construct only for ordinals C<\077> and below, remembering to pad to the
+left with zeros to make three digits.  For larger ordinals, it's best to
+convert to some other construct, such as to hex and use C<\x{}> instead.
+
+A backslash followed by a non-octal digit in a bracketed character class
+(C<[\8]> or C<[\9]>) will be interpreted as a NULL character and the digit.
+Having fewer than 3 digits may lead to a misleading warning message that says
+that what follows is ignored.  For example, C<"\128"> in the ASCII character set
+is equivalent to the two characters C<"\n8">, but the warning C<Illegal octal
+digit '8' ignored> will be thrown.  To avoid this warning, make sure to pad
+your octal number with C<0>s: C<"\0128">.
 
 =back