[Emacs-diffs] Changes to markers.texi

[Glenn Morris]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Glenn Morris <gm>       07/09/06 04:21:52

Index: markers.texi
===================================================================
RCS file: markers.texi
diff -N markers.texi
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ markers.texi        6 Sep 2007 04:21:52 -0000       1.1
@@ -0,0 +1,664 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 
2001,
address@hidden   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, 
Inc.
address@hidden See the file elisp.texi for copying conditions.
address@hidden ../info/markers
address@hidden Markers, Text, Positions, Top
address@hidden Markers
address@hidden markers
+
+  A @dfn{marker} is a Lisp object used to specify a position in a buffer
+relative to the surrounding text.  A marker changes its offset from the
+beginning of the buffer automatically whenever text is inserted or
+deleted, so that it stays with the two characters on either side of it.
+
address@hidden
+* Overview of Markers::      The components of a marker, and how it relocates.
+* Predicates on Markers::    Testing whether an object is a marker.
+* Creating Markers::         Making empty markers or markers at certain places.
+* Information from Markers:: Finding the marker's buffer or character position.
+* Marker Insertion Types::   Two ways a marker can relocate when you
+                               insert where it points.
+* Moving Markers::           Moving the marker to a new buffer or position.
+* The Mark::                 How "the mark" is implemented with a marker.
+* The Region::               How to access "the region".
address@hidden menu
+
address@hidden Overview of Markers
address@hidden 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
+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
+operates on, but that is entirely the programmer's responsibility.
address@hidden, for a complete description of positions.
+
+  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.
+
address@hidden marker relocation
+  Deleting text around a marker's position leaves the marker between the
+characters immediately before and after the deleted text.  Inserting
+text at the position of a marker normally leaves the marker either in
+front of or after the new text, depending on the marker's @dfn{insertion
+type} (@pxref{Marker Insertion Types})---unless the insertion is done
+with @code{insert-before-markers} (@pxref{Insertion}).
+
address@hidden marker garbage collection
+  Insertion and deletion in a buffer must check all the markers and
+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.
+
address@hidden markers as numbers
+  Because it is common to perform arithmetic operations on a marker
+position, most of the arithmetic operations (including @code{+} and
address@hidden) accept markers as arguments.  In such cases, the marker
+stands for its current position.
+
+Here are examples of creating markers, setting markers, and moving point
+to markers:
+
address@hidden
address@hidden
+;; @r{Make a new marker that initially does not point anywhere:}
+(setq m1 (make-marker))
+     @result{} #<marker in no buffer>
address@hidden group
+
address@hidden
+;; @r{Set @code{m1} to point between the 99th and 100th characters}
+;;   @r{in the current buffer:}
+(set-marker m1 100)
+     @result{} #<marker at 100 in markers.texi>
address@hidden group
+
address@hidden
+;; @r{Now insert one character at the beginning of the buffer:}
+(goto-char (point-min))
+     @result{} 1
+(insert "Q")
+     @result{} nil
address@hidden group
+
address@hidden
+;; @address@hidden is updated appropriately.}
+m1
+     @result{} #<marker at 101 in markers.texi>
address@hidden group
+
address@hidden
+;; @r{Two markers that point to the same position}
+;;   @r{are not @code{eq}, but they are @code{equal}.}
+(setq m2 (copy-marker m1))
+     @result{} #<marker at 101 in markers.texi>
+(eq m1 m2)
+     @result{} nil
+(equal m1 m2)
+     @result{} t
address@hidden group
+
address@hidden
+;; @r{When you are finished using a marker, make it point nowhere.}
+(set-marker m1 nil)
+     @result{} #<marker in no buffer>
address@hidden group
address@hidden example
+
address@hidden Predicates on Markers
address@hidden Predicates on Markers
+
+  You can test an object to see whether it is a marker, or whether it is
+either an integer or a marker.  The latter test is useful in connection
+with the arithmetic functions that work with both markers and integers.
+
address@hidden markerp object
+This function returns @code{t} if @var{object} is a marker, @code{nil}
+otherwise.  Note that integers are not markers, even though many
+functions will accept either a marker or an integer.
address@hidden defun
+
address@hidden integer-or-marker-p object
+This function returns @code{t} if @var{object} is an integer or a marker,
address@hidden otherwise.
address@hidden defun
+
address@hidden number-or-marker-p object
+This function returns @code{t} if @var{object} is a number (either
+integer or floating point) or a marker, @code{nil} otherwise.
address@hidden defun
+
address@hidden Creating Markers
address@hidden Functions that Create Markers
+
+  When you create a new marker, you can make it point nowhere, or point
+to the present position of point, or to the beginning or end of the
+accessible portion of the buffer, or to the same place as another given
+marker.
+
+The next four functions all return markers with insertion type
address@hidden  @xref{Marker Insertion Types}.
+
address@hidden make-marker
+This function returns a newly created marker that does not point
+anywhere.
+
address@hidden
address@hidden
+(make-marker)
+     @result{} #<marker in no buffer>
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden point-marker
+This function returns a new marker that points to the present position
+of point in the current buffer.  @xref{Point}.  For an example, see
address@hidden, below.
address@hidden defun
+
address@hidden point-min-marker
+This function returns a new marker that points to the beginning of the
+accessible portion of the buffer.  This will be the beginning of the
+buffer unless narrowing is in effect.  @xref{Narrowing}.
address@hidden defun
+
address@hidden point-max-marker
+This function returns a new marker that points to the end of the
+accessible portion of the buffer.  This will be the end of the buffer
+unless narrowing is in effect.  @xref{Narrowing}.
+
+Here are examples of this function and @code{point-min-marker}, shown in
+a buffer containing a version of the source file for the text of this
+chapter.
+
address@hidden
address@hidden
+(point-min-marker)
+     @result{} #<marker at 1 in markers.texi>
+(point-max-marker)
+     @result{} #<marker at 15573 in markers.texi>
address@hidden group
+
address@hidden
+(narrow-to-region 100 200)
+     @result{} nil
address@hidden group
address@hidden
+(point-min-marker)
+     @result{} #<marker at 100 in markers.texi>
address@hidden group
address@hidden
+(point-max-marker)
+     @result{} #<marker at 200 in markers.texi>
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden copy-marker marker-or-integer &optional 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
address@hidden  If passed an integer as its argument,
address@hidden returns a new marker that points to position
address@hidden in the current buffer.
+
+The new marker's insertion type is specified by the argument
address@hidden  @xref{Marker Insertion Types}.
+
+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,
address@hidden returns a new marker that points to the end of the
+buffer.
+
address@hidden
address@hidden
+(copy-marker 0)
+     @result{} #<marker at 1 in markers.texi>
address@hidden group
+
address@hidden
+(copy-marker 20000)
+     @result{} #<marker at 7572 in markers.texi>
address@hidden group
address@hidden example
+
+An error is signaled if @var{marker} is neither a marker nor an
+integer.
address@hidden defun
+
+  Two distinct markers are considered @code{equal} (even though not
address@hidden) to each other if they have the same position and buffer, or
+if they both point nowhere.
+
address@hidden
address@hidden
+(setq p (point-marker))
+     @result{} #<marker at 2139 in markers.texi>
address@hidden group
+
address@hidden
+(setq q (copy-marker p))
+     @result{} #<marker at 2139 in markers.texi>
address@hidden group
+
address@hidden
+(eq p q)
+     @result{} nil
address@hidden group
+
address@hidden
+(equal p q)
+     @result{} t
address@hidden group
address@hidden example
+
address@hidden Information from Markers
address@hidden Information from Markers
+
+  This section describes the functions for accessing the components of a
+marker object.
+
address@hidden marker-position marker
+This function returns the position that @var{marker} points to, or
address@hidden if it points nowhere.
address@hidden defun
+
address@hidden marker-buffer marker
+This function returns the buffer that @var{marker} points into, or
address@hidden if it points nowhere.
+
address@hidden
address@hidden
+(setq m (make-marker))
+     @result{} #<marker in no buffer>
address@hidden group
address@hidden
+(marker-position m)
+     @result{} nil
address@hidden group
address@hidden
+(marker-buffer m)
+     @result{} nil
address@hidden group
+
address@hidden
+(set-marker m 3770 (current-buffer))
+     @result{} #<marker at 3770 in markers.texi>
address@hidden group
address@hidden
+(marker-buffer m)
+     @result{} #<buffer markers.texi>
address@hidden group
address@hidden
+(marker-position m)
+     @result{} 3770
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden buffer-has-markers-at position
+This function returns @code{t} if one or more markers
+point at position @var{position} in the current buffer.
address@hidden defun
+
address@hidden Marker Insertion Types
address@hidden Marker Insertion Types
+
address@hidden insertion type of a marker
+  When you insert text directly at the place where a marker points,
+there are two possible ways to relocate that marker: it can point before
+the inserted text, or point after it.  You can specify which one a given
+marker should do by setting its @dfn{insertion type}.  Note that use of
address@hidden ignores markers' insertion types, always
+relocating a marker to point after the inserted text.
+
address@hidden set-marker-insertion-type marker type
+This function sets the insertion type of marker @var{marker} to
address@hidden  If @var{type} is @code{t}, @var{marker} will advance when
+text is inserted at its position.  If @var{type} is @code{nil},
address@hidden does not advance when text is inserted there.
address@hidden defun
+
address@hidden marker-insertion-type marker
+This function reports the current insertion type of @var{marker}.
address@hidden defun
+
+Most functions that create markers, without an argument allowing to
+specify the insertion type, create them with insertion type
address@hidden  Also, the mark has, by default, insertion type
address@hidden
+
address@hidden Moving Markers
address@hidden 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.
+
address@hidden 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.
+
+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.
+
+The value returned is @var{marker}.
+
address@hidden
address@hidden
+(setq m (point-marker))
+     @result{} #<marker at 4714 in markers.texi>
address@hidden group
address@hidden
+(set-marker m 55)
+     @result{} #<marker at 55 in markers.texi>
address@hidden group
address@hidden
+(setq b (get-buffer "foo"))
+     @result{} #<buffer foo>
address@hidden group
address@hidden
+(set-marker m 0 b)
+     @result{} #<marker at 1 in foo>
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden move-marker marker position &optional buffer
+This is another name for @code{set-marker}.
address@hidden defun
+
address@hidden The Mark
address@hidden The Mark
address@hidden mark, the
address@hidden mark ring
+
+  One special marker in each buffer is designated @dfn{the mark}.  It
+specifies a position to bound a range of text for commands such as
address@hidden and @code{indent-rigidly}.  Lisp programs should
+set the mark only to values that have a potential use to the user, and
+never for their own internal purposes.  For example, the
address@hidden command sets the mark to the value of point
+before doing any replacements, because this enables the user to move
+back there conveniently after the replace is finished.
+
+  Many commands are designed to operate on the text between point and
+the mark when called interactively.  If you are writing such a
+command, don't examine the mark directly; instead, use
address@hidden with the @samp{r} specification.  This provides the
+values of point and the mark as arguments to the command in an
+interactive call, but permits other Lisp programs to specify arguments
+explicitly.  @xref{Interactive Codes}.
+
+  Each buffer has a marker which represents the value of the mark in
+that buffer, independent of any other buffer.  When a buffer is newly
+created, this marker exists but does not point anywhere.  That means
+the mark ``doesn't exist'' in that buffer as yet.
+
+  Once the mark ``exists'' in a buffer, it normally never ceases to
+exist.  However, it may become @dfn{inactive}, if Transient Mark mode is
+enabled.  The variable @code{mark-active}, which is always buffer-local
+in all buffers, indicates whether the mark is active: address@hidden
+means yes.  A command can request deactivation of the mark upon return
+to the editor command loop by setting @code{deactivate-mark} to a
address@hidden value (but this causes deactivation only if Transient
+Mark mode is enabled).
+
+  The main motivation for using Transient Mark mode is that this mode
+also enables highlighting of the region when the mark is active.
address@hidden
+
+  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
+mark on the mark ring.  The variable @code{mark-ring-max} specifies the
+maximum number of entries in the mark ring; once the list becomes this
+long, adding a new element deletes the last element.
+
+  There is also a separate global mark ring, but that is used only in a
+few particular user-level commands, and is not relevant to Lisp
+programming.  So we do not describe it here.
+
address@hidden mark &optional force
address@hidden current buffer mark
+This function returns the current buffer's mark position as an integer,
+or @code{nil} if no mark has ever been set in this buffer.
+
+If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is
address@hidden, @code{mark} signals an error if the mark is inactive.
+However, if @var{force} is address@hidden, then @code{mark} disregards
+inactivity of the mark, and returns the mark position anyway (or
address@hidden).
address@hidden defun
+
address@hidden mark-marker
+This function returns the marker that represents the current buffer's
+mark.  It is not a copy, it is the marker used internally.  Therefore,
+changing this marker's position will directly affect the buffer's
+mark.  Don't do that unless that is the effect you want.
+
address@hidden
address@hidden
+(setq m (mark-marker))
+     @result{} #<marker at 3420 in markers.texi>
address@hidden group
address@hidden
+(set-marker m 100)
+     @result{} #<marker at 100 in markers.texi>
address@hidden group
address@hidden
+(mark-marker)
+     @result{} #<marker at 100 in markers.texi>
address@hidden group
address@hidden example
+
+Like any marker, this marker can be set to point at any buffer you
+like.  If you make it point at any buffer other than the one of which
+it is the mark, it will yield perfectly consistent, but rather odd,
+results.  We recommend that you not do it!
address@hidden defun
+
address@hidden
address@hidden Command set-mark-command jump
+If @var{jump} is @code{nil}, this command sets the mark to the value
+of point and pushes the previous value of the mark on the mark ring.  The
+message @samp{Mark set} is also displayed in the echo area.
+
+If @var{jump} is not @code{nil}, this command sets point to the value
+of the mark, and sets the mark to the previous saved mark value, which
+is popped off the mark ring.
+
+This function is @emph{only} intended for interactive use.
address@hidden deffn
address@hidden ignore
+
address@hidden set-mark position
+This function sets the mark to @var{position}, and activates the mark.
+The old value of the mark is @emph{not} pushed onto the mark ring.
+
address@hidden note:} Use this function only if you want the user to
+see that the mark has moved, and you want the previous mark position to
+be lost.  Normally, when a new mark is set, the old one should go on the
address@hidden  For this reason, most applications should use
address@hidden and @code{pop-mark}, not @code{set-mark}.
+
+Novice Emacs Lisp programmers often try to use the mark for the wrong
+purposes.  The mark saves a location for the user's convenience.  An
+editing command should not alter the mark unless altering the mark is
+part of the user-level functionality of the command.  (And, in that
+case, this effect should be documented.)  To remember a location for
+internal use in the Lisp program, store it in a Lisp variable.  For
+example:
+
address@hidden
address@hidden
+(let ((beg (point)))
+  (forward-line 1)
+  (delete-region beg (point))).
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden for interactive use only
address@hidden
address@hidden Command exchange-point-and-mark
+This function exchanges the positions of point and the mark.
+It is intended for interactive use.
address@hidden deffn
address@hidden ignore
+
address@hidden push-mark &optional position nomsg activate
+This function sets the current buffer's mark to @var{position}, and
+pushes a copy of the previous mark onto @code{mark-ring}.  If
address@hidden is @code{nil}, then the value of point is used.
address@hidden 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}.
+
+A @samp{Mark set} message is displayed unless @var{nomsg} is
address@hidden
address@hidden defun
+
address@hidden pop-mark
+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.
address@hidden defun
+
address@hidden transient-mark-mode
address@hidden  @cindex Transient Mark mode  Redundant
+This variable if address@hidden enables Transient Mark mode, in which
+every buffer-modifying primitive sets @code{deactivate-mark}.  The
+consequence of this is that commands that modify the buffer normally
+make the mark inactive.
+
+Lisp programs can set @code{transient-mark-mode} to @code{only} to
+enable Transient Mark mode for the following command only.  During
+that following command, the value of @code{transient-mark-mode} is
address@hidden  If it is still @code{identity} at the end of the
+command, it changes to @code{nil}.
address@hidden defopt
+
address@hidden mark-even-if-inactive
+If this is address@hidden, Lisp programs and the Emacs user can use the
+mark even when it is inactive.  This option affects the behavior of
+Transient Mark mode.  When the option is address@hidden, deactivation of
+the mark turns off region highlighting, but commands that use the mark
+behave as if the mark were still active.
address@hidden defopt
+
address@hidden deactivate-mark
+If an editor command sets this variable address@hidden, then the editor
+command loop deactivates the mark after the command returns (if
+Transient Mark mode is enabled).  All the primitives that change the
+buffer set @code{deactivate-mark}, to deactivate the mark when the
+command is finished.
+
+To write Lisp code that modifies the buffer without causing
+deactivation of the mark at the end of the command, bind
address@hidden to @code{nil} around the code that does the
+modification.  For example:
+
address@hidden
+(let (deactivate-mark)
+  (insert " "))
address@hidden example
address@hidden defvar
+
address@hidden deactivate-mark
+This function deactivates the mark, if Transient Mark mode is enabled.
+Otherwise it does nothing.
address@hidden defun
+
address@hidden mark-active
+The mark is active when this variable is address@hidden  This variable
+is always buffer-local in each buffer.
address@hidden defvar
+
address@hidden activate-mark-hook
address@hidden 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.
address@hidden defvar
+
address@hidden mark-ring
+The value of this buffer-local variable is the list of saved former
+marks of the current buffer, most recent first.
+
address@hidden
address@hidden
+mark-ring
address@hidden (#<marker at 11050 in markers.texi>
+    #<marker at 10832 in markers.texi>
+    @dots{})
address@hidden group
address@hidden example
address@hidden defvar
+
address@hidden mark-ring-max
+The value of this variable is the maximum size of @code{mark-ring}.  If
+more marks than this are pushed onto the @code{mark-ring},
address@hidden discards an old mark when it adds a new one.
address@hidden defopt
+
address@hidden The Region
address@hidden The Region
address@hidden region (between point and mark)
+
+  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
+only those functions specifically related to the region itself are
+described here.
+
+The next two functions signal an error if the mark does not point
+anywhere.  If Transient Mark mode is enabled and
address@hidden is @code{nil}, they also signal an error
+if the mark is inactive.
+
address@hidden region-beginning
+This function returns the position of the beginning of the region (as
+an integer).  This is the position of either point or the mark,
+whichever is smaller.
address@hidden defun
+
address@hidden region-end
+This function returns the position of the end of the region (as an
+integer).  This is the position of either point or the mark, whichever is
+larger.
address@hidden defun
+
+  Few programs need to use the @code{region-beginning} and
address@hidden 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}.)
+
address@hidden
+   arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299
address@hidden ignore