Commit 29679a81 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

*** empty log message ***

parent db07847f
......@@ -31,7 +31,7 @@ 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
buffer. 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
......@@ -141,7 +141,7 @@ 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
This functions returns a newly created marker that does not point
anywhere.
@example
......@@ -309,10 +309,10 @@ 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.
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}.
......@@ -365,16 +365,15 @@ 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''.
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).
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 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.
......@@ -399,7 +398,7 @@ this buffer.
@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,
that 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.
......@@ -505,9 +504,15 @@ inactive.
@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.
command loop deactivates the mark after the command returns, but only if
Transient Mark mode is enabled.
@end defvar
@defun deactivate-mark
This function deactivates the mark, but only if Transient Mark mode
is enabled.
@end defun
@defvar mark-active
The mark is active when this variable is non-@code{nil}. This variable
is always local in each buffer.
......
......@@ -7,15 +7,15 @@
@chapter Positions
@cindex position (in buffer)
A @dfn{position} is the index of a character in the text of buffer.
A @dfn{position} is the index of a character in the text of a buffer.
More precisely, a position identifies the place between two characters
(or before the first character, or after the last character), so we can
speak of the character before or after a given position. However, the
we often speak of the character ``at'' a position, meaning the character
speak of the character before or after a given position. However, we
often speak of the character ``at'' a position, meaning the character
after that position.
Positions are usually represented as integers starting from 1, but can
also be represented as @dfn{markers}---special objects which relocate
also be represented as @dfn{markers}---special objects that relocate
automatically when text is inserted or deleted so they stay with the
surrounding characters. @xref{Markers}.
......@@ -58,7 +58,7 @@ details.
@defun point
@cindex current buffer position
This function returns the position of point in the current buffer,
This function returns the value of point in the current buffer,
as an integer.
@need 700
......@@ -71,26 +71,26 @@ as an integer.
@end defun
@defun point-min
This function returns the minimum accessible value of point in the
current buffer. This is 1, unless narrowing is in effect, in
which case it is the position of the start of the region that you
narrowed to. (@xref{Narrowing}.)
This function returns the minimum accessible value of point in the
current buffer. This is normally 1, but if narrowing is in effect, it
is the position of the start of the region that you narrowed to.
(@xref{Narrowing}.)
@end defun
@defun point-max
This function returns the maximum accessible value of point in the
This function returns the maximum accessible value of point in the
current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is
in effect, in which case it is the position of the end of the region
that you narrowed to. (@xref{Narrowing}).
@end defun
@defun buffer-end flag
This function returns @code{(point-min)} if @var{flag} is less than 1,
This function returns @code{(point-min)} if @var{flag} is less than 1,
@code{(point-max)} otherwise. The argument @var{flag} must be a number.
@end defun
@defun buffer-size
This function returns the total number of characters in the current
This function returns the total number of characters in the current
buffer. In the absence of any narrowing (@pxref{Narrowing}),
@code{point-max} returns a value one larger than this.
......@@ -129,7 +129,7 @@ or relative to the edges of the selected window. @xref{Point}.
@subsection Motion by Characters
These functions move point based on a count of characters.
@code{goto-char} is the fundamental primitive; the functions others use
@code{goto-char} is the fundamental primitive; the other functions use
that.
@deffn Command goto-char position
......@@ -192,14 +192,14 @@ argument.
@end deffn
@deffn Command backward-word count
This function just like @code{forward-word}, except that it moves
This function is just like @code{forward-word}, except that it moves
backward until encountering the front of a word, rather than forward.
In an interactive call, @var{count} is set to the numeric prefix
argument.
This function is rarely used in programs, as it is more efficient to
call @code{forward-word} with negative argument.
call @code{forward-word} with a negative argument.
@end deffn
@defvar words-include-escapes
......@@ -230,7 +230,7 @@ Likewise, to move to the end of the buffer, use:
@end group
@end example
Here are two commands which users use to do these things. They are
Here are two commands that users use to do these things. They are
documented here to warn you not to use them in Lisp programs, because
they set the mark and display messages in the echo area.
......@@ -250,7 +250,7 @@ Don't use this function in Lisp programs!
This function moves point to the end of the buffer (or the limits of
the accessible portion, when narrowing is in effect), setting the mark
at the previous position. If @var{n} is non-@code{nil}, then it puts
point @var{n} tenths of the way from the end.
point @var{n} tenths of the way from the end of the buffer.
In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.
......@@ -272,10 +272,12 @@ control characters are displayed.
@deffn Command goto-line line
This function moves point to the front of the @var{line}th line,
counting from line 1 at beginning of buffer. If @var{line} is less than
1, it moves point to the beginning of the buffer. If @var{line} is
counting from line 1 at beginning of the buffer. If @var{line} is less
than 1, it moves point to the beginning of the buffer. If @var{line} is
greater than the number of lines in the buffer, it moves point to the
@emph{end of the last line} of the buffer.
end of the buffer---that is, the @emph{end of the last line} of the
buffer. This is the only case in which @code{goto-line} does not
necessarily move to the beginning of a line.
If narrowing is in effect, then @var{line} still counts from the
beginning of the buffer, but point cannot go outside the accessible
......@@ -285,8 +287,10 @@ position.
The return value of @code{goto-line} is the difference between
@var{line} and the line number of the line to which point actually was
able move (in the full buffer, disregarding any narrowing). Thus, the
value is positive if the scan encounters the real end of the buffer.
able to move (in the full buffer, before taking account of narrowing).
Thus, the value is positive if the scan encounters the real end of the
buffer. The value is zero if scan encounters the end of the accessible
portion but not the real end of the buffer.
In an interactive call, @var{line} is the numeric prefix argument if
one has been provided. Otherwise @var{line} is read in the minibuffer.
......@@ -298,8 +302,8 @@ argument @var{count} not @code{nil} or 1, it moves forward
@var{count}@minus{}1 lines and then to the beginning of the line.
If this function reaches the end of the buffer (or of the accessible
portion, if narrowing is in effect), it positions point at the end of
the buffer. No error is signaled.
portion, if narrowing is in effect), it positions point there. No error
is signaled.
@end deffn
@deffn Command end-of-line &optional count
......@@ -308,15 +312,17 @@ argument @var{count} not @code{nil} or 1, it moves forward
@var{count}@minus{}1 lines and then to the end of the line.
If this function reaches the end of the buffer (or of the accessible
portion, if narrowing is in effect), it positions point at the end of
the buffer. No error is signaled.
portion, if narrowing is in effect), it positions point there. No error
is signaled.
@end deffn
@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 the line.
@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 @code{forward-line} encounters the beginning or end of the buffer (or
of the accessible portion) before finding that many lines, it sets point
......@@ -435,7 +441,7 @@ continued onto additional screen lines. In these cases,
@code{vertical-motion} moves point much like @code{forward-line}.
@xref{Truncation}.
Because the width of a given string depends on the flags which control
Because the width of a given string depends on the flags that control
the appearance of certain characters, @code{vertical-motion} behaves
differently, for a given piece of text, depending on the buffer it is
in, and even on the selected window (because the width, the truncation
......@@ -462,28 +468,28 @@ This function moves point with respect to the text currently displayed
in the selected window. It moves point to the beginning of the screen
line @var{count} screen lines from the top of the window. If
@var{count} is negative, that specifies a position
@w{@minus{}@var{count}} lines from the bottom---or else the last line of
the buffer, if the buffer ends above the specified screen position.
@w{@minus{}@var{count}} lines from the bottom (or the last line of the
buffer, if the buffer ends above the specified screen position).
If @var{count} is @code{nil}, then point moves to the beginning of the
line in the middle of the window. If the absolute value of @var{count}
is greater than the size of the window, then point moves to the place
which would appear on that screen line if the window were tall enough.
that would appear on that screen line if the window were tall enough.
This will probably cause the next redisplay to scroll to bring that
location onto the screen.
In an interactive call, @var{count} is the numeric prefix argument.
The value returned is the window line number, with the top line in the
window numbered 0.
The value returned is the window line number point has moved to, with
the top line in the window numbered 0.
@end deffn
@defun compute-motion from frompos to topos width offsets window
This function scan through the current buffer, calculating screen
position. It scans the current buffer forward from position @var{from},
assuming that is at screen coordinates @var{frompos}, to position
@var{to} or coordinates @var{topos}, whichever comes first. It returns
the ending buffer position and screen coordinates.
This function scans the current buffer, calculating screen positions.
It scans the buffer forward from position @var{from}, assuming that is
at screen coordinates @var{frompos}, to position @var{to} or coordinates
@var{topos}, whichever comes first. It returns the ending buffer
position and screen coordinates.
The coordinate arguments @var{frompos} and @var{topos} are cons cells of
the form @code{(@var{hpos} . @var{vpos})}.
......@@ -501,9 +507,9 @@ column numbers in the buffer. This can be nonzero in a continuation
line, when the previous screen lines' widths do not add up to a multiple
of @code{tab-width}. It is always zero in a non-continuation line.
The window @var{window} serves to specify which display table to use;
that is its only effect. @code{compute-motion} always operates on the
current buffer, regardless of what buffer is displayed in @var{window}.
The window @var{window} serves only to specify which display table to
use. @code{compute-motion} always operates on the current buffer,
regardless of what buffer is displayed in @var{window}.
The return value is a list of five elements:
......@@ -513,27 +519,29 @@ The return value is a list of five elements:
@noindent
Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
is the vertical position, and @var{hpos} is the horizontal position.
is the vertical screen position, and @var{hpos} is the horizontal screen
position.
The result @var{prevhpos} is the horizontal position one character back
from @var{pos}. The result @var{contin} is @code{t} if a line was
continued after (or within) the previous character.
from @var{pos}. The result @var{contin} is @code{t} if the last line
was continued after (or within) the previous character.
For example, to find the buffer position of column @var{col} of line
@var{line} of a certain window, pass the window's display start location
as @var{from} and the window's upper-left coordinates as @var{frompos}.
Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
the end of the visible section of the buffer, and pass @var{line} and
the end of the accessible portion of the buffer, and pass @var{line} and
@var{col} as @var{topos}. Here's a function that does this:
@example
(defun coordinates-of-position (col line)
(car (compute-motion (window-start)
'(0 . 0)
(point)
(point-max)
(cons col line)
(window-width)
(cons (window-hscroll) 0))))
(cons (window-hscroll) 0)
(selected-window))))
@end example
When you use @code{compute-motion} for the minibuffer, you need to use
......@@ -575,9 +583,10 @@ a vertical motion command.
This variable controls how the vertical line motion commands operate
when starting at the end of a line. If @code{track-eol} is
non-@code{nil}, then vertical motion starting at the end of a line will
keep to the ends of lines. This means moving to the end of each line
moved onto. The value of @code{track-eol} has no effect if point is not
at the end of a line when the first vertical motion command is given.
keep to the ends of lines (instead of keeping to a particular column).
This means moving to the end of each line moved onto. The value of
@code{track-eol} has no effect if point is not at the end of a line when
the first vertical motion command is given.
@code{track-eol} has its effect by telling line motion commands to set
@code{temporary-goal-column} to 9999 instead of to the current column.
......@@ -616,9 +625,9 @@ A negative argument means move backward but still to a less deep spot.
@end deffn
@deffn Command down-list arg
This function moves forward down @var{arg} levels of parentheses. A
negative argument means move backward but still go down @var{arg}
levels.
This function moves forward into @var{arg} levels of parentheses. A
negative argument means move backward but still go @var{arg} levels
deeper in parentheses.
@end deffn
@deffn Command forward-sexp arg
......@@ -655,17 +664,17 @@ to the beginning of a defun, not to the end of one.
@end deffn
@deffn Command end-of-defun arg
Move forward to the @var{arg}th end of a defun. If @var{arg} is
negative, this actually moves backward, but it still moves to the end of
a defun, not to the beginning of one.
This function moves forward to the @var{arg}th end of a defun. If
@var{arg} is negative, this actually moves backward, but it still moves
to the end of a defun, not to the beginning of one.
@end deffn
@defopt defun-prompt-regexp
If non-@code{nil}, this variable holds a regular expression that
specifies what text can appear before the open-parenthesis that starts a
defun. That is to say, the a defun begins on a line which starts
with a match for this regular expression, followed by a character
with open-parenthesis syntax.
defun. That is to say, a defun begins on a line that starts with a
match for this regular expression, followed by a character with
open-parenthesis syntax.
@end defopt
@node Skipping Characters
......@@ -746,10 +755,10 @@ Configurations}).
@cindex point excursion
@cindex current buffer excursion
The @code{save-excursion} special form saves the identity of the current
buffer and the values of point and the mark in it, evaluates @var{forms},
and finally restores the buffer and its saved values of point and the mark.
All three saved values are restored even in case of an abnormal exit
via throw or error (@pxref{Nonlocal Exits}).
buffer and the values of point and the mark in it, evaluates
@var{forms}, and finally restores the buffer and its saved values of
point and the mark. All three saved values are restored even in case of
an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
The @code{save-excursion} special form is the standard way to switch
buffers or move point within one part of a program and avoid affecting
......@@ -805,12 +814,12 @@ beginning and end of the buffer. While narrowing is in effect, no text
outside the accessible portion is displayed, and point cannot move
outside the accessible portion.
Values such as positions or line numbers, that usually count from the
Values such as positions or line numbers, which usually count from the
beginning of the buffer, do so despite narrowing, but the functions
which use them refuse to operate on text that is inaccessible.
The commands for saving buffers are unaffected by narrowing; they save
the entire buffer regardless of the any narrowing.
the entire buffer regardless of any narrowing.
@deffn Command narrow-to-region start end
This function sets the accessible portion of the current buffer to start
......@@ -849,8 +858,8 @@ This special form saves the current bounds of the accessible portion,
evaluates the @var{body} forms, and finally restores the saved bounds,
thus restoring the same state of narrowing (or absence thereof) formerly
in effect. The state of narrowing is restored even in the event of an
abnormal exit via throw or error (@pxref{Nonlocal Exits}). Therefore,
this construct is a clean way to narrow a buffer temporarily.
abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
Therefore, this construct is a clean way to narrow a buffer temporarily.
The value returned by @code{save-restriction} is that returned by the
last form in @var{body}, or @code{nil} if no body forms were given.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment