changeset 53218:917e6aba04d3

(Text Comparison): Correctly describe when two strings are `equal'. Combine and clarify descriptions of `assoc-ignore-case' and `assoc-ignore-representation'.

--- a/lispref/strings.texi	Mon Dec 01 03:57:00 2003 +0000
+++ b/lispref/strings.texi	Mon Dec 01 04:07:41 2003 +0000
@@ -417,8 +417,20 @@
 strings.  When @code{equal} (@pxref{Equality Predicates}) compares two
 strings, it uses @code{string=}.
 
-If the strings contain non-@acronym{ASCII} characters, and one is unibyte
-while the other is multibyte, then they cannot be equal.  @xref{Text
+For technical reasons, a unibyte and a multibyte string are
+@code{equal} if and only if they contain the same sequence of
+character codes and all these codes are either in the range 0 through
+127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
+However, when a unibyte string gets converted to a multibyte string,
+all characters with codes in the range 160 through 255 get converted
+to characters with higher codes, whereas @acronym{ASCII} characters
+remain unchanged.  Thus, a unibyte string and its conversion to
+multibyte are only @code{equal} if the string is all @acronym{ASCII}.
+Character codes 160 through 255 are not entirely proper in multibyte
+text, even though they can occur.  As a consequence, the situation
+where a unibyte and a multibyte string are @code{equal} without both
+being all @acronym{ASCII} is a technical oddity that very few Emacs
+Lisp programmers ever get confronted with.  @xref{Text
 Representations}.
 @end defun
 
@@ -493,9 +505,10 @@
 the string).
 
 The strings are both converted to multibyte for the comparison
-(@pxref{Text Representations}) so that a unibyte string can be equal to
-a multibyte string.  If @var{ignore-case} is non-@code{nil}, then case
-is ignored, so that upper case letters can be equal to lower case letters.
+(@pxref{Text Representations}) so that a unibyte string and its
+conversion to multibyte are always regarded as equal.  If
+@var{ignore-case} is non-@code{nil}, then case is ignored, so that
+upper case letters can be equal to lower case letters.
 
 If the specified portions of the two strings match, the value is
 @code{t}.  Otherwise, the value is an integer which indicates how many
@@ -506,15 +519,13 @@
 @end defun
 
 @defun assoc-ignore-case key alist
-This function works like @code{assoc}, except that @var{key} must be a
-string, and comparison is done using @code{compare-strings}, ignoring
-case differences.  @xref{Association Lists}.
-@end defun
-
-@defun assoc-ignore-representation key alist
-This function works like @code{assoc}, except that @var{key} must be a
-string, and comparison is done using @code{compare-strings}.
-Case differences are significant.
+@defunx assoc-ignore-representation key alist
+These functions work like @code{assoc}, except that @var{key} must be
+a string, all elements of @var{alist} must be cons cells whose
+@sc{car} is a string, and comparison is done using
+@code{compare-strings}.  @code{assoc-ignore-case} ignores case
+differences, whereas @code{assoc-ignore-representation} does not.
+@xref{Association Lists}.
 @end defun
 
   See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for