Fix bug 7425.

[bpt/emacs.git] / doc / lispref / text.texi

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 89dd539..2510607 100644 (file)
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -1,7 +1,8 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,

-@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c   Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/text
 @node Text, Non-ASCII Characters, Markers, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/text
 @node Text, Non-ASCII Characters, Markers, Top


@@ -42,7 +43,7 @@ the character after point.
 * The Kill Ring::    Where removed text sometimes is saved for later use.
 * Undo::             Undoing changes to the text of a buffer.
 * Maintaining Undo:: How to enable and disable undo information.
 * The Kill Ring::    Where removed text sometimes is saved for later use.
 * Undo::             Undoing changes to the text of a buffer.
 * Maintaining Undo:: How to enable and disable undo information.

-                       How to control how much information is kept.
+                        How to control how much information is kept.

 * Filling::          Functions for explicit filling.
 * Margins::          How to specify margins for filling commands.
 * Adaptive Fill::    Adaptive Fill mode chooses a fill prefix from context.
 * Filling::          Functions for explicit filling.
 * Margins::          How to specify margins for filling commands.
 * Adaptive Fill::    Adaptive Fill mode chooses a fill prefix from context.


@@ -821,7 +822,7 @@ would be difficult to change the terminology now.
 * Kill Functions::         Functions that kill text.
 * Yanking::                How yanking is done.
 * Yank Commands::          Commands that access the kill ring.
 * Kill Functions::         Functions that kill text.
 * Yanking::                How yanking is done.
 * Yank Commands::          Commands that access the kill ring.

-* Low-Level Kill Ring::           Functions and variables for kill ring access.
+* Low-Level Kill Ring::    Functions and variables for kill ring access.

 * Internals of Kill Ring:: Variables that hold kill ring data.
 @end menu
 
 * Internals of Kill Ring:: Variables that hold kill ring data.
 @end menu
 


@@ -899,10 +900,10 @@ from the buffer.  It returns @code{nil}.
 The command does not set @code{this-command} to @code{kill-region}, so a
 subsequent kill command does not append to the same kill ring entry.
 
 The command does not set @code{this-command} to @code{kill-region}, so a
 subsequent kill command does not append to the same kill ring entry.
 

-Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
-support Emacs 18.  For newer Emacs versions, it is better to use
-@code{kill-new} or @code{kill-append} instead.  @xref{Low-Level Kill
-Ring}.
+@c FIXME Why is it better?  Why isn't copy-region-as-kill obsolete then?
+@c Why is it used in many places in Emacs?
+In Lisp programs, it is better to use @code{kill-new} or
+@code{kill-append} instead of this command.  @xref{Low-Level Kill Ring}.

 @end deffn
 
 @node Yanking
 @end deffn
 
 @node Yanking


@@ -1040,8 +1041,8 @@ text property, if there is one.
 @subsection Low-Level Kill Ring
 
   These functions and variables provide access to the kill ring at a
 @subsection Low-Level Kill Ring
 
   These functions and variables provide access to the kill ring at a

-lower level, but still convenient for use in Lisp programs, because they
-take care of interaction with window system selections
+lower level, but are still convenient for use in Lisp programs,
+because they take care of interaction with window system selections

 (@pxref{Window System Selections}).
 
 @defun current-kill n &optional do-not-move
 (@pxref{Window System Selections}).
 
 @defun current-kill n &optional do-not-move


@@ -1298,13 +1299,16 @@ This function places a boundary element in the undo list.  The undo
 command stops at such a boundary, and successive undo commands undo
 to earlier and earlier boundaries.  This function returns @code{nil}.
 
 command stops at such a boundary, and successive undo commands undo
 to earlier and earlier boundaries.  This function returns @code{nil}.
 

-The editor command loop automatically creates an undo boundary before
-each key sequence is executed.  Thus, each undo normally undoes the
-effects of one command.  Self-inserting input characters are an
-exception.  The command loop makes a boundary for the first such
-character; the next 19 consecutive self-inserting input characters do
-not make boundaries, and then the 20th does, and so on as long as
-self-inserting characters continue.
+The editor command loop automatically calls @code{undo-boundary} just
+before executing each key sequence, so that each undo normally undoes
+the effects of one command.  As an exception, the command
+@code{self-insert-command}, which produces self-inserting input
+characters (@pxref{Commands for Insertion}), may remove the boundary
+inserted by the command loop: a boundary is accepted for the first
+such character, the next 19 consecutive self-inserting input
+characters do not have boundaries, and then the 20th does; and so on
+as long as the self-inserting characters continue.  Hence, sequences
+of consecutive character insertions can be undone as a group.

 
 All buffer modifications add a boundary whenever the previous undoable
 change was made in some other buffer.  This is to ensure that
 
 All buffer modifications add a boundary whenever the previous undoable
 change was made in some other buffer.  This is to ensure that


