Merge changes from emacs-23 branch.

[gnu-emacs] / doc / lispref / text.texi

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 07c5d5c8a8c44580444ba03a0df1e9b156625aae..a7c4a3e62f4c38b843608a01de1e2b4191bb6f46 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
 


@@ -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


@@ -1629,15 +1633,9 @@ As a practical matter, if you are writing text for other people to
 read, you should set @code{fill-column} to no more than 70.  Otherwise
 the line will be too long for people to read comfortably, and this can
 make the text seem clumsy.
 read, you should set @code{fill-column} to no more than 70.  Otherwise
 the line will be too long for people to read comfortably, and this can
 make the text seem clumsy.

-@end defopt
-
-@defvar default-fill-column
-The value of this variable is the default value for @code{fill-column} in
-buffers that do not override it.  This is the same as
-@code{(default-value 'fill-column)}.

 
 

-The default value for @code{default-fill-column} is 70.
-@end defvar
+The default value for @code{fill-column} is 70.
+@end defopt

 
 @deffn Command set-left-margin from to margin
 This sets the @code{left-margin} property on the text from @var{from} to
 
 @deffn Command set-left-margin from to margin
 This sets the @code{left-margin} property on the text from @var{from} to


@@ -1690,20 +1688,20 @@ may involve either inserting or deleting whitespace.)  This function
 is value of @code{indent-line-function} in Paragraph-Indent Text mode.
 @end defun
 
 is value of @code{indent-line-function} in Paragraph-Indent Text mode.
 @end defun
 

-@defvar left-margin
+@defopt left-margin

 This variable specifies the base left margin column.  In Fundamental
 mode, @kbd{C-j} indents to this column.  This variable automatically
 becomes buffer-local when set in any fashion.
 This variable specifies the base left margin column.  In Fundamental
 mode, @kbd{C-j} indents to this column.  This variable automatically
 becomes buffer-local when set in any fashion.

-@end defvar
+@end defopt

 
 

-@defvar fill-nobreak-predicate
+@defopt fill-nobreak-predicate

 This variable gives major modes a way to specify not to break a line
 at certain places.  Its value should be a list of functions.  Whenever
 filling considers breaking the line at a certain place in the buffer,
 it calls each of these functions with no arguments and with point
 located at that place.  If any of the functions returns
 non-@code{nil}, then the line won't be broken there.
 This variable gives major modes a way to specify not to break a line
 at certain places.  Its value should be a list of functions.  Whenever
 filling considers breaking the line at a certain place in the buffer,
 it calls each of these functions with no arguments and with point
 located at that place.  If any of the functions returns
 non-@code{nil}, then the line won't be broken there.

-@end defvar
+@end defopt

 
 @node Adaptive Fill
 @section Adaptive Fill Mode
 
 @node Adaptive Fill
 @section Adaptive Fill Mode


@@ -2599,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.


@@ -2611,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


@@ -3018,7 +3016,7 @@ time you want to specify a particular attribute for certain text.
 
 @item
 A cons cell with the form @code{(foreground-color . @var{color-name})}
 
 @item
 A cons cell with the form @code{(foreground-color . @var{color-name})}

-or @code{(background-color . @var{color-name})}.  These are older,
+or @code{(background-color . @var{color-name})}.  These are old,

 deprecated equivalents for @code{(:foreground @var{color-name})} and
 @code{(:background @var{color-name})}.  Please convert code that uses
 them.
 deprecated equivalents for @code{(:foreground @var{color-name})} and
 @code{(:background @var{color-name})}.  Please convert code that uses
 them.


@@ -3037,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


@@ -3172,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)}


@@ -3519,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)