no message

13 files changed, 95 insertions, 60 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 0f4abc7a984..6dfc203f638 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,27 @@
+2010-01-04  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        Avoid dubious uses of save-excursions.
+        * positions.texi (Excursions): Recommend the use of
+        save-current-buffer if applicable.
+        * text.texi (Clickable Text): Fix the example code which used
+        save-excursion in a naive way which sometimes preserves point and
+        sometimes not.
+        * variables.texi (Creating Buffer-Local):
+        * os.texi (Session Management):
+        * display.texi (GIF Images):
+        * control.texi (Cleanups): Use (save|with)-current-buffer.
+
+2010-01-02  Eli Zaretskii  <eliz@gnu.org>
+
+        * modes.texi (Example Major Modes): Fix indentation.  (Bug#5195)
+
+2010-01-02  Chong Yidong  <cyd@stupidchicken.com>
+
+        * nonascii.texi (Text Representations, Character Codes)
+        (Converting Representations, Explicit Encoding)
+        (Translation of Characters): Use hex notation consistently.
+        (Character Sets): Fix map-charset-chars doc (Bug#5197).
+
 2010-01-01  Chong Yidong  <cyd@stupidchicken.com>
 
         * loading.texi (Where Defined): Make it clearer that these are
@@ -8364,7 +8388,7 @@
 ;; End:
 
     Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
-      2007, 2008, 2009  Free Software Foundation, Inc.
+      2007, 2008, 2009, 2010  Free Software Foundation, Inc.
 
   This file is part of GNU Emacs.
 
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 41f844b4e21..6d7c01d354b 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1255,9 +1255,8 @@ make sure to kill it before finishing:
 
 @smallexample
 @group
-(save-excursion
-  (let ((buffer (get-buffer-create " *temp*")))
-    (set-buffer buffer)
+(let ((buffer (get-buffer-create " *temp*")))
+  (with-current-buffer buffer
     (unwind-protect
         @var{body-form}
       (kill-buffer buffer))))
@@ -1269,7 +1268,7 @@ You might think that we could just as well write @code{(kill-buffer
 (current-buffer))} and dispense with the variable @code{buffer}.
 However, the way shown above is safer, if @var{body-form} happens to
 get an error after switching to a different buffer!  (Alternatively,
-you could write another @code{save-excursion} around @var{body-form},
+you could write a @code{save-current-buffer} around @var{body-form},
 to ensure that the temporary buffer becomes current again in time to
 kill it.)
 
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 8feb8ea8c81..512d7d53019 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4394,8 +4394,7 @@ every 0.1 seconds.
   (when (= idx max)
     (setq idx 0))
   (let ((img (create-image file nil :image idx)))
-    (save-excursion
-      (set-buffer buffer)
+    (with-current-buffer buffer
       (goto-char (point-min))
       (unless first-time (delete-char 1))
       (insert-image img))
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 1e7ef76ed55..c78ced0d67b 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1062,8 +1062,8 @@ correspondingly more complicated.  Here are excerpts from
       ;;   @r{part of symbol names but not words.}
       ;;   @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
       (while (< i ?0)
-        (modify-syntax-entry i "_   " table)
-        (setq i (1+ i)))
+        (modify-syntax-entry i "_   " table)
+        (setq i (1+ i)))
       ;; @r{@dots{} similar code follows for other character ranges.}
 @end group
 @group
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index d3bbc2c114f..59f790c90da 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -46,12 +46,12 @@ in most any known written language.
 follows the @dfn{Unicode Standard}.  The Unicode Standard assigns a
 unique number, called a @dfn{codepoint}, to each and every character.
 The range of codepoints defined by Unicode, or the Unicode
-@dfn{codespace}, is @code{0..10FFFF} (in hex), inclusive.  Emacs
-extends this range with codepoints in the range @code{110000..3FFFFF},
-which it uses for representing characters that are not unified with
-Unicode and raw 8-bit bytes that cannot be interpreted as characters
-(the latter occupy the range @code{3FFF80..3FFFFF}).  Thus, a
-character codepoint in Emacs is a 22-bit integer number.
+@dfn{codespace}, is @code{0..#x10FFFF} (in hexadecimal notation),
+inclusive.  Emacs extends this range with codepoints in the range
+@code{#x110000..#x3FFFFF}, which it uses for representing characters
+that are not unified with Unicode and @dfn{raw 8-bit bytes} that
+cannot be interpreted as characters.  Thus, a character codepoint in
+Emacs is a 22-bit integer number.
 
 @cindex internal representation of characters
 @cindex characters, representation in buffers and strings
@@ -189,8 +189,8 @@ of characters as @var{string}.  If @var{string} is a multibyte string,
 it is returned unchanged.  The function assumes that @var{string}
 includes only @acronym{ASCII} characters and raw 8-bit bytes; the
 latter are converted to their multibyte representation corresponding
-to the codepoints in the @code{3FFF80..3FFFFF} area (@pxref{Text
-Representations, codepoints}).
+to the codepoints @code{#x3FFF80} through @code{#x3FFFFF}, inclusive
+(@pxref{Text Representations, codepoints}).
 @end defun
 
 @defun string-to-unibyte string
@@ -271,15 +271,19 @@ contains no text properties.
 
   The unibyte and multibyte text representations use different
 character codes.  The valid character codes for unibyte representation
-range from 0 to 255---the values that can fit in one byte.  The valid
-character codes for multibyte representation range from 0 to 4194303
-(#x3FFFFF).  In this code space, values 0 through 127 are for
-@acronym{ASCII} characters, and values 128 through 4194175 (#x3FFF7F)
-are for non-@acronym{ASCII} characters.  Values 0 through 1114111
-(#10FFFF) correspond to Unicode characters of the same codepoint;
-values 1114112 (#110000) through 4194175 (#x3FFF7F) represent
-characters that are not unified with Unicode; and values 4194176
-(#x3FFF80) through 4194303 (#x3FFFFF) represent eight-bit raw bytes.
+range from 0 to @code{#xFF} (255)---the values that can fit in one
+byte.  The valid character codes for multibyte representation range
+from 0 to @code{#x3FFFFF}.  In this code space, values 0 through
+@code{#x7F} (127) are for @acronym{ASCII} characters, and values
+@code{#x80} (128) through @code{#x3FFF7F} (4194175) are for
+non-@acronym{ASCII} characters.
+
+  Emacs character codes are a superset of the Unicode standard.
+Values 0 through @code{#x10FFFF} (1114111) correspond to Unicode
+characters of the same codepoint; values @code{#x110000} (1114112)
+through @code{#x3FFF7F} (4194175) represent characters that are not
+unified with Unicode; and values @code{#x3FFF80} (4194176) through
+@code{#x3FFFFF} (4194303) represent eight-bit raw bytes.
 
 @defun characterp charcode
 This returns @code{t} if @var{charcode} is a valid character, and
@@ -540,7 +544,7 @@ and strings.
 @cindex @code{eight-bit}, a charset
   Emacs defines several special character sets.  The character set
 @code{unicode} includes all the characters whose Emacs code points are
-in the range @code{0..10FFFF}.  The character set @code{emacs}
+in the range @code{0..#x10FFFF}.  The character set @code{emacs}
 includes all @acronym{ASCII} and non-@acronym{ASCII} characters.
 Finally, the @code{eight-bit} charset includes the 8-bit raw bytes;
 Emacs uses it to represent raw bytes encountered in text.
@@ -628,12 +632,12 @@ that fits the second argument of @code{decode-char} above.  If
   The following function comes in handy for applying a certain
 function to all or part of the characters in a charset:
 
-@defun map-charset-chars function charset &optional arg from to
+@defun map-charset-chars function charset &optional arg from-code to-code
 Call @var{function} for characters in @var{charset}.  @var{function}
 is called with two arguments.  The first one is a cons cell
 @code{(@var{from} .  @var{to})}, where @var{from} and @var{to}
 indicate a range of characters contained in charset.  The second
-argument is the optional argument @var{arg}.
+argument passed to @var{function} is @var{arg}.
 
 By default, the range of codepoints passed to @var{function} includes
 all the characters in @var{charset}, but optional arguments
@@ -751,7 +755,7 @@ This variable automatically becomes buffer-local when set.
 
 @defun make-translation-table-from-vector vec
 This function returns a translation table made from @var{vec} that is
-an array of 256 elements to map byte values 0 through 255 to
+an array of 256 elements to map bytes (values 0 through #xFF) to
 characters.  Elements may be @code{nil} for untranslated bytes.  The
 returned table has a translation table for reverse mapping in the
 first extra slot, and the value @code{1} in the second extra slot.
@@ -1562,10 +1566,10 @@ in this section.
 text.  They logically consist of a series of byte values; that is, a
 series of @acronym{ASCII} and eight-bit characters.  In unibyte
 buffers and strings, these characters have codes in the range 0
-through 255.  In a multibyte buffer or string, eight-bit characters
-have character codes higher than 255 (@pxref{Text Representations}),
-but Emacs transparently converts them to their single-byte values when
-you encode or decode such text.
+through #xFF (255).  In a multibyte buffer or string, eight-bit
+characters have character codes higher than #xFF (@pxref{Text
+Representations}), but Emacs transparently converts them to their
+single-byte values when you encode or decode such text.
 
   The usual way to read a file into a buffer as a sequence of bytes, so
 you can decode the contents explicitly, is with
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index ded70f4927b..8d62ab87499 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2182,7 +2182,7 @@ Emacs is restarted by the session manager.
 
 @group
 (defun save-yourself-test ()
-  (insert "(save-excursion
+  (insert "(save-current-buffer
   (switch-to-buffer \"*scratch*\")
   (insert \"I am restored\"))")
   nil)
diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index deded596f81..3897efc6f2b 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -806,7 +806,9 @@ after the completion of the excursion.
 
   The forms for saving and restoring the configuration of windows are
 described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
-Configurations}).
+Configurations}).  When only the identity of the current buffer needs
+to be saved and restored, it is preferable to use
+@code{save-current-buffer} instead.
 
 @defspec save-excursion body@dots{}
 @cindex mark excursion
@@ -817,10 +819,10 @@ buffer and the values of point and the mark in it, evaluates
 point and the mark.  All three saved values are restored even in case of
 an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
 
-The @code{save-excursion} special form is the standard way to switch
-buffers or move point within one part of a program and avoid affecting
-the rest of the program.  It is used more than 4000 times in the Lisp
-sources of Emacs.
+The @code{save-excursion} special form is the standard way to move
+point within one part of a program and avoid affecting the rest of the
+program.  It is used more than 4000 times in the Lisp sources
+of Emacs.
 
 @code{save-excursion} does not save the values of point and the mark for
 other buffers, so changes in other buffers remain in effect after
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 91b65017754..7c3f91c3fa8 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3524,13 +3524,12 @@ following command:
 (defun dired-mouse-find-file-other-window (event)
   "In Dired, visit the file or directory name you click on."
   (interactive "e")
-  (let (window pos file)
-    (save-excursion
-      (setq window (posn-window (event-end event))
-            pos (posn-point (event-end event)))
-      (if (not (windowp window))
-          (error "No file chosen"))
-      (set-buffer (window-buffer window))
+  (let ((window (posn-window (event-end event)))
+        (pos (posn-point (event-end event)))
+        file)
+    (if (not (windowp window))
+        (error "No file chosen"))
+    (with-current-buffer (window-buffer window)
       (goto-char pos)
       (setq file (dired-get-file-for-visit)))
     (if (file-directory-p file)
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 4f9f9c17369..d8ab347eebf 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1240,8 +1240,7 @@ foo
 
 @group
 ;; @r{In buffer @samp{b2}, the value hasn't changed.}
-(save-excursion
-  (set-buffer "b2")
+(with-current-buffer "b2"
   foo)
      @result{} 5
 @end group
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 75561a0ba21..cabec8f7fb1 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,13 @@
+2010-01-04  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * gnus.texi (Posting Styles): Use with-current-buffer.
+        * calc.texi (Defining Simple Commands): Prefer save-current-buffer.
+
+2010-01-02  Kevin Ryde  <user42@zip.com.au>
+
+        * eieio.texi (Naming Conventions): Correction to xref on elisp
+        coding conventions, is "Tips" node not "Standards".
+
 2009-12-24  Chong Yidong  <cyd@stupidchicken.com>
 
         * calc.texi (General Mode Commands): Calc file should be in .emacs.d.
@@ -6507,7 +6517,7 @@
 ;; End:
 
     Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
-      2003, 2004, 2005, 2006, 2007, 2008, 2009  Free Software Foundation, Inc.
+      2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010  Free Software Foundation, Inc.
 
   This file is part of GNU Emacs.
 
diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi
index c88bb3e9ab8..e7c03197704 100644
--- a/doc/misc/calc.texi
+++ b/doc/misc/calc.texi
@@ -31968,7 +31968,7 @@ the function with code that looks roughly like this:
 @smallexample
 (let ((calc-command-flags nil))
   (unwind-protect
-      (save-excursion
+      (save-current-buffer
         (calc-select-buffer)
         @emph{body of function}
         @emph{renumber stack}
diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi
index c8a34bbd160..06ff1677f0f 100755
--- a/doc/misc/eieio.texi
+++ b/doc/misc/eieio.texi
@@ -11,7 +11,7 @@
 @copying
 This manual documents EIEIO, an object framework for Emacs Lisp.
 
-Copyright @copyright{} 2007, 2008, 2009 Free Software Foundation, Inc.
+Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -1776,11 +1776,11 @@ This signal is called when an attempt to reference @var{slot} in
 @comment  node-name,  next,  previous,  up
 @chapter Naming Conventions
 
-@pxref{Standards,,,elisp,GNU Emacs Lisp Reference Manual}, for a
-description of Emacs Lisp programming conventions.  These conventions
-help ensure that Emacs packages work nicely one another, so an
-@eieio{}-based program should follow them.  Here are some conventions
-that apply specifically to @eieio{}-based programs:
+@xref{Tips,,Tips and Conventions,elisp,GNU Emacs Lisp Reference
+Manual}, for a description of Emacs Lisp programming conventions.
+These conventions help ensure that Emacs packages work nicely one
+another, so an @eieio{}-based program should follow them.  Here are
+some conventions that apply specifically to @eieio{}-based programs:
 
 @itemize
 
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index e90789d2494..a33a91ba6f1 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -10,7 +10,7 @@
 
 @copying
 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -13449,8 +13449,7 @@ So here's a new example:
          (body "You are fired.\n\nSincerely, your boss.")
          (organization "Important Work, Inc"))
         ("nnml:.*"
-         (From (save-excursion
-                 (set-buffer gnus-article-buffer)
+         (From (with-current-buffer gnus-article-buffer
                  (message-fetch-field "to"))))
         ("^nn.+:"
          (signature-file "~/.mail-signature"))))