@@ -2593,9 +2597,9 @@ along with the characters; this includes such diverse functions as
 
 @menu
 * Examining Properties::   Looking at the properties of one character.
 
 @menu
 * Examining Properties::   Looking at the properties of one character.

-* Changing Properties::           Setting the properties of a range of text.
-* Property Search::       Searching for where a property changes value.
-* Special Properties::    Particular properties with special meanings.
+* Changing Properties::    Setting the properties of a range of text.
+* Property Search::        Searching for where a property changes value.
+* Special Properties::     Particular properties with special meanings.

 * Format Properties::      Properties for representing formatting of text.
 * Sticky Properties::      How inserted text gets properties from
                              neighboring text.
 * Format Properties::      Properties for representing formatting of text.
 * Sticky Properties::      How inserted text gets properties from
                              neighboring text.


@@ -2605,8 +2609,8 @@ along with the characters; this includes such diverse functions as
                              do something when you click on them.
 * Fields::                 The @code{field} property defines
                              fields within the buffer.
                              do something when you click on them.
 * Fields::                 The @code{field} property defines
                              fields within the buffer.

-* Not Intervals::         Why text properties do not use
-                            Lisp-visible text intervals.
+* Not Intervals::          Why text properties do not use
+                             Lisp-visible text intervals.

 @end menu
 
 @node Examining Properties
 @end menu
 
 @node Examining Properties


@@ -3031,7 +3035,7 @@ The @code{font-lock-face} property is equivalent to the @code{face}
 property when Font Lock mode is enabled.  When Font Lock mode is disabled,
 @code{font-lock-face} has no effect.
 
 property when Font Lock mode is enabled.  When Font Lock mode is disabled,
 @code{font-lock-face} has no effect.
 

-The @code{font-lock-mode} property is useful for special modes that
+The @code{font-lock-face} property is useful for special modes that

 implement their own highlighting.  @xref{Precalculated Fontification}.
 
 @item mouse-face
 implement their own highlighting.  @xref{Precalculated Fontification}.
 
 @item mouse-face


@@ -3166,9 +3170,20 @@ Consecutive characters with the same @code{field} property constitute a
 @item cursor
 @kindex cursor @r{(text property)}
 Normally, the cursor is displayed at the end of any overlay and text
 @item cursor
 @kindex cursor @r{(text property)}
 Normally, the cursor is displayed at the end of any overlay and text

-property strings present at the current window position.  You can
+property strings present at the current buffer position.  You can

 place the cursor on any desired character of these strings by giving
 place the cursor on any desired character of these strings by giving

-that character a non-@code{nil} @var{cursor} text property.
+that character a non-@code{nil} @code{cursor} text property.  In
+addition, if the value of the @code{cursor} property of an overlay
+string is an integer number, it specifies the number of buffer's
+character positions associated with the overlay string; this way,
+Emacs will display the cursor on the character with that property
+regardless of whether the current buffer position is actually covered
+by the overlay.  Specifically, if the value of the @code{cursor}
+property of a character is the number @var{n}, the cursor will be
+displayed on this character for any buffer position in the range
+@code{[@var{ovpos}..@var{ovpos}+@var{n}]}, where @var{ovpos} is the
+starting buffer position covered by the overlay (@pxref{Managing
+Overlays}).

 
 @item pointer
 @kindex pointer @r{(text property)}
 
 @item pointer
 @kindex pointer @r{(text property)}


@@ -3513,13 +3528,12 @@ following command:
 (defun dired-mouse-find-file-other-window (event)
   "In Dired, visit the file or directory name you click on."
   (interactive "e")
 (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)
       (goto-char pos)
       (setq file (dired-get-file-for-visit)))
     (if (file-directory-p file)


@@ -4265,6 +4279,4 @@ code that is itself run from a modification hook, then rebind locally
 @code{inhibit-modification-hooks} to @code{nil}.
 @end defvar
 
 @code{inhibit-modification-hooks} to @code{nil}.
 @end defvar
 

-@ignore
-   arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
-@end ignore
+