X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/67ab0163d67fbfeb41c37c8a259f27eeef965520..37b2bf43a95249276ecf0671c74dfa924a144f2c:/doc/lispref/markers.texi diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi index 7b73c454c8..19386d638f 100644 --- a/doc/lispref/markers.texi +++ b/doc/lispref/markers.texi @@ -1,9 +1,9 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software +@c Foundation, Inc. @c See the file elisp.texi for copying conditions. -@setfilename ../../info/markers -@node Markers, Text, Positions, Top +@node Markers @chapter Markers @cindex markers @@ -27,8 +27,8 @@ deleted, so that it stays with the two characters on either side of it. @node Overview of Markers @section Overview of Markers - A marker specifies a buffer and a position in that buffer. The -marker can be used to represent a position in the functions that + A marker specifies a buffer and a position in that buffer. A +marker can be used to represent a position in functions that require one, just as an integer could be used. In that case, the marker's buffer is normally ignored. Of course, a marker used in this way usually points to a position in the buffer that the function @@ -38,12 +38,12 @@ operates on, but that is entirely the programmer's responsibility. A marker has three attributes: the marker position, the marker buffer, and the insertion type. The marker position is an integer that is equivalent (at a given time) to the marker as a position in -that buffer. But the marker's position value can change often during -the life of the marker. Insertion and deletion of text in the buffer -relocate the marker. The idea is that a marker positioned between two -characters remains between those two characters despite insertion and -deletion elsewhere in the buffer. Relocation changes the integer -equivalent of the marker. +that buffer. But the marker's position value can change during +the life of the marker, and often does. Insertion and deletion of +text in the buffer relocate the marker. The idea is that a marker +positioned between two characters remains between those two characters +despite insertion and deletion elsewhere in the buffer. Relocation +changes the integer equivalent of the marker. @cindex marker relocation Deleting text around a marker's position leaves the marker between the @@ -58,12 +58,12 @@ with @code{insert-before-markers} (@pxref{Insertion}). relocate them if necessary. This slows processing in a buffer with a large number of markers. For this reason, it is a good idea to make a marker point nowhere if you are sure you don't need it any more. -Unreferenced markers are garbage collected eventually, but until then -will continue to use time if they do point somewhere. +Markers that can no longer be accessed are eventually removed +(@pxref{Garbage Collection}). @cindex markers as numbers Because it is common to perform arithmetic operations on a marker -position, most of the arithmetic operations (including @code{+} and +position, most of these operations (including @code{+} and @code{-}) accept markers as arguments. In such cases, the marker stands for its current position. @@ -188,7 +188,7 @@ chapter. (point-min-marker) @result{} # (point-max-marker) - @result{} # + @result{} # @end group @group @@ -206,7 +206,7 @@ chapter. @end example @end defun -@defun copy-marker marker-or-integer &optional insertion-type +@defun copy-marker &optional marker-or-integer insertion-type If passed a marker as its argument, @code{copy-marker} returns a new marker that points to the same place and the same buffer as does @var{marker-or-integer}. If passed an integer as its argument, @@ -216,11 +216,14 @@ new marker that points to the same place and the same buffer as does The new marker's insertion type is specified by the argument @var{insertion-type}. @xref{Marker Insertion Types}. +@c This behavior used to be documented until 2013/08. +@ignore If passed an integer argument less than 1, @code{copy-marker} returns a new marker that points to the beginning of the current buffer. If passed an integer argument greater than the length of the buffer, @code{copy-marker} returns a new marker that points to the end of the buffer. +@end ignore @example @group @@ -229,8 +232,8 @@ buffer. @end group @group -(copy-marker 20000) - @result{} # +(copy-marker 90000) + @result{} # @end group @end example @@ -279,6 +282,8 @@ This function returns the position that @var{marker} points to, or This function returns the buffer that @var{marker} points into, or @code{nil} if it points nowhere. +@c FIXME: The `buffer' argument of `set-marker' already defaults to +@c the current buffer, why use `(current-buffer)' explicitly here? @example @group (setq m (make-marker)) @@ -308,11 +313,6 @@ This function returns the buffer that @var{marker} points into, or @end example @end defun -@defun buffer-has-markers-at position -This function returns @code{t} if one or more markers -point at position @var{position} in the current buffer. -@end defun - @node Marker Insertion Types @section Marker Insertion Types @@ -344,21 +344,27 @@ specify the insertion type, create them with insertion type @section Moving Marker Positions This section describes how to change the position of an existing -marker. When you do this, be sure you know whether the marker is used -outside of your program, and, if so, what effects will result from -moving it---otherwise, confusing things may happen in other parts of -Emacs. +marker. When you do this, be sure you know how the marker is used +outside of your program. For example, moving a marker to an unrelated +new position can cause undo to later adjust the marker incorrectly. +Often when you wish to relocate a marker to an unrelated position, it +is preferable to make a new marker and set the prior one to point +nowhere. @defun set-marker marker position &optional buffer This function moves @var{marker} to @var{position} in @var{buffer}. If @var{buffer} is not provided, it defaults to the current buffer. +@c This behavior used to be documented until 2013/08. +@ignore If @var{position} is less than 1, @code{set-marker} moves @var{marker} to the beginning of the buffer. If @var{position} is greater than the -size of the buffer, @code{set-marker} moves marker to the end of the -buffer. If @var{position} is @code{nil} or a marker that points -nowhere, then @var{marker} is set to point nowhere. +size of the buffer (@pxref{Point}), @code{set-marker} moves marker to +the end of the buffer. +@end ignore +If @var{position} is @code{nil} or a marker that points nowhere, then +@var{marker} is set to point nowhere. The value returned is @var{marker}. @@ -389,7 +395,7 @@ This is another name for @code{set-marker}. @node The Mark @section The Mark @cindex mark, the -@cindex mark ring +@c @cindex the mark? Each buffer has a special marker, which is designated @dfn{the mark}. When a buffer is newly created, this marker exists but does @@ -422,12 +428,13 @@ can request deactivation of the mark upon return to the editor command loop by setting the variable @code{deactivate-mark} to a non-@code{nil} value. - If Transient Mode is enabled, certain editing commands that normally -apply to text near point, apply instead to the region when the mark is -active. This is the main motivation for using Transient Mark mode. -(Another is that this enables highlighting of the region when the mark -is active. @xref{Display}.) + If Transient Mark mode is enabled, certain editing commands that +normally apply to text near point, apply instead to the region when +the mark is active. This is the main motivation for using Transient +Mark mode. (Another is that this enables highlighting of the region +when the mark is active. @xref{Display}.) +@cindex mark ring In addition to the mark, each buffer has a @dfn{mark ring} which is a list of markers containing previous values of the mark. When editing commands change the mark, they should normally save the old value of the @@ -509,7 +516,8 @@ example: This function sets the current buffer's mark to @var{position}, and pushes a copy of the previous mark onto @code{mark-ring}. If @var{position} is @code{nil}, then the value of point is used. -@code{push-mark} returns @code{nil}. +@c Doesn't seem relevant. +@c @code{push-mark} returns @code{nil}. The function @code{push-mark} normally @emph{does not} activate the mark. To do that, specify @code{t} for the argument @var{activate}. @@ -523,8 +531,9 @@ This function pops off the top element of @code{mark-ring} and makes that mark become the buffer's actual mark. This does not move point in the buffer, and it does nothing if @code{mark-ring} is empty. It deactivates the mark. - -The return value is not meaningful. +@c +@c Seems even less relevant. +@c The return value is not meaningful. @end defun @defopt transient-mark-mode @@ -593,8 +602,16 @@ the function @code{use-region-p} for that (@pxref{The Region}). @defvarx deactivate-mark-hook These normal hooks are run, respectively, when the mark becomes active and when it becomes inactive. The hook @code{activate-mark-hook} is -also run at the end of a command if the mark is active and it is -possible that the region may have changed. +also run at the end of the command loop if the mark is active and it +is possible that the region may have changed. +@ignore +This piece of command_loop_1, run unless deactivating the mark: + if (current_buffer != prev_buffer || MODIFF != prev_modiff) + { + Lisp_Object hook = intern ("activate-mark-hook"); + Frun_hooks (1, &hook); + } +@end ignore @end defvar @defun handle-shift-selection @@ -634,9 +651,17 @@ more marks than this are pushed onto the @code{mark-ring}, @code{push-mark} discards an old mark when it adds a new one. @end defopt +@c There is also global-mark-ring-max, but this chapter explicitly +@c does not talk about the global mark. + @node The Region @section The Region -@cindex region (between point and mark) +@c The index entry must be just ``region'' to make it the first hit +@c when the user types ``i region RET'', because otherwise the Info +@c reader will present substring matches in alphabetical order, +@c putting this one near the end, with something utterly unrelated as +@c the first hit. +@cindex region The text between point and the mark is known as @dfn{the region}. Various functions operate on text delimited by point and the mark, but @@ -660,16 +685,26 @@ integer). This is the position of either point or the mark, whichever is larger. @end defun - Few programs need to use the @code{region-beginning} and -@code{region-end} functions. A command designed to operate on a region -should normally use @code{interactive} with the @samp{r} specification -to find the beginning and end of the region. This lets other Lisp -programs specify the bounds explicitly as arguments. (@xref{Interactive -Codes}.) +@c FIXME: Mention it in tips.texi? + Instead of using @code{region-beginning} and @code{region-end}, a +command designed to operate on a region should normally use +@code{interactive} with the @samp{r} specification to find the +beginning and end of the region. This lets other Lisp programs +specify the bounds explicitly as arguments. @xref{Interactive Codes}. @defun use-region-p This function returns @code{t} if Transient Mark mode is enabled, the -mark is active, and there's a valid region in the buffer. Commands -that operate on the region (instead of on text near point) when -there's an active mark should use this to test whether to do that. +mark is active, and there is a valid region in the buffer. This +function is intended to be used by commands that operate on the +region, instead of on text near point, when the mark is active. + +@cindex empty region +@vindex use-empty-active-region +A region is valid if it has a non-zero size, or if the user option +@code{use-empty-active-region} is non-@code{nil} (by default, it is +@code{nil}). The function @code{region-active-p} is similar to +@code{use-region-p}, but considers all regions as valid. In most +cases, you should not use @code{region-active-p}, since if the region +is empty it is often more appropriate to operate on point. @end defun +