[win32] maintpatches for docs

	    #53:  "Perlop bitwise & | ^ documentation"
	 Msg-ID:  <Pine.GSO.3.96.971106073858.29771O-100000@usertest.teleport.c
	   Date:  Thu, 6 Nov 1997 07:44:52 -0800 (PST)
	  Files:  pod/perlfunc.pod
	-------- 
	    #54:  "Update docs on tr///"
	   From:  Tom Phoenix <rootbeer@teleport.com>
	 Msg-ID:  <Pine.GSO.3.96.971103071602.10568C-100000@usertest.teleport.c
	   Date:  Mon, 3 Nov 1997 07:28:39 -0800 (PST)
	  Files:  pod/perldelta.pod pod/perldiag.pod pod/perlfunc.pod
		  pod/perllocale.pod pod/perlmod.pod pod/perlop.pod
		  pod/perlstyle.pod toke.c

p4raw-id: //depot/win32/perl@635

8 files changed, 69 insertions, 36 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index ac02ac68af..9443f386d9 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -1208,7 +1208,7 @@ or a hash slice, such as
 
 =item Applying %s to %s will act on scalar(%s)
 
-(W) The pattern match (//), substitution (s///), and translation (tr///)
+(W) The pattern match (//), substitution (s///), and transliteration (tr///)
 operators work on scalar values.  If you apply one of them to an array
 or a hash, it will convert the array or hash to a scalar value -- the
 length of an array, or the population info of a hash -- and then work on
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 35eff72ef7..9f16761239 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -194,7 +194,7 @@ the return value of your socket() call?  See L<perlfunc/accept>.
 
 =item Applying %s to %s will act on scalar(%s)
 
-(W) The pattern match (//), substitution (s///), and translation (tr///)
+(W) The pattern match (//), substitution (s///), and transliteration (tr///)
 operators work on scalar values.  If you apply one of them to an array
 or a hash, it will convert the array or hash to a scalar value -- the
 length of an array, or the population info of a hash -- and then work on
@@ -2469,13 +2469,13 @@ Perl yourself.
 (F) The regular expression ends with an unbackslashed backslash.  Backslash
 it.   See L<perlre>.
 
-=item Translation pattern not terminated
+=item Transliteration pattern not terminated
 
 (F) The lexer couldn't find the interior delimiter of a tr/// or tr[][]
 or y/// or y[][] construct.  Missing the leading C<$> from variables
 C<$tr> or C<$y> may cause this error.
 
-=item Translation replacement not terminated
+=item Transliteration replacement not terminated
 
 (F) The lexer couldn't find the final delimiter of a tr/// or tr[][]
 construct.
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 0570c8fe64..f509f61553 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3720,7 +3720,7 @@ seconds, for this process and the children of this process.
 
 =item tr///
 
-The translation operator.  Same as y///. See L<perlop>.
+The transliteration operator.  Same as y///. See L<perlop>.
 
 =item truncate FILEHANDLE,LENGTH
 
@@ -4062,6 +4062,6 @@ Note that write is I<NOT> the opposite of read.  Unfortunately.
 
 =item y///
 
-The translation operator.  Same as tr///.  See L<perlop>.
+The transliteration operator.  Same as tr///.  See L<perlop>.
 
 =back
diff --git a/pod/perllocale.pod b/pod/perllocale.pod
index 037fcc9f91..70a32e4fe9 100644
--- a/pod/perllocale.pod
+++ b/pod/perllocale.pod
@@ -491,7 +491,7 @@ regular expressions.)  Thanks to C<LC_CTYPE>, depending on your locale
 setting, characters like 'E<aelig>', 'E<eth>', 'E<szlig>', and
 'E<oslash>' may be understood as C<\w> characters.
 
-The C<LC_CTYPE> locale also provides the map used in translating
+The C<LC_CTYPE> locale also provides the map used in transliterating
 characters between lower and uppercase.  This affects the case-mapping
 functions - lc(), lcfirst, uc() and ucfirst(); case-mapping
 interpolation with C<\l>, C<\L>, C<\u> or <\U> in double-quoted strings
diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index 4d0ad2d449..942f216dda 100644
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -45,7 +45,7 @@ forced to be in package C<main>, even when used for other purposes than
 their builtin one.  Note also that, if you have a package called C<m>,
 C<s>, or C<y>, then you can't use the qualified form of an identifier
 because it will be interpreted instead as a pattern match, a substitution,
-or a translation.
+or a transliteration.
 
 (Variables beginning with underscore used to be forced into package
 main, but we decided it was more useful for package writers to be able
diff --git a/pod/perlop.pod b/pod/perlop.pod
index 17728df9d3..5d1aae79a6 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -145,7 +145,7 @@ is returned.  One effect of these rules is that C<-bareword> is equivalent
 to C<"-bareword">.
 
 Unary "~" performs bitwise negation, i.e., 1's complement.
-(See also L<Integer Arithmetic>.)
+(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
 
 Unary "+" has no effect whatsoever, even on strings.  It is useful
 syntactically for separating a function name from a parenthesized expression
@@ -162,11 +162,11 @@ thing from interpretation.
 Binary "=~" binds a scalar expression to a pattern match.  Certain operations
 search or modify the string $_ by default.  This operator makes that kind
 of operation work on some other string.  The right argument is a search
-pattern, substitution, or translation.  The left argument is what is
-supposed to be searched, substituted, or translated instead of the default
+pattern, substitution, or transliteration.  The left argument is what is
+supposed to be searched, substituted, or transliterated instead of the default
 $_.  The return value indicates the success of the operation.  (If the
 right argument is an expression rather than a search pattern,
-substitution, or translation, it is interpreted as a search pattern at run
+substitution, or transliteration, it is interpreted as a search pattern at run
 time.  This can be is less efficient than an explicit search, because the
 pattern must be compiled every time the expression is evaluated.
 
@@ -300,15 +300,15 @@ by the current locale if C<use locale> is in effect.  See L<perllocale>.
 =head2 Bitwise And
 
 Binary "&" returns its operators ANDed together bit by bit.
-(See also L<Integer Arithmetic>.)
+(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
 
 =head2 Bitwise Or and Exclusive Or
 
 Binary "|" returns its operators ORed together bit by bit.
-(See also L<Integer Arithmetic>.)
+(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
 
 Binary "^" returns its operators XORed together bit by bit.
-(See also L<Integer Arithmetic>.)
+(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
 
 =head2 C-style Logical And
 
@@ -558,14 +558,14 @@ any pair of delimiters you choose.  Non-bracketing delimiters use
 the same character fore and aft, but the 4 sorts of brackets
 (round, angle, square, curly) will all nest.
 
-    Customary  Generic     Meaning    Interpolates
-	''	 q{}	   Literal	   no
-	""	qq{}	   Literal	   yes
-	``	qx{}	   Command	   yes
-		qw{}	  Word list	   no
-	//	 m{}	Pattern match	   yes
-		 s{}{}	 Substitution	   yes
-		tr{}{}	 Translation	   no
+    Customary  Generic        Meaning	     Interpolates
+	''	 q{}	      Literal		  no
+	""	qq{}	      Literal		  yes
+	``	qx{}	      Command		  yes
+		qw{}	     Word list		  no
+	//	 m{}	   Pattern match	  yes
+		 s{}{}	    Substitution	  yes
+		tr{}{}	  Transliteration	  no (but see below)
 
 Note that there can be whitespace between the operator and the quoting
 characters, except when C<#> is being used as the quoting character.
@@ -576,8 +576,9 @@ next line. This allows you to write:
     s {foo}  # Replace foo
       {bar}  # with bar.
 
-For constructs that do interpolation, variables beginning with "C<$>" or "C<@>"
-are interpolated, as are the following sequences:
+For constructs that do interpolation, variables beginning with "C<$>"
+or "C<@>" are interpolated, as are the following sequences. Within
+a transliteration, the first ten of these sequences may be used.
 
     \t		tab             (HT, TAB)
     \n		newline         (LF, NL)
@@ -589,6 +590,7 @@ are interpolated, as are the following sequences:
     \033	octal char
     \x1b	hex char
     \c[		control char
+
     \l		lowercase next char
     \u		uppercase next char
     \L		lowercase till \E
@@ -954,16 +956,18 @@ to occur.  Here are two common cases:
 
 =item y/SEARCHLIST/REPLACEMENTLIST/cds
 
-Translates all occurrences of the characters found in the search list
+Transliterates all occurrences of the characters found in the search list
 with the corresponding character in the replacement list.  It returns
 the number of characters replaced or deleted.  If no string is
-specified via the =~ or !~ operator, the $_ string is translated.  (The
+specified via the =~ or !~ operator, the $_ string is transliterated.  (The
 string specified with =~ must be a scalar variable, an array element, a
 hash element, or an assignment to one of those, i.e., an lvalue.)
+A character range may be specified with a hyphen, so C<tr/A-J/0-9/> 
+does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>.
 For B<sed> devotees, C<y> is provided as a synonym for C<tr>.  If the
 SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has
 its own pair of quotes, which may or may not be bracketing quotes,
-e.g., C<tr[A-Z][a-z]> or C<tr(+-*/)/ABCD/>.
+e.g., C<tr[A-Z][a-z]> or C<tr(+\-*/)/ABCD/>.
 
 Options:
 
@@ -977,7 +981,7 @@ by SEARCHLIST not found in REPLACEMENTLIST are deleted.  (Note
 that this is slightly more flexible than the behavior of some B<tr>
 programs, which delete anything they find in the SEARCHLIST, period.)
 If the C</s> modifier is specified, sequences of characters that were
-translated to the same character are squashed down to a single instance of the
+transliterated to the same character are squashed down to a single instance of the
 character.
 
 If the C</d> modifier is used, the REPLACEMENTLIST is always interpreted
@@ -1006,13 +1010,13 @@ Examples:
     tr [\200-\377]
        [\000-\177];		# delete 8th bit
 
-If multiple translations are given for a character, only the first one is used:
+If multiple transliterations are given for a character, only the first one is used:
 
     tr/AAA/XYZ/
 
-will translate any A to X.
+will transliterate any A to X.
 
-Note that because the translation table is built at compile time, neither
+Note that because the transliteration table is built at compile time, neither
 the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote
 interpolation.  That means that if you want to use variables, you must use
 an eval():
@@ -1213,6 +1217,34 @@ the compiler will precompute the number that
 expression represents so that the interpreter
 won't have to.
 
+=head2 Bitwise String Operators
+
+Bitstrings of any size may be manipulated by the bitwise operators
+(C<~ | & ^>).
+
+If the operands to a binary bitwise op are strings of different sizes,
+B<or> and B<xor> ops will act as if the shorter operand had additional
+zero bits on the right, while the B<and> op will act as if the longer
+operand were truncated to the length of the shorter.
+
+    # ASCII-based examples 
+    print "j p \n" ^ " a h";        	# prints "JAPH\n"
+    print "JA" | "  ph\n";          	# prints "japh\n"
+    print "japh\nJunk" & '_____';   	# prints "JAPH\n";
+    print 'p N$' ^ " E<H\n";		# prints "Perl\n";
+
+If you are intending to manipulate bitstrings, you should be certain that
+you're supplying bitstrings: If an operand is a number, that will imply
+a B<numeric> bitwise operation. You may explicitly show which type of
+operation you intend by using C<""> or C<0+>, as in the examples below.
+
+    $foo =  150  |  105 ;	# yields 255  (0x96 | 0x69 is 0xFF)
+    $foo = '150' |  105 ;	# yields 255
+    $foo =  150  | '105';	# yields 255
+    $foo = '150' | '105';	# yields string '155' (under ASCII)
+
+    $baz = 0+$foo & 0+$bar;	# both ops explicitly numeric
+    $biz = "$foo" ^ "$bar";	# both ops explicitly stringy
 
 =head2 Integer Arithmetic
 
@@ -1230,7 +1262,8 @@ countermand this by saying
 which lasts until the end of that BLOCK.
 
 The bitwise operators ("&", "|", "^", "~", "<<", and ">>") always
-produce integral results.  However, C<use integer> still has meaning
+produce integral results.  (But see also L<Bitwise String Operators>.)
+However, C<use integer> still has meaning
 for them.  By default, their results are interpreted as unsigned
 integers.  However, if C<use integer> is in effect, their results are
 interpreted as signed integers.  For example, C<~0> usually evaluates
diff --git a/pod/perlstyle.pod b/pod/perlstyle.pod
index bfc94a9eaa..5ad73cfafe 100644
--- a/pod/perlstyle.pod
+++ b/pod/perlstyle.pod
@@ -250,7 +250,7 @@ sufficient example:
 
 =item *
 
-Line up your translations when it makes sense:
+Line up your transliterations when it makes sense:
 
     tr [abc]
        [xyz];
diff --git a/toke.c b/toke.c
index 128b828d1c..ad423642a6 100644
--- a/toke.c
+++ b/toke.c
@@ -4969,7 +4969,7 @@ scan_trans(char *start)
 	if (lex_stuff)
 	    SvREFCNT_dec(lex_stuff);
 	lex_stuff = Nullsv;
-	croak("Translation pattern not terminated");
+	croak("Transliteration pattern not terminated");
     }
     if (s[-1] == multi_open)
 	s--;
@@ -4982,7 +4982,7 @@ scan_trans(char *start)
 	if (lex_repl)
 	    SvREFCNT_dec(lex_repl);
 	lex_repl = Nullsv;
-	croak("Translation replacement not terminated");
+	croak("Transliteration replacement not terminated");
     }
 
     New(803,tbl,256,short);