-@c -*-texinfo-*-
+@c -*- mode: texinfo; coding: utf-8 -*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2016 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Positions
@chapter Positions
normally ignore which buffer the marker points into; they convert the
marker to an integer, and use that integer, exactly as if you had
passed the integer as the argument, even if the marker points to the
-``wrong'' buffer. A marker that points nowhere cannot convert to an
+wrong buffer. A marker that points nowhere cannot convert to an
integer; using it instead of an integer causes an error.
@xref{Markers}.
- See also the ``field'' feature (@pxref{Fields}), which provides
+ See also the field feature (@pxref{Fields}), which provides
functions that are used by many cursor-motion commands.
@menu
@node Word Motion
@subsection Motion by Words
- These functions for parsing words use the syntax table to decide
-whether a given character is part of a word. @xref{Syntax Tables}.
+ The functions for parsing words described below use the syntax table
+to decide whether a given character is part of a word. @xref{Syntax
+Tables}.
@deffn Command forward-word &optional count
This function moves point forward @var{count} words (or backward if
@var{count} is negative). If @var{count} is omitted or @code{nil}, it
-defaults to 1.
+defaults to 1. In an interactive call, @var{count} is specified by
+the numeric prefix argument.
``Moving one word'' means moving until point crosses a
-word-constituent character and then encounters a word-separator
-character. However, this function cannot move point past the boundary
-of the accessible portion of the buffer, or across a field boundary
+word-constituent character, which indicates the beginning of a word,
+and then continue moving until the word ends. By default, characters
+that begin and end words, known as @dfn{word boundaries}, are defined
+by the current buffer's syntax table (@pxref{Syntax Class Table}), but
+modes can override that by setting up a suitable
+@code{find-word-boundary-function-table}, described below. In any
+case, this function cannot move point past the boundary of the
+accessible portion of the buffer, or across a field boundary
(@pxref{Fields}). The most common case of a field boundary is the end
of the prompt in the minibuffer.
If @code{inhibit-field-text-motion} is non-@code{nil},
this function ignores field boundaries.
-In an interactive call, @var{count} is specified by the numeric prefix
-argument.
@end deffn
@deffn Command backward-word &optional count
@defopt words-include-escapes
@c Emacs 19 feature
-This variable affects the behavior of @code{forward-word} and everything
-that uses it. If it is non-@code{nil}, then characters in the
-``escape'' and ``character quote'' syntax classes count as part of
-words. Otherwise, they do not.
+This variable affects the behavior of @code{forward-word} and
+@code{backward-word}, and everything that uses them. If it is
+non-@code{nil}, then characters in the escape and character-quote
+syntax classes count as part of words. Otherwise, they do not.
@end defopt
@defvar inhibit-field-text-motion
@code{forward-paragraph} ignore field boundaries.
@end defvar
+@defvar find-word-boundary-function-table
+This variable affects the behavior of @code{forward-word} and
+@code{backward-word}, and everything that uses them. Its value is a
+char-table (@pxref{Char-Tables}) of functions to search for word
+boundaries. If a character has a non-@code{nil} entry in this table,
+then when a word starts or ends with that character, the corresponding
+function will be called with 2 arguments: @var{pos} and @var{limit}.
+The function should return the position of the other word boundary.
+Specifically, if @var{pos} is smaller than @var{limit}, then @var{pos}
+is at the beginning of a word, and the function should return the
+position after the last character of the word; otherwise, @var{pos} is
+at the last character of a word, and the function should return the
+position of that word's first character.
+@end defvar
+
+@defun forward-word-strictly &optional count
+This function is like @code{forward-word}, but it is not affected by
+@code{find-word-boundary-function-table}. Lisp programs that should
+not change behavior when word movement is modified by modes which set
+that table, such as @code{subword-mode}, should use this function
+instead of @code{forward-word}.
+@end defun
+
+@defun backward-word-strictly &optional count
+This function is like @code{backward-word}, but it is not affected by
+@code{find-word-boundary-function-table}. Like with
+@code{forward-word-strictly}, use this function instead of
+@code{backward-word} when movement by words should only consider
+syntax tables.
+@end defun
+
@node Buffer End Motion
@subsection Motion to an End of the Buffer
@cindex move to beginning or end of buffer
@deffn Command forward-line &optional count
@cindex beginning of line
This function moves point forward @var{count} lines, to the beginning of
-the line. If @var{count} is negative, it moves point
-@minus{}@var{count} lines backward, to the beginning of a line. If
-@var{count} is zero, it moves point to the beginning of the current
-line. If @var{count} is @code{nil}, that means 1.
+the line following that. If @var{count} is negative, it moves point
+@minus{}@var{count} lines backward, to the beginning of a line
+preceding that. If @var{count} is zero, it moves point to the
+beginning of the current line. If @var{count} is @code{nil}, that
+means 1.
If @code{forward-line} encounters the beginning or end of the buffer (or
of the accessible portion) before finding that many lines, it sets point
@code{forward-line} returns the difference between @var{count} and the
number of lines actually moved. If you attempt to move down five lines
from the beginning of a buffer that has only three lines, point stops at
-the end of the last line, and the value will be 2.
+the end of the last line, and the value will be 2. As an explicit
+exception, if the last accessible line is non-empty, but has no
+newline (e.g., if the buffer ends without a newline), the function
+sets point to the end of that line, and the value returned by the
+function counts that line as one line successfully moved.
In an interactive call, @var{count} is the numeric prefix argument.
@end deffn
@deffn Command previous-line count
@cindex goal column
This function moves point up @var{count} lines (down if @var{count}
-is negative). In moving, it attempts to keep point in the ``goal column''
+is negative). In moving, it attempts to keep point in the @dfn{goal column}
(normally the same column that it was at the beginning of the move).
If there is no character in the target line exactly under the current
@deffn Command next-line count
This function moves point down @var{count} lines (up if @var{count}
-is negative). In moving, it attempts to keep point in the ``goal column''
+is negative). In moving, it attempts to keep point in the goal column
(normally the same column that it was at the beginning of the move).
If there is no character in the target line exactly under the current
the top line in the window numbered 0.
@end deffn
+@vindex move-to-window-group-line-function
+@defun move-to-window-group-line count
+This function is like @code{move-to-window-line}, except that when the
+selected window is a part of a group of windows (@pxref{Window
+Group}), @code{move-to-window-group-line} will move to a position with
+respect to the entire group, not just the single window. This
+condition holds when the buffer local variable
+@code{move-to-window-group-line-function} is set to a function. In
+this case, @code{move-to-window-group-line} calls the function with
+the argument @var{count}, then returns its result.
+@end defun
+
@defun compute-motion from frompos to topos width offsets window
This function scans the current buffer, calculating screen positions.
It scans the buffer forward from position @var{from}, assuming that is
@section Excursions
@cindex excursion
- It is often useful to move point ``temporarily'' within a localized
+ It is often useful to move point temporarily within a localized
portion of the program. This is called an @dfn{excursion}, and it is
done with the @code{save-excursion} special form. This construct
remembers the initial identity of the current buffer, and its value
Configurations} and in @ref{Frame Configurations}. @c frameset?
@defspec save-excursion body@dots{}
-@cindex mark excursion
@cindex point excursion
This special form saves the identity of the current buffer and the
value of point in it, evaluates @var{body}, and finally
-restores the buffer and its saved value of point. both saved values are
+restores the buffer and its saved value of point. Both saved values are
restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
during an excursion:
@example
-Warning: Use `with-current-buffer' rather than
+Warning: Use ‘with-current-buffer’ rather than
save-excursion+set-buffer
@end example