This commit was generated by cvs2svn to compensate for changes in r1117,

[chise/xemacs-chise.git.1] / man / lispref / text.texi

diff --git a/man/lispref/text.texi b/man/lispref/text.texi
index f66bf59..7aad873 100644 (file)
--- a/man/lispref/text.texi
+++ b/man/lispref/text.texi
@@ -70,12 +70,13 @@ functions usually did not have these optional @var{buffer} arguments
 and always operated on the current buffer.)
 
 
-@defun char-after position &optional buffer
+@defun char-after &optional position buffer
 This function returns the character in the buffer at (i.e.,
 immediately after) position @var{position}.  If @var{position} is out of
 range for this purpose, either before the beginning of the buffer, or at
-or beyond the end, then the value is @code{nil}.  If optional argument
-@var{buffer} is @code{nil}, the current buffer is assumed.
+or beyond the end, then the value is @code{nil}.  The default for
+@var{position} is point.  If optional argument @var{buffer} is
+@code{nil}, the current buffer is assumed.
 
 In the following example, assume that the first character in the
 buffer is @samp{@@}:
@@ -88,6 +89,15 @@ buffer is @samp{@@}:
 @end example
 @end defun
 
+@defun char-before &optional position buffer
+This function returns the character in the current buffer immediately
+before position @var{position}.  If @var{position} is out of range for
+this purpose, either at or before the beginning of the buffer, or beyond
+the end, then the value is @code{nil}.  The default for
+@var{position} is point.  If optional argument @var{buffer} is
+@code{nil}, the current buffer is assumed.
+@end defun
+
 @defun following-char &optional buffer
 This function returns the character following point in the buffer.
 This is similar to @code{(char-after (point))}.  However, if point is at
@@ -1478,7 +1488,7 @@ comparing the first characters of each, the second characters of each,
 and so on.  If a mismatch is found, it means that the sort keys are
 unequal; the sort key whose character is less at the point of first
 mismatch is the lesser sort key.  The individual characters are compared
-according to their numerical values.  Since Emacs uses the @sc{ASCII}
+according to their numerical values.  Since Emacs uses the @sc{ascii}
 character set, the ordering in that set determines alphabetical order.
 @c version 19 change
 
@@ -2464,18 +2474,59 @@ ThXs Xs the contents of the buffer before.
 
 @defun translate-region start end table
 This function applies a translation table to the characters in the
-buffer between positions @var{start} and @var{end}.
+buffer between positions @var{start} and @var{end}.  The translation
+table @var{table} can be either a string, a vector, or a char-table.
+
+If @var{table} is a string, its @var{n}th element is the mapping for the 
+character with code @var{n}.
+
+If @var{table} is a vector, its @var{n}th element is the mapping for
+character with code @var{n}.  Legal mappings are characters, strings, or
+@code{nil} (meaning don't replace.)
 
-The translation table @var{table} is a string; @code{(aref @var{table}
-@var{ochar})} gives the translated character corresponding to
-@var{ochar}.  If the length of @var{table} is less than 256, any
-characters with codes larger than the length of @var{table} are not
-altered by the translation.
+If @var{table} is a char-table, its elements describe the mapping
+between characters and their replacements.  The char-table should be of
+type @code{char} or @code{generic}.
+
+When the @var{table} is a string or vector and its length is less than
+the total number of characters (256 without Mule), any characters with
+codes larger than the length of @var{table} are not altered by the
+translation.
 
 The return value of @code{translate-region} is the number of
 characters that were actually changed by the translation.  This does
 not count characters that were mapped into themselves in the
 translation table.
+
+@strong{NOTE}: Prior to XEmacs 21.2, the @var{table} argument was
+allowed only to be a string.  This is still the case in FSF Emacs.
+
+The following example creates a char-table that is passed to
+@code{translate-region}, which translates character @samp{a} to
+@samp{the letter a}, removes character @samp{b}, and translates
+character @samp{c} to newline.
+
+@example
+@group
+---------- Buffer: foo ----------
+Here is a sentence in the buffer.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(let ((table (make-char-table 'generic)))
+  (put-char-table ?a "the letter a" table)
+  (put-char-table ?b "" table)
+  (put-char-table ?c ?\n table)
+  (translate-region (point-min) (point-max) table))
+     @result{} 3
+
+---------- Buffer: foo ----------
+Here is the letter a senten
+e in the uffer.
+---------- Buffer: foo ----------
+@end group
+@end example
 @end defun
 
 @node Registers