Merge from emacs--devo--0

Patches applied:

 * emacs--devo--0  (patch 887-889)

   - Update from CVS
   - Merge from emacs--rel--22

 * emacs--rel--22  (patch 116-121)

   - Update from CVS

Revision: emacs@sv.gnu.org/emacs--unicode--0--patch-268

8 files changed, 180 insertions, 113 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 279a9a47ec3..9d5e6158f3f 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,7 @@
+2007-10-13  Eric S. Raymond  <esr@snark.thyrsus.com>
+
+        * files.texi: Capitalize node names according to convention.
+
 2007-10-13  Glenn Morris  <rgm@gnu.org>
 
         * misc.texi (Interactive Shell): Correct INSIDE_EMACS reference.
@@ -23,6 +27,11 @@
         * files.texi (Version Systems): Describe newer VCses.
         Reorder the descriptions to be chronological.
 
+2007-10-09  Richard Stallman  <rms@gnu.org>
+
+        * display.texi (Cursor Display): Correct how cursor appears
+        in nonselected windows.
+
 2007-10-04  Nick Roberts  <nickrob@snap.net.nz>
 
         * building.texi (GDB Graphical Interface): Remove references to gdba
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index d4d2945d584..5e1e0056592 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1116,12 +1116,12 @@ doesn't switch, so it uses the normal cursor.
 
 @cindex cursor in non-selected windows
 @vindex cursor-in-non-selected-windows
-  Normally, the cursor appears in non-selected windows in the ``off''
-state, with the same appearance as when the blinking cursor blinks
+  Normally, the cursor appears in non-selected windows without
+blinking, with the same appearance as when the blinking cursor blinks
 ``off.''  For a box cursor, this is a hollow box; for a bar cursor,
 this is a thinner bar.  To turn off cursors in non-selected windows,
-customize the variable @code{cursor-in-non-selected-windows} and assign
-it a @code{nil} value.
+customize the variable @code{cursor-in-non-selected-windows} and
+assign it a @code{nil} value.
 
 @vindex x-stretch-cursor
 @cindex wide block cursor
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 78c72dac330..80feaea2340 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1595,15 +1595,15 @@ system, but is usually not excessive.
 @subsection Basic Editing under Version Control
 
 @menu
-* Selecting a fileset::          Choosing a set of files to operate on 
-* Doing the next logical thing:: Stepping forward in the development cycle
-* VC with a locking VCS::     RCS in its default mode, SCCS, and optionally CVS.
-* VC with a merging VCS::     Without locking: default mode for CVS.
-* Advanced C-x v v::    Advanced features available with a prefix argument.
-* Log Buffer::          Features available in log entry buffers.
+* Selecting A Fileset::    Choosing a set of files to operate on 
+* Doing The Right Thing::  Stepping forward in the development cycle
+* VC With A Locking VCS::  RCS in its default mode, SCCS, and optionally CVS.
+* VC With A Merging VCS::  Without locking: default mode for CVS.
+* Advanced C-x v v::       Advanced features available with a prefix argument.
+* Log Buffer::             Features available in log entry buffers.
 @end menu
 
-@node Selecting a fileset
+@node Selecting A Fileset
 @subsubsection Choosing the scope of your command
 
 @cindex filesets
@@ -1638,7 +1638,7 @@ marked files, but did not pass them to the version-control backends as
 a group.  Now it does, which enables VC to drive changeset-based
 version-control systems.
 
-@node Doing the next logical thing
+@node Doing The Right Thing
 @subsubsection Performing the next operation in the development cycle
 
   The principal VC command is an all-purpose command that performs
@@ -1667,7 +1667,7 @@ accidentally edit a file without properly checking it out first.  To
 achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only}
 in your @file{~/.emacs} file.  (@xref{Init Rebinding}.)
 
-@node VC with a locking VCS
+@node VC With A Locking VCS
 @subsubsection Basic Version Control with Locking
 
   If locking is used for the file (as with SCCS, and RCS in its default
@@ -1698,7 +1698,7 @@ formerly locked the file, to inform him of what has happened.
   These rules also apply when you use CVS in locking mode, except
 that there is no such thing as stealing a lock.
 
-@node VC with a merging VCS
+@node VC With A Merging VCS
 @subsubsection Basic Version Control with Merging
 
   When your version-control system is merging-based rather than
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 5c4f9159066..d95597e940b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,25 @@
+2007-10-13  Karl Berry  <karl@gnu.org>
+
+        * elisp.texi (@dircategory): Move to after @copying,
+        since we want @copying as close as possible to the beginning of
+        the output.
+
+2007-10-12  Richard Stallman  <rms@gnu.org>
+
+        * elisp.texi (Top): Add Distinguish Interactive to subnode menu.
+
+        * commands.texi (Distinguish Interactive): New node,
+        broken out from Interactive Call and rewritten.
+        (Command Loop): Put Distinguish Interactive in menu.
+
+2007-10-09  Richard Stallman  <rms@gnu.org>
+
+        * text.texi (Examining Properties): Mention overlay priority.
+
+        * display.texi (Display Margins): Correct the description
+        of margin display specifications.
+        (Replacing Specs): New subnode broken out of Display Property.
+
 2007-10-06  Juri Linkov  <juri@jurta.org>
 
         * text.texi (Filling): Document fill-paragraph-or-region.
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index aaad7ca82a7..cdd627f6b52 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -18,6 +18,7 @@ are done, and the subroutines that allow Lisp programs to do them.
 * Command Overview::    How the command loop reads commands.
 * Defining Commands::   Specifying how a function should read arguments.
 * Interactive Call::    Calling a command, so that it will read arguments.
+* Distinguish Interactive::     Making a command distinguish interactive calls.
 * Command Loop Info::   Variables set by the command loop for you to examine.
 * Adjusting Point::     Adjustment of point after a command.
 * Input Events::        What input looks like when you read it.
@@ -635,42 +636,74 @@ part of the prompt.
 @end example
 @end deffn
 
-@defun interactive-p
-This function returns @code{t} if the containing function (the one
-whose code includes the call to @code{interactive-p}) was called in
-direct response to user input.  This means that it was called with the
-function @code{call-interactively}, and that a keyboard macro is
-not running, and that Emacs is not running in batch mode.
+@node Distinguish Interactive
+@section Distinguish Interactive Calls
+
+  Sometimes a command should display additional visual feedback (such
+as an informative message in the echo area) for interactive calls
+only.  There are three ways to do this.  The recommended way to test
+whether the function was called using @code{call-interactively} is to
+give it an optional argument @code{print-message} and use the
+@code{interactive} spec to make it non-@code{nil} in interactive
+calls.  Here's an example:
+
+@example
+(defun foo (&optional print-message)
+  (interactive "p")
+  (when print-message
+    (message "foo")))
+@end example
+
+@noindent
+We use @code{"p"} because the numeric prefix argument is never
+@code{nil}.  Defined in this way, the function does display the
+message when called from a keyboard macro.
+
+  The above method with the additional argument is usually best,
+because it allows callers to say ``treat this call as interactive.''
+But you can also do the job in a simpler way by testing
+@code{called-interactively-p}.
+
+@defun called-interactively-p
+This function returns @code{t} when the calling function was called
+using @code{call-interactively}.
 
 If the containing function was called by Lisp evaluation (or with
 @code{apply} or @code{funcall}), then it was not called interactively.
 @end defun
 
-  The most common use of @code{interactive-p} is for deciding whether
-to give the user additional visual feedback (such as by printing an
-informative message).  For example:
+   Here's an example of using @code{called-interactively-p}:
 
 @example
 @group
-;; @r{Here's the usual way to use @code{interactive-p}.}
 (defun foo ()
   (interactive)
-  (when (interactive-p)
-    (message "foo")))
+  (when (called-interactively-p)
+    (message "foo"))
+  'haha)
      @result{} foo
 @end group
 
 @group
-;; @r{This function is just to illustrate the behavior.}
-(defun bar ()
-  (interactive)
-  (setq foobar (list (foo) (interactive-p))))
-     @result{} bar
+;; @r{Type @kbd{M-x foo}.}
+     @print{} foo
 @end group
 
 @group
-;; @r{Type @kbd{M-x foo}.}
-     @print{} foo
+(foo)
+     @result{} haha
+@end group
+@end example
+
+  Here is another example that contrasts direct and indirect
+calls to @code{called-interactively-p}.
+
+@example
+@group
+(defun bar ()
+  (interactive)
+  (setq foobar (list (foo) (called-interactively-p))))
+     @result{} bar
 @end group
 
 @group
@@ -684,31 +717,16 @@ foobar
 @end group
 @end example
 
-  If you want to test @emph{only} whether the function was called
-using @code{call-interactively}, add an optional argument
-@code{print-message} which should be non-@code{nil} in an interactive
-call, and use the @code{interactive} spec to make sure it is
-non-@code{nil}.  Here's an example:
-
-@example
-(defun foo (&optional print-message)
-  (interactive "p")
-  (when print-message
-    (message "foo")))
-@end example
-
-@noindent
-Defined in this way, the function does display the message when called
-from a keyboard macro.  We use @code{"p"} because the numeric prefix
-argument is never @code{nil}.
-
-@defun called-interactively-p
-This function returns @code{t} when the calling function was called
-using @code{call-interactively}.
+  If you want to treat commands run in keyboard macros just like calls
+from Lisp programs, test @code{interactive-p} instead of
+@code{called-interactively-p}.
 
-When possible, instead of using this function, you should use the
-method in the example above; that method makes it possible for a
-caller to ``pretend'' that the function was called interactively.
+@defun interactive-p
+This function returns @code{t} if the containing function (the one
+whose code includes the call to @code{interactive-p}) was called in
+direct response to user input.  This means that it was called with the
+function @code{call-interactively}, and that a keyboard macro is
+not running, and that Emacs is not running in batch mode.
 @end defun
 
 @node Command Loop Info
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 90d94dbe6b3..4c9df9c5ede 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3245,21 +3245,47 @@ to use the value specified by the frame.
 insert images into text, and also control other aspects of how text
 displays.  The value of the @code{display} property should be a
 display specification, or a list or vector containing several display
-specifications.  Display specifications generally apply in parallel to
-the text they cover.
+specifications.  Display specifications in the same @code{display}
+property value generally apply in parallel to the text they cover.
+
+  If several sources (overlays and/or a text property) specify values
+for the @code{display} property, only one of the values takes effect,
+following the rules of @code{get-char-property}.  @xref{Examining
+Properties}.
+
+  The rest of this section describes several kinds of
+display specifications and what they mean.
+
+@menu
+* Replacing Specs::      Display specs that replace the text.
+* Specified Space::      Displaying one space with a specified width.
+* Pixel Specification::  Specifying space width or height in pixels.
+* Other Display Specs::  Displaying an image; magnifying text; moving it
+                          up or down on the page; adjusting the width
+                          of spaces within text.
+* Display Margins::     Displaying text or images to the side of the main text.
+@end menu
+
+@node Replacing Specs
+@subsection Display Specs That Replace The Text
 
   Some kinds of @code{display} specifications specify something to
-display instead of the text that has the property.  If a list of
-display specifications includes more than one of this kind, the first
-is effective and the rest are ignored.  You cannot interactively move
-point into the middle of the text that is thus replaced.
-
-  For these specifications, ``the text that has the property'' means
-all the consecutive characters that have the same Lisp object as their
-@code{display} property; these characters are replaced as a single
-unit.  By contrast, characters that have similar but distinct Lisp
-objects as their @code{display} properties are handled separately.
-Here's a function that illustrates this point:
+display instead of the text that has the property.  These are called
+@dfn{replacing} display specifications.  Emacs does not allow the user
+to interactively move point into the middle of buffer text that is
+replaced in this way.
+
+  If a list of display specifications includes more than one replacing
+display specification, the first overrides the rest.  Replacing
+display specifications make most other display specifications
+irrelevant, since those don't apply to the replacement.
+
+  For replacing display specifications, ``the text that has the
+property'' means all the consecutive characters that have the same
+Lisp object as their @code{display} property; these characters are
+replaced as a single unit.  By contrast, characters that have similar
+but distinct Lisp objects as their @code{display} properties are
+handled separately.  Here's a function that illustrates this point:
 
 @smallexample
 (defun foo ()
@@ -3299,18 +3325,6 @@ object as the @code{display} property value, it's irrelevant
 whether they got this property from a single call to
 @code{put-text-property} or from two different calls.
 
-  The rest of this section describes several kinds of
-display specifications and what they mean.
-
-@menu
-* Specified Space::      Displaying one space with a specified width.
-* Pixel Specification::  Specifying space width or height in pixels.
-* Other Display Specs::  Displaying an image; magnifying text; moving it
-                          up or down on the page; adjusting the width
-                          of spaces within text.
-* Display Margins::     Displaying text or images to the side of the main text.
-@end menu
-
 @node Specified Space
 @subsection Specified Spaces
 @cindex spaces, specified height or width
@@ -3549,25 +3563,28 @@ string.
 @cindex display margins
 @cindex margins, display
 
-  A buffer can have blank areas called @dfn{display margins} on the left
-and on the right.  Ordinary text never appears in these areas, but you
-can put things into the display margins using the @code{display}
-property.
-
-  To put text in the left or right display margin of the window, use a
-display specification of the form @code{(margin right-margin)} or
-@code{(margin left-margin)} on it.  To put an image in a display margin,
-use that display specification along with the display specification for
-the image.  Unfortunately, there is currently no way to make
-text or images in the margin mouse-sensitive.
-
-  If you put such a display specification directly on text in the
-buffer, the specified margin display appears @emph{instead of} that
-buffer text itself.  To put something in the margin @emph{in
-association with} certain buffer text without preventing or altering
-the display of that text, put a @code{before-string} property on the
-text and put the display specification on the contents of the
-before-string.
+  A buffer can have blank areas called @dfn{display margins} on the
+left and on the right.  Ordinary text never appears in these areas,
+but you can put things into the display margins using the
+@code{display} property.  There is currently no way to make text or
+images in the margin mouse-sensitive.
+
+  The way to display something in the margins is to specify it in a
+margin display specification in the @code{display} property of some
+text.  This is a replacing display specification, meaning that the
+text you put it on does not get displayed; the margin display appears,
+but that text does not.
+
+  A margin display specification looks like @code{((margin
+right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}.
+Here, @var{spec} is another display specification that says what to
+display in the margin.  Typically it is a string of text to display,
+or an image descriptor.
+
+  To display something in the margin @emph{in association with}
+certain buffer text, without altering or preventing the display of
+that text, put a @code{before-string} property on the text and put the
+margin display specification on the contents of the before-string.
 
   Before the display margins can display anything, you must give
 them a nonzero width.  The usual way to do that is to set these
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 613bdbace38..8cd25ed59d3 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -9,11 +9,6 @@
 @set VERSION  2.9
 @set EMACSVER 23.0.50
 
-@dircategory Emacs
-@direntry
-* Elisp: (elisp).       The Emacs Lisp Reference Manual.
-@end direntry
-
 @c in general, keep the following line commented out, unless doing a
 @c copy of this manual that will be published.  The manual should go
 @c onto the distribution in the full, 8.5 x 11" size.
@@ -67,6 +62,11 @@ developing GNU and promoting software freedom.''
 @end quotation
 @end copying
 
+@dircategory Emacs
+@direntry
+* Elisp: (elisp).       The Emacs Lisp Reference Manual.
+@end direntry
+
 @titlepage
 @title GNU Emacs Lisp Reference Manual
 @subtitle For Emacs Version @value{EMACSVER}
@@ -639,6 +639,7 @@ Command Loop
 * Command Overview::    How the command loop reads commands.
 * Defining Commands::   Specifying how a function should read arguments.
 * Interactive Call::    Calling a command, so that it will read arguments.
+* Distinguish Interactive::     Making a command distinguish interactive calls.
 * Command Loop Info::   Variables set by the command loop for you to examine.
 * Adjusting Point::     Adjustment of point after a command.
 * Input Events::        What input looks like when you read it.
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index c6da06b4a13..daaaf6c9b9d 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2619,13 +2619,13 @@ the @var{prop} property of that symbol.
 This function is like @code{get-text-property}, except that it checks
 overlays first and then text properties.  @xref{Overlays}.
 
-The argument @var{object} may be a string, a buffer, or a window.  If it
-is a window, then the buffer displayed in that window is used for text
-properties and overlays, but only the overlays active for that window
-are considered.  If @var{object} is a buffer, then all overlays in that
-buffer are considered, as well as text properties.  If @var{object} is a
-string, only text properties are considered, since strings never have
-overlays.
+The argument @var{object} may be a string, a buffer, or a window.  If
+it is a window, then the buffer displayed in that window is used for
+text properties and overlays, but only the overlays active for that
+window are considered.  If @var{object} is a buffer, then overlays in
+that buffer are considered first, in order of decreasing priority,
+followed by the text properties.  If @var{object} is a string, only
+text properties are considered, since strings never have overlays.
 @end defun
 
 @defun get-char-property-and-overlay position prop &optional object