Initial revision

1 files changed, 574 insertions, 0 deletions

diff --git a/lispref/markers.texi b/lispref/markers.texi
new file mode 100644
index 00000000000..1e7ceebe7df
--- /dev/null
+++ b/lispref/markers.texi
@@ -0,0 +1,574 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/markers
+@node Markers, Text, Positions, Top
+@chapter Markers
+@cindex 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.
+
+@menu
+* 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.
+* Changing 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''.
+@end menu
+
+@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 require one,
+just as an integer could be used.  @xref{Positions}, for a complete
+description of positions.
+
+  A marker has two attributes: the marker position, and the marker
+buffer.  The marker position is an integer which 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.
+
+@cindex 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 in front of
+the new text---unless it is inserted with @code{insert-before-markers}
+(@pxref{Insertion}).
+
+@cindex 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.
+
+@cindex markers as numbers
+  Because it is common to perform arithmetic operations on a marker
+position, most of the arithmetic operations (including @code{+} and
+@code{-}) 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:
+
+@example
+@group
+;; @r{Make a new marker that initially does not point anywhere:}
+(setq m1 (make-marker))
+     @result{} #<marker in no buffer>
+@end group
+
+@group
+;; @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>
+@end group
+
+@group
+;; @r{Now insert one character at the beginning of the buffer:}
+(goto-char (point-min))
+     @result{} 1
+(insert "Q")
+     @result{} nil
+@end group
+
+@group
+;; @r{@code{m1} is updated appropriately.}
+m1
+     @result{} #<marker at 101 in markers.texi>
+@end group
+
+@group
+;; @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
+@end group
+
+@group
+;; @r{When you are finished using a marker, make it point nowhere.}
+(set-marker m1 nil)
+     @result{} #<marker in no buffer>
+@end group
+@end example
+
+@node Predicates on Markers
+@section 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.
+
+@defun 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.
+@end defun
+
+@defun integer-or-marker-p object
+This function returns @code{t} if @var{object} is an integer or a marker,
+@code{nil} otherwise.
+@end defun
+
+@defun number-or-marker-p object
+This function returns @code{t} if @var{object} is a number (either kind)
+or a marker, @code{nil} otherwise.
+@end defun
+
+@node Creating Markers
+@section 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.
+
+@defun make-marker
+This functions returns a newly allocated marker that does not point
+anywhere.
+
+@example
+@group
+(make-marker)
+     @result{} #<marker in no buffer>
+@end group
+@end example
+@end defun
+
+@defun 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
+@code{copy-marker}, below.
+@end defun
+
+@defun 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}.
+@end defun
+
+@defun point-max-marker
+@cindex end of buffer 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.
+
+@example
+@group
+(point-min-marker)
+     @result{} #<marker at 1 in markers.texi>
+(point-max-marker)
+     @result{} #<marker at 15573 in markers.texi>
+@end group
+
+@group
+(narrow-to-region 100 200)
+     @result{} nil
+@end group
+@group
+(point-min-marker)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+@group
+(point-max-marker)
+     @result{} #<marker at 200 in markers.texi>
+@end group
+@end example
+@end defun
+
+@defun copy-marker marker-or-integer
+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,
+@code{copy-marker} returns a new marker that points to position
+@var{marker-or-integer} in the current buffer.
+
+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.
+
+An error is signaled if @var{marker} is neither a marker nor an
+integer.
+
+@example
+@group
+(setq p (point-marker))
+     @result{} #<marker at 2139 in markers.texi>
+@end group
+
+@group
+(setq q (copy-marker p))
+     @result{} #<marker at 2139 in markers.texi>
+@end group
+
+@group
+(eq p q)
+     @result{} nil
+@end group
+
+@group
+(equal p q)
+     @result{} t
+@end group
+
+@group
+(copy-marker 0)
+     @result{} #<marker at 1 in markers.texi>
+@end group
+
+@group
+(copy-marker 20000)
+     @result{} #<marker at 7572 in markers.texi>
+@end group
+@end example
+@end defun
+
+@node Information from Markers
+@section Information from Markers
+
+  This section describes the functions for accessing the components of a
+marker object.
+
+@defun marker-position marker
+This function returns the position that @var{marker} points to, or
+@code{nil} if it points nowhere.
+@end defun
+
+@defun marker-buffer marker
+This function returns the buffer that @var{marker} points into, or
+@code{nil} if it points nowhere.
+
+@example
+@group
+(setq m (make-marker))
+     @result{} #<marker in no buffer>
+@end group
+@group
+(marker-position m)
+     @result{} nil
+@end group
+@group
+(marker-buffer m)
+     @result{} nil
+@end group
+
+@group
+(set-marker m 3770 (current-buffer))
+     @result{} #<marker at 3770 in markers.texi>
+@end group
+@group
+(marker-buffer m)
+     @result{} #<buffer markers.texi>
+@end group
+@group
+(marker-position m)
+     @result{} 3770
+@end group
+@end example
+@end defun
+
+  Two distinct markers are considered @code{equal} (even though not
+@code{eq}) to each other if they have the same position and buffer, or
+if they both point nowhere.
+
+@node Changing Markers
+@section Changing 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.
+
+@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.
+
+If @var{position} is less than 1, @code{set-marker} moves @var{marker}
+to the beginning of the buffer.  If the value of @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}.
+
+@example
+@group
+(setq m (point-marker))
+     @result{} #<marker at 4714 in markers.texi>
+@end group
+@group
+(set-marker m 55)
+     @result{} #<marker at 55 in markers.texi>
+@end group
+@group
+(setq b (get-buffer "foo"))
+     @result{} #<buffer foo>
+@end group
+@group
+(set-marker m 0 b)
+     @result{} #<marker at 1 in foo>
+@end group
+@end example
+@end defun
+
+@defun move-marker marker position &optional buffer
+This is another name for @code{set-marker}.
+@end defun
+
+@node The Mark
+@section The Mark
+@cindex mark, the
+@cindex mark ring
+
+  One special marker in each buffer is designated @dfn{the mark}.  It
+records a position for the user for the sake of commands such as
+@kbd{C-w} and @kbd{C-x @key{TAB}}.  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 @code{replace-regexp}
+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 so that when called interactively they
+operate on the text between point and the mark.  If you are writing such
+a command, don't examine the mark directly; instead, use
+@code{interactive} 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 its own value of the mark that is independent of the
+value of the mark in other buffers.  When a buffer is created, the mark
+exists but does not point anywhere.  We consider this state as ``the
+absence of a mark in that buffer''.
+
+  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 local in all
+buffers, indicates whether the mark is active: non-@code{nil} means
+yes.  A command can request deactivation of the mark upon return to the
+editor command loop by setting @code{deactivate-mark} to a
+non-@code{nil} value (but this deactivation only follows 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.
+@xref{Display}.
+
+  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.
+
+@defun mark &optional force
+@cindex current buffer mark
+This function returns the current buffer's mark position as an integer.
+
+If the mark is inactive, @code{mark} normally signals an error.
+However, if @var{force} is non-@code{nil}, then @code{mark} returns the
+mark position anyway---or @code{nil}, if the mark is not yet set for
+this buffer.
+@end defun
+
+@defun mark-marker
+This function returns the current buffer's mark.  This is the very marker
+which records the mark location inside Emacs, not a copy.  Therefore,
+changing this marker's position will directly affect the position of the mark.
+Don't do it unless that is the effect you want.
+
+@example
+@group
+(setq m (mark-marker))
+     @result{} #<marker at 3420 in markers.texi>
+@end group
+@group
+(set-marker m 100)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+@group
+(mark-marker)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+@end example
+
+Like any marker, this marker can be set to point at any buffer you like.
+We don't recommend that you make it point at any buffer other than the
+one of which it is the mark.  If you do, it will yield perfectly
+consistent, but rather odd, results.
+@end defun
+
+@ignore
+@deffn 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.
+@end deffn
+@end ignore
+
+@defun 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.
+
+@strong{Please 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
+@code{mark-ring}.  For this reason, most applications should use
+@code{push-mark} 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:
+
+@example
+@group
+(let ((beg (point)))
+  (forward-line 1)
+  (delete-region beg (point))).
+@end group
+@end example
+@end defun
+
+@c for interactive use only
+@ignore
+@deffn Command exchange-point-and-mark
+This function exchanges the positions of point and the mark.
+It is intended for interactive use.
+@end deffn
+@end ignore
+
+@defun 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
+@var{position} is @code{nil}, then the value of point is used.
+@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}.
+
+A @samp{Mark set} message is displayed unless @var{nomsg} is
+non-@code{nil}.
+@end defun
+
+@defun 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.
+@end defun
+
+@defopt transient-mark-mode
+@cindex Transient Mark mode
+This variable 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.
+@end defopt
+
+@defvar deactivate-mark
+If an editor command sets this variable non-@code{nil}, then the editor
+command loop deactivates the mark after the command returns.
+@end defvar
+
+@defvar mark-active
+The mark is active when this variable is non-@code{nil}.  This variable
+is always local in each buffer.
+@end defvar
+
+@defvar activate-mark-hook
+@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 the region may
+have changed.
+@end defvar
+
+@defvar mark-ring
+The value of this buffer-local variable is the list of saved former
+marks of the current buffer, most recent first.
+
+@example
+@group
+mark-ring
+@result{} (#<marker at 11050 in markers.texi> 
+    #<marker at 10832 in markers.texi>
+    @dots{})
+@end group
+@end example
+@end defvar
+
+@defopt 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},
+@code{push-mark} discards an old mark when it adds a new one.
+@end defopt
+
+@node The Region
+@section The Region
+@cindex region, the
+
+  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.
+
+@defun 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.
+
+If the mark does not point anywhere, an error is signaled.
+@end defun
+
+@defun 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.
+
+If the mark does not point anywhere, an error is signaled.
+@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}.)