summaryrefslogtreecommitdiff
path: root/lispref
diff options
context:
space:
mode:
authorRichard M. Stallman <rms@gnu.org>1994-08-03 00:12:07 +0000
committerRichard M. Stallman <rms@gnu.org>1994-08-03 00:12:07 +0000
commit39ca484cf3024b8257f4d6fa72cb40113954eb55 (patch)
tree275cf67999a69875e884f098a4c1e7a459c6904f /lispref
parentb48a944c2f46fe59405ee50b9d6c86ff59f33669 (diff)
downloademacs-39ca484cf3024b8257f4d6fa72cb40113954eb55.tar.gz
*** empty log message ***
Diffstat (limited to 'lispref')
-rw-r--r--lispref/frames.texi45
-rw-r--r--lispref/searching.texi73
-rw-r--r--lispref/text.texi284
3 files changed, 208 insertions, 194 deletions
diff --git a/lispref/frames.texi b/lispref/frames.texi
index 778ef637261..b12b8aa70a0 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -9,7 +9,7 @@
A @var{frame} is a rectangle on the screen that contains one or more
Emacs windows. A frame initially contains a single main window (plus
-perhaps a minibuffer window) which you can subdivide vertically or
+perhaps a minibuffer window), which you can subdivide vertically or
horizontally into smaller windows.
@cindex terminal frame
@@ -66,7 +66,7 @@ variable @code{default-frame-alist}; parameters not specified there
either default from the standard X defaults file and X resources.
The set of possible parameters depends in principle on what kind of
-window system Emacs uses to display its the frames. @xref{X Frame
+window system Emacs uses to display its frames. @xref{X Frame
Parameters}, for documentation of individual parameters you can specify
when creating an X window frame.
@end defun
@@ -251,11 +251,11 @@ The type of icon to use for this frame when it is iconified.
Non-@code{nil} specifies a bitmap icon, @code{nil} a text icon.
@item foreground-color
-The color to use for the inside of a character. This is a string; the X
+The color to use for the image of a character. This is a string; the X
server defines the meaningful color names.
@item background-color
-The color to use for the background of text.
+The color to use for the background of characters.
@item mouse-color
The color for the mouse pointer.
@@ -303,7 +303,7 @@ it and see if it works.)
@subsection Frame Size And Position
You can read or change the size and position of a frame using the
-frame parameters @code{left}, @code{top}, @code{height} and
+frame parameters @code{left}, @code{top}, @code{height}, and
@code{width}. Whatever geometry parameters you don't specify are chosen
by the window manager in its usual fashion.
@@ -311,7 +311,7 @@ by the window manager in its usual fashion.
@defun set-frame-position frame left top
This function sets the position of the top left corner of
-@var{frame}---to @var{left} and @var{top}. These arguments are measured
+@var{frame} to @var{left} and @var{top}. These arguments are measured
in pixels, counting from the top left corner of the screen.
@end defun
@@ -330,10 +330,10 @@ pixels. If you don't supply @var{frame}, they use the selected frame.
@defun frame-char-height &optional frame
@defunx frame-char-width &optional frame
-These functions return the height and width, respectively, of a
-character in @var{frame}, measured in pixels. The values depend on the
-choice of font. If you don't supply @var{frame}, these functions use
-the selected frame.
+These functions return the height and width of a character in
+@var{frame}, measured in pixels. The values depend on the choice of
+font. If you don't supply @var{frame}, these functions use the selected
+frame.
@end defun
@defun set-frame-size frame cols rows
@@ -354,7 +354,7 @@ Size}.
@defun x-parse-geometry geom
@cindex geometry specification
The function @code{x-parse-geometry} converts a standard X windows
-geometry string to an alist which you can use as part of the argument to
+geometry string to an alist that you can use as part of the argument to
@code{make-frame}.
The alist describes which parameters were specified in @var{geom}, and
@@ -454,7 +454,6 @@ one), and then it moves back to the top.
@defun frame-top-window frame
This returns the topmost, leftmost window of frame @var{frame}.
-This is a window
@end defun
At any time, exactly one window on any frame is @dfn{selected within the
@@ -463,7 +462,7 @@ frame also selects this window. You can get the frame's current
selected window with @code{frame-selected-window}.
@defun frame-selected-window frame
-This function returns the window on @var{frame} which is selected within
+This function returns the window on @var{frame} that is selected within
@var{frame}.
@end defun
@@ -482,7 +481,7 @@ must use the minibuffer window of some other frame. When you create the
frame, you can specify explicitly the frame on which to find the
minibuffer to use. If you don't, then the minibuffer is found in the
frame which is the value of the variable
-@code{default-minibuffer-frame}. Its value should be a frame which does
+@code{default-minibuffer-frame}. Its value should be a frame that does
have a minibuffer.
If you use a minibuffer-only frame, you might want that frame to raise
@@ -534,7 +533,7 @@ Don't call it for any other reason.
@defun redirect-frame-focus frame focus-frame
This function redirects focus from @var{frame} to @var{focus-frame}.
-This means that @var{focus-frame} will receive subsequent keystrokes and
+This means that @var{focus-frame} will receive subsequent keystrokes
intended for @var{frame}. After such an event, the value of
@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
events specifying @var{frame} will instead select @var{focus-frame}.
@@ -547,7 +546,7 @@ One use of focus redirection is for frames that don't have minibuffers.
These frames use minibuffers on other frames. Activating a minibuffer
on another frame redirects focus to that frame. This puts the focus on
the minibuffer's frame, where it belongs, even though the mouse remains
-in the frame which activated the minibuffer.
+in the frame that activated the minibuffer.
Selecting a frame can also change focus redirections. Selecting frame
@code{bar}, when @code{foo} had been selected, changes any redirections
@@ -573,7 +572,7 @@ change it.
A frame may be @dfn{visible}, @dfn{invisible}, or @dfn{iconified}. If
it is visible, you can see its contents. If it is iconified, the
frame's contents do not appear on the screen, but an icon does. If the
-frame is invisible, it doesn't show in the screen, not even as an icon.
+frame is invisible, it doesn't show on the screen, not even as an icon.
@deffn Command make-frame-visible &optional frame
This function makes frame @var{frame} visible. If you omit @var{frame},
@@ -646,7 +645,7 @@ for any frame using frame parameters. @xref{X Frame Parameters}.
all their properties, and the window configuration of each one.
@defun current-frame-configuration
-This function returns a frame configuration list which describes
+This function returns a frame configuration list that describes
the current arrangement of frames and their contents.
@end defun
@@ -660,7 +659,7 @@ This function restores the state of frames described in
@cindex mouse tracking
@cindex tracking the mouse
-Sometimes it is useful to @dfn{track} the mouse, which means, to display
+Sometimes it is useful to @dfn{track} the mouse, which means to display
something to indicate where the mouse is and move the indicator as the
mouse moves. For efficient mouse tracking, you need a way to wait until
the mouse actually moves.
@@ -911,7 +910,7 @@ independently. The usual values of @var{type} are @code{PRIMARY} and
with X Window System conventions. The default is @code{PRIMARY}.
@end defun
-@defun x-get-selection type data-type
+@defun x-get-selection &optional type data-type
This function accesses selections set up by Emacs or by other X
clients. It takes two optional arguments, @var{type} and
@var{data-type}. The default for @var{type}, the selection type, is
@@ -1004,14 +1003,14 @@ is much slower.
@node Resources
@section X Resources
-@defun x-get-resource attribute &optional name class
+@defun x-get-resource attribute &optional component subclass
The function @code{x-get-resource} retrieves a resource value from the X
Windows defaults database.
Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
This function searches using a key of the form
-@samp{@var{instance}.@var{attribute}}, using the name under which Emacs
-was invoked as @var{instance}, and using @samp{Emacs} as the class.
+@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
+under which Emacs was invoked), and using @samp{Emacs} as the class.
The optional arguments @var{component} and @var{subclass} add to the key
and the class, respectively. You must specify both of them or neither.
diff --git a/lispref/searching.texi b/lispref/searching.texi
index be43dc387ba..98ce0f7c9e7 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -80,8 +80,11 @@ upper bound and returns @code{nil}. (It would be more consistent now
to return the new position of point in that case, but some programs
may depend on a value of @code{nil}.)
- If @var{repeat} is non-@code{nil}, then the search is repeated that
-many times. Point is positioned at the end of the last match.
+If @var{repeat} is supplied (it must be a positive number), then the
+search is repeated that many times (each time starting at the end of the
+previous time's match). If these successive searches succeed, the
+function succeeds, moving point and returning its new value. Otherwise
+the search fails.
@end deffn
@deffn Command search-backward string &optional limit noerror repeat
@@ -165,13 +168,14 @@ regexps; the following section says how to search for them.
@node Syntax of Regexps
@subsection Syntax of Regular Expressions
- Regular expressions have a syntax in which a few characters are special
-constructs and the rest are @dfn{ordinary}. An ordinary character is a
-simple regular expression which matches that character and nothing else.
-The special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*},
-@samp{+}, @samp{?}, @samp{[}, @samp{]} and @samp{\}; no new special
-characters will be defined in the future. Any other character appearing
-in a regular expression is ordinary, unless a @samp{\} precedes it.
+ Regular expressions have a syntax in which a few characters are
+special constructs and the rest are @dfn{ordinary}. An ordinary
+character is a simple regular expression that matches that character and
+nothing else. The special characters are @samp{.}, @samp{*}, @samp{+},
+@samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new
+special characters will be defined in the future. Any other character
+appearing in a regular expression is ordinary, unless a @samp{\}
+precedes it.
For example, @samp{f} is not a special character, so it is ordinary, and
therefore @samp{f} is a regular expression that matches the string
@@ -180,7 +184,7 @@ therefore @samp{f} is a regular expression that matches the string
only @samp{o}.@refill
Any two regular expressions @var{a} and @var{b} can be concatenated. The
-result is a regular expression which matches a string if @var{a} matches
+result is a regular expression that matches a string if @var{a} matches
some amount of the beginning of that string and @var{b} matches the rest of
the string.@refill
@@ -255,14 +259,14 @@ inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any
lower case letter. Ranges may be intermixed freely with individual
characters, as in @samp{[a-z$%.]}, which matches any lower case letter
-or @samp{$}, @samp{%} or a period.@refill
+or @samp{$}, @samp{%}, or a period.@refill
To include a @samp{]} in a character set, make it the first character.
For example, @samp{[]a]} matches @samp{]} or @samp{a}. To include a
-@samp{-}, write @samp{-} as the first character in the set, or put
+@samp{-}, write @samp{-} as the first character in the set, or put it
immediately after a range. (You can replace one individual character
@var{c} with the range @samp{@var{c}-@var{c}} to make a place to put the
-@samp{-}). There is no way to write a set containing just @samp{-} and
+@samp{-}.) There is no way to write a set containing just @samp{-} and
@samp{]}.
To include @samp{^} in a set, put it anywhere but at the beginning of
@@ -284,21 +288,21 @@ newline is mentioned as one of the characters not to match.
@item ^
@cindex @samp{^} in regexp
@cindex beginning of line in regexp
-is a special character that matches the empty string, but only at
-the beginning of a line in the text being matched. Otherwise it fails
-to match anything. Thus, @samp{^foo} matches a @samp{foo} which occurs
-at the beginning of a line.
+is a special character that matches the empty string, but only at the
+beginning of a line in the text being matched. Otherwise it fails to
+match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
+the beginning of a line.
-When matching a string, @samp{^} matches at the beginning of the string
-or after a newline character @samp{\n}.
+When matching a string instead of a buffer, @samp{^} matches at the
+beginning of the string or after a newline character @samp{\n}.
@item $
@cindex @samp{$} in regexp
is similar to @samp{^} but matches only at the end of a line. Thus,
@samp{x+$} matches a string of one @samp{x} or more at the end of a line.
-When matching a string, @samp{$} matches at the end of the string
-or before a newline character @samp{\n}.
+When matching a string instead of a buffer, @samp{$} matches at the end
+of the string or before a newline character @samp{\n}.
@item \
@cindex @samp{\} in regexp
@@ -306,8 +310,8 @@ has two functions: it quotes the special characters (including
@samp{\}), and it introduces additional special constructs.
Because @samp{\} quotes special characters, @samp{\$} is a regular
-expression which matches only @samp{$}, and @samp{\[} is a regular
-expression which matches only @samp{[}, and so on.
+expression that matches only @samp{$}, and @samp{\[} is a regular
+expression that matches only @samp{[}, and so on.
Note that @samp{\} also has special meaning in the read syntax of Lisp
strings (@pxref{String Type}), and must be quoted with @samp{\}. For
@@ -322,13 +326,12 @@ example, the regular expression that matches the @samp{\} character is
are treated as ordinary ones if they are in contexts where their special
meanings make no sense. For example, @samp{*foo} treats @samp{*} as
ordinary since there is no preceding expression on which the @samp{*}
-can act. It is poor practice to depend on this behavior; better to
-quote the special character anyway, regardless of where it
-appears.@refill
+can act. It is poor practice to depend on this behavior; quote the
+special character anyway, regardless of where it appears.@refill
For the most part, @samp{\} followed by any character matches only
that character. However, there are several exceptions: characters
-which, when preceded by @samp{\}, are special constructs. Such
+that, when preceded by @samp{\}, are special constructs. Such
characters are always ordinary when encountered on their own. Here
is a table of @samp{\} constructs:
@@ -371,13 +374,13 @@ To record a matched substring for future reference.
@end enumerate
This last application is not a consequence of the idea of a
-parenthetical grouping; it is a separate feature which happens to be
+parenthetical grouping; it is a separate feature that happens to be
assigned as a second meaning to the same @samp{\( @dots{} \)} construct
because there is no conflict in practice between the two meanings.
Here is an explanation of this feature:
@item \@var{digit}
-matches the same text which matched the @var{digit}th occurrence of a
+matches the same text that matched the @var{digit}th occurrence of a
@samp{\( @dots{} \)} construct.
In other words, after the end of a @samp{\( @dots{} \)} construct. the
@@ -404,12 +407,12 @@ determines which characters these are. @xref{Syntax Tables}.
@item \W
@cindex @samp{\W} in regexp
-matches any character that is not a word-constituent.
+matches any character that is not a word constituent.
@item \s@var{code}
@cindex @samp{\s} in regexp
matches any character whose syntax is @var{code}. Here @var{code} is a
-character which represents a syntax code: thus, @samp{w} for word
+character that represents a syntax code: thus, @samp{w} for word
constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
etc. @xref{Syntax Tables}, for a list of syntax codes and the
characters that stand for them.
@@ -419,7 +422,7 @@ characters that stand for them.
matches any character whose syntax is not @var{code}.
@end table
- These regular expression constructs match the empty string---that is,
+ The following regular expression constructs match the empty string---that is,
they don't use up any characters---but whether they match depends on the
context.
@@ -463,7 +466,7 @@ matches the empty string, but only at the end of a word.
@kindex invalid-regexp
Not every string is a valid regular expression. For example, a string
with unbalanced square brackets is invalid (with a few exceptions, such
-as @samp{[]]}, and so is a string that ends with a single @samp{\}. If
+as @samp{[]]}), and so is a string that ends with a single @samp{\}. If
an invalid regular expression is passed to any of the search functions,
an @code{invalid-regexp} error is signaled.
@@ -481,13 +484,13 @@ string match when calling a function that wants a regular expression.
One use of @code{regexp-quote} is to combine an exact string match with
context described as a regular expression. For example, this searches
-for the string which is the value of @code{string}, surrounded by
+for the string that is the value of @code{string}, surrounded by
whitespace:
@example
@group
(re-search-forward
- (concat "\\s " (regexp-quote string) "\\s "))
+ (concat "\\s-" (regexp-quote string) "\\s-"))
@end group
@end example
@end defun
diff --git a/lispref/text.texi b/lispref/text.texi
index 7d33a1c5d14..637ebd610eb 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -8,7 +8,7 @@
@cindex text
This chapter describes the functions that deal with the text in a
-buffer. Most examine, insert or delete text in the current buffer,
+buffer. Most examine, insert, or delete text in the current buffer,
often in the vicinity of point. Many are interactive. All the
functions that change the text provide for undoing the changes
(@pxref{Undo}).
@@ -130,7 +130,7 @@ the text. See also @code{point-max} in @xref{Point}.
@defun bolp
This function returns @code{t} if point is at the beginning of a line.
@xref{Text Lines}. The beginning of the buffer (or its accessible
-portion always counts as the beginning of a line.
+portion) always counts as the beginning of a line.
@end defun
@defun eolp
@@ -207,7 +207,7 @@ This function lets you compare two substrings of the same buffer or two
different buffers. The first three arguments specify one substring,
giving a buffer and two positions within the buffer. The last three
arguments specify the other substring in the same way. You can use
-@code{nil} for @var{buffer1}, @var{buffer2} or both to stand for the
+@code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the
current buffer.
The value is negative if the first substring is less, positive if the
@@ -251,17 +251,17 @@ inserted text.
@cindex insertion before point
@cindex before point, insertion
Some insertion functions leave point before the inserted text, while
-other functions leave it after. We call the latter insertion
-@dfn{before point}.
+other functions leave it after. We call the former insertion @dfn{after
+point} and the latter insertion @dfn{before point}.
Insertion functions signal an error if the current buffer is
read-only.
@defun insert &rest args
This function inserts the strings and/or characters @var{args} into the
-current buffer, at point, moving point forward. An error is signaled
-unless all @var{args} are either strings or characters. The value is
-@code{nil}.
+current buffer, at point, moving point forward. In other words, it
+inserts the text before point. An error is signaled unless all
+@var{args} are either strings or characters. The value is @code{nil}.
@end defun
@defun insert-before-markers &rest args
@@ -304,14 +304,14 @@ We hold these truths to be self-evident, that all
@result{} nil
---------- Buffer: bar ----------
-We hold these truth
+We hold these truth@point{}
---------- Buffer: bar ----------
@end group
@end example
@end defun
@xref{Sticky Properties}, for other insertion functions that inherit
-text properties from the nearby text.
+text properties from the nearby text in addition to inserting it.
@node Commands for Insertion
@section User-Level Insertion Commands
@@ -329,11 +329,11 @@ the mark after the inserted text. The value is @code{nil}.
@deffn Command self-insert-command count
@cindex character insertion
@cindex self-insertion
-This command inserts the last character typed @var{count} times and
-returns @code{nil}. Most printing characters are bound to this command.
-In routine use, @code{self-insert-command} is the most frequently called
-function in Emacs, but programs rarely use it except to install it on a
-keymap.
+This command inserts the last character typed; it does so @var{count}
+times, before point, and returns @code{nil}. Most printing characters
+are bound to this command. In routine use, @code{self-insert-command}
+is the most frequently called function in Emacs, but programs rarely use
+it except to install it on a keymap.
In an interactive call, @var{count} is the numeric prefix argument.
@@ -357,11 +357,13 @@ If @var{number-of-newlines} is supplied, that many newline characters
are inserted.
@cindex newline and Auto Fill mode
-In Auto Fill mode, @code{newline} can break the preceding line if
-@var{number-of-newlines} is not supplied. When this happens, it
-actually inserts two newlines at different places: one at point, and
-another earlier in the line. @code{newline} does not auto-fill if
-@var{number-of-newlines} is non-@code{nil}.
+This function calls @code{auto-fill-function} if the current column
+number is greater than the value of @code{fill-column} and
+@var{number-of-newlines} is @code{nil}. Typically what
+@code{auto-fill-function} does is insert a newline; thus, the overall
+result in this case is to insert two newlines at different places: one
+at point, and another earlier in the line. @code{newline} does not
+auto-fill if @var{number-of-newlines} is non-@code{nil}.
The value returned is @code{nil}. In an interactive call, @var{count}
is the numeric prefix argument.
@@ -369,7 +371,7 @@ is the numeric prefix argument.
@deffn Command split-line
This command splits the current line, moving the portion of the line
-after point down vertically, so that it is on the next line directly
+after point down vertically so that it is on the next line directly
below where it was before. Whitespace is inserted as needed at the
beginning of the lower line, using the @code{indent-to} function.
@code{split-line} returns the position of point.
@@ -390,8 +392,8 @@ buffer-local when set in any fashion.
Deletion means removing part of the text in a buffer, without saving
it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
-Some deletion functions save text in the kill ring in some cases
-but not in the usual case.
+Some deletion functions do save text in the kill ring in some special
+cases.
All of the deletion functions operate on the current buffer, and all
return a value of @code{nil}.
@@ -479,7 +481,7 @@ This function deletes all spaces and tabs around point. It returns
In the following examples, we call @code{delete-horizontal-space} four
times, once on each line, with point between the second and third
-characters on the successive line.
+characters on the line each time.
@example
@group
@@ -514,7 +516,7 @@ instead. The value is @code{nil}.
If there is a fill prefix, and the second of the lines being joined
starts with the prefix, then @code{delete-indentation} deletes the
-fill prefix before joining the lines.
+fill prefix before joining the lines. @xref{Filling}.
In the example below, point is located on the line starting
@samp{events}, and it makes no difference if there are trailing spaces
@@ -553,8 +555,8 @@ also appropriate. Otherwise, one space is appropriate. @xref{Syntax
Class Table}.
In the example below, @code{fixup-whitespace} is called the first time
-with point before the word @samp{spaces} in the first line. for the
-second invocation, Point is directly after the @samp{(}.
+with point before the word @samp{spaces} in the first line. For the
+second invocation, point is directly after the @samp{(}.
@smallexample
@group
@@ -612,21 +614,21 @@ functions.
Most of the kill commands are primarily for interactive use, and are
not described here. What we do describe are the functions provided for
use in writing such commands. You can use these functions to write
-commands for killing text. When you need to deleting text for internal
+commands for killing text. When you need to delete text for internal
purposes within a Lisp function, you should normally use deletion
functions, so as not to disturb the kill ring contents.
@xref{Deletion}.
Killed text is saved for later yanking in the @dfn{kill ring}. This
-is a list which holds, not just the last text kill, but a number of
-recent kills. We call this a ``ring'' because yanking treats it as a
-cyclic order. The list is kept in the variable @code{kill-ring}, and
-can be operated on with the usual functions for lists; there are also
-specialized functions, described in this section, which treat it as a
-ring.
+is a list that holds a number of recent kills, not just the last text
+kill. We call this a ``ring'' because yanking treats it as having
+elements in a cyclic order. The list is kept in the variable
+@code{kill-ring}, and can be operated on with the usual functions for
+lists; there are also specialized functions, described in this section,
+that treat it as a ring.
Some people think this use of the word ``kill'' is unfortunate, since
-it refers to operations which specifically @emph{do not} destroy the
+it refers to operations that specifically @emph{do not} destroy the
entities ``killed''. This is in sharp contrast to ordinary life, in
which death is permanent and ``killed'' entities do not come back to
life. Therefore, other metaphors have been proposed. For example, the
@@ -638,7 +640,7 @@ would be difficult to change the terminology now.
* Kill Ring Concepts:: What text looks like in the kill ring.
* Kill Functions:: Functions that kill text.
* Yank Commands:: Commands that access the kill ring.
-* Low Level Kill Ring:: Functions and variables for kill ring access.
+* Low-Level Kill Ring:: Functions and variables for kill ring access.
* Internals of Kill Ring:: Variables that hold kill-ring data.
@end menu
@@ -660,7 +662,7 @@ new entry automatically deletes the last entry.
When kill commands are interwoven with other commands, each kill
command makes a new entry in the kill ring. Multiple kill commands in
succession build up a single entry in the kill ring, which would be
-yanked as a unit. The second and subsequent consecutive kill commands
+yanked as a unit; the second and subsequent consecutive kill commands
add text to the entry made by the first one.
For yanking, one entry in the kill ring is designated the ``front'' of
@@ -678,8 +680,8 @@ command that calls this function is a ``kill command'' (and should
probably have @samp{kill} in its name). @code{kill-region} puts the
newly killed text in a new element at the beginning of the kill ring or
adds it to the most recent element. It uses the @code{last-command}
-variable to determine whether the previous was a kill command, and if so
-appends the killed text to the most recent entry.
+variable to determine whether the previous command was a kill command,
+and if so appends the killed text to the most recent entry.
@deffn Command kill-region start end
This function kills the text in the region defined by @var{start} and
@@ -704,7 +706,7 @@ the cursor momentarily, or by displaying a message in the echo area.
Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or
-@code{kill-append} instead. @xref{Low Level Kill Ring}.
+@code{kill-append} instead. @xref{Low-Level Kill Ring}.
@end deffn
@node Yank Commands
@@ -754,8 +756,8 @@ oldest.
The value is always @code{nil}.
@end deffn
-@node Low Level Kill Ring
-@subsection Low Level Kill Ring
+@node Low-Level Kill Ring
+@subsection Low-Level Kill Ring
These functions and variables provide access to the kill ring at a lower
level, but still convenient for use in Lisp programs. They take care of
@@ -763,13 +765,13 @@ interaction with X Window selections. They do not exist in Emacs
version 18.
@defun current-kill n &optional do-not-move
-The function @code{current-kill} rotates the yanking pointer in the
-kill ring by @var{n} places, and returns the text at that place in the
-ring.
+The function @code{current-kill} rotates the yanking pointer which
+designates the ``front'' of the kill ring by @var{n} places (from newer
+kills to older ones), and returns the text at that place in the ring.
If the optional second argument @var{do-not-move} is non-@code{nil},
then @code{current-kill} doesn't alter the yanking pointer; it just
-returns the @var{n}th kill forward from the current yanking pointer.
+returns the @var{n}th kill, counting from the current yanking pointer.
If @var{n} is zero, indicating a request for the latest kill,
@code{current-kill} calls the value of
@@ -808,8 +810,8 @@ client. @xref{X Selections}.
@end defvar
@defvar interprogram-cut-function
-This variable provides a way of communicating killed text to and from
-other programs, when you are using a window system. Its value should be
+This variable provides a way of communicating killed text to other
+programs, when you are using a window system. Its value should be
@code{nil} or a function of one argument.
If the value is a function, @code{kill-new} and @code{kill-append} call
@@ -828,13 +830,13 @@ form of a list of strings. The most recent kill is always at the front
of the list.
The @code{kill-ring-yank-pointer} variable points to a link in the
-kill ring list, whose @sc{car} is the text to yank next. Moving
+kill ring list, whose @sc{car} is the text to yank next. We say it
+identifies the ``front'' of the ring. Moving
@code{kill-ring-yank-pointer} to a different link is called
-@dfn{rotating the kill ring}; we say it identifies the ``front'' of the
-ring. We call the kill ring a ``ring'' because the functions that move
-the yank pointer wrap around from the end of the list to the beginning,
-or vice-versa. Rotation of the kill ring is virtual; it does not change
-the value of @code{kill-ring}.
+@dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
+the functions that move the yank pointer wrap around from the end of the
+list to the beginning, or vice-versa. Rotation of the kill ring is
+virtual; it does not change the value of @code{kill-ring}.
Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
variables whose values are normally lists. The word ``pointer'' in the
@@ -845,8 +847,8 @@ command.
The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
of the links in the kill ring list. The element it identifies is the
@sc{car} of that link. Kill commands, which change the kill ring, also
-set this variable from @code{kill-ring}. The effect is to rotate the
-ring so that the newly killed text is at front.
+set this variable to the value of @code{kill-ring}. The effect is to
+rotate the ring so that the newly killed text is at the front.
Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
pointing to the second entry in the kill ring @code{("some text" "a
@@ -873,8 +875,8 @@ This state of affairs might occur after @kbd{C-y} (@code{yank})
immediately followed by @kbd{M-y} (@code{yank-pop}).
@defvar kill-ring
-This variable holds list of killed text sequences, most recently killed
-first.
+This variable holds the list of killed text sequences, most recently
+killed first.
@end defvar
@defvar kill-ring-yank-pointer
@@ -895,12 +897,12 @@ value for @code{kill-ring-max} is 30.
@section Undo
@cindex redo
- Most buffers have an @dfn{undo list} which records all changes made to
-the buffer's text so that they can be undone. (The buffers which don't
-have one are usually special-purpose buffers for which Emacs assumes
-that undoing is not useful.) All the primitives which modify the text
-in the buffer automatically add elements to the front of the undo list,
-which is in the variable @code{buffer-undo-list}.
+ Most buffers have an @dfn{undo list}, which records all changes made
+to the buffer's text so that they can be undone. (The buffers that
+don't have one are usually special-purpose buffers for which Emacs
+assumes that undoing is not useful.) All the primitives that modify the
+text in the buffer automatically add elements to the front of the undo
+list, which is in the variable @code{buffer-undo-list}.
@defvar buffer-undo-list
This variable's value is the undo list of the current buffer.
@@ -1028,10 +1030,10 @@ change group at which this size is exceeded is the last one kept.
@end defvar
@defvar undo-strong-limit
-The upper limit for the acceptable size of an undo list. The change
-group at which this size is exceeded is discarded itself (along with all
-subsequent changes). There is one exception: garbage collection always
-keeps the very latest change group no matter how big it is.
+This is the upper limit for the acceptable size of an undo list. The
+change group at which this size is exceeded is discarded itself (along
+with all older change groups). There is one exception: the very latest
+change group is never discarded separate no matter how big it is.
@end defvar
@node Filling
@@ -1088,8 +1090,8 @@ the header lines.
Ordinarily, @code{fill-individual-paragraphs} regards each change in
indentation as starting a new paragraph. If
@code{fill-individual-varying-indent} is non-@code{nil}, then only
-separator lines separate paragraphs. That mode can handle paragraphs
-with extra indentation on the first line.
+separator lines separate paragraphs. That mode can handle indented
+paragraphs with additional indentation on the first line.
@end deffn
@defopt fill-individual-varying-indent
@@ -1116,6 +1118,16 @@ that the line ends exactly at @code{fill-column}. It returns
@code{nil}.
@end deffn
+@defopt fill-prefix
+This variable specifies a string of text that appears at the beginning
+of normal text lines and should be disregarded when filling them. Any
+line that fails to start with the fill prefix is considered the start of
+a paragraph; so is any line that starts with the fill prefix followed by
+additional whitespace. Lines that start with the fill prefix but no
+additional whitespace are ordinary text lines that can be filled
+together. The resulting filled lines also start with the fill prefix.
+@end defopt
+
@defopt fill-column
This buffer-local variable specifies the maximum width of filled
lines. Its value should be an integer, which is a number of columns.
@@ -1142,10 +1154,10 @@ The default value for @code{default-fill-column} is 70.
@cindex filling, automatic
@cindex Auto Fill mode
- Auto Fill mode is a minor mode which fills lines automatically as text
-as inserted. This section describes the hook and the two variables used
-by Auto Fill mode. For a description of functions that you can call
-explicitly to fill and justify existing text, see @ref{Filling}.
+ Auto Fill mode is a minor mode that fills lines automatically as text
+as inserted. This section describes the hook used by Auto Fill mode.
+For a description of functions that you can call explicitly to fill and
+justify existing text, see @ref{Filling}.
@defvar auto-fill-function
The value of this variable should be a function (of no arguments) to
@@ -1174,7 +1186,7 @@ rearranges the order of the elements of a list (@pxref{Rearrangement}).
The values returned by these functions are not meaningful.
@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
-This function is the general text sorting routine that divides a buffer
+This function is the general text-sorting routine that divides a buffer
into records and sorts them. Most of the commands in this section use
this function.
@@ -1444,8 +1456,8 @@ converts the tab into spaces so that it can move precisely to column
@var{force}, since there is no way to split them.
The argument @var{force} also has an effect if the line isn't long
-enough to reach column @var{column}; in that case, it says to indent at
-the end of the line to reach that column.
+enough to reach column @var{column}; in that case, it says to add
+whitespace at the end of the line to reach that column.
If @var{column} is not an integer, an error is signaled.
@@ -1489,11 +1501,12 @@ end of the line.
@deffn Command indent-to column &optional minimum
@comment !!Type Primitive Function
@comment !!SourceFile indent.c
-This function indents from point with tabs and spaces until
-@var{column} is reached. If @var{minimum} is specified and
-non-@code{nil}, then at least that many spaces are inserted even if this
-requires going beyond @var{column}. The value is the column at which
-the inserted indentation ends.
+This function indents from point with tabs and spaces until @var{column}
+is reached. If @var{minimum} is specified and non-@code{nil}, then at
+least that many spaces are inserted even if this requires going beyond
+@var{column}. Otherwise the function does nothing if point is already
+beyond @var{column}. The value is the column at which the inserted
+indentation ends.
@end deffn
@defopt indent-tabs-mode
@@ -1532,17 +1545,9 @@ indent the current line in a way appropriate for the current major mode.
This command calls the function in @code{indent-line-function} to indent
the current line; except that if that function is
@code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That
-is a trivial command which inserts a tab character.)
+is a trivial command that inserts a tab character.)
@end deffn
-@defvar left-margin
-This variable is the column to which the default
-@code{indent-line-function} will indent. (That function is
-@code{indent-to-left-margin}.) In Fundamental mode, @key{LFD} indents
-to this column. This variable automatically becomes buffer-local when
-set in any fashion.
-@end defvar
-
@defun indent-to-left-margin
This is the default @code{indent-line-function}, used in Fundamental
mode, Text mode, etc. Its effect is to adjust the indentation at the
@@ -1551,6 +1556,12 @@ beginning of the current line to the value specified by the variable
whitespace.
@end defun
+@defvar left-margin
+This variable specifies the column for @code{indent-to-left-margin} to
+indent to. In Fundamental mode, @key{LFD} indents to this column. This
+variable automatically becomes buffer-local when set in any fashion.
+@end defvar
+
@deffn Command newline-and-indent
@comment !!SourceFile simple.el
This function inserts a newline, then indents the new line (the one
@@ -1580,7 +1591,7 @@ by @code{left-margin}.
@node Region Indent
@subsection Indenting an Entire Region
- This section describes commands which indent all the lines in the
+ This section describes commands that indent all the lines in the
region. They return unpredictable values.
@deffn Command indent-region start end to-column
@@ -1608,15 +1619,15 @@ region one by one, but presumably faster.
If the value is @code{nil}, there is no short cut, and
@code{indent-region} actually works line by line.
-A short cut function is useful in modes such as C mode and Lisp mode,
+A short-cut function is useful in modes such as C mode and Lisp mode,
where the @code{indent-line-function} must scan from the beginning of
-the function: applying it to each line would be quadratic in time. The
-short cut can update the scan information as it moves through the lines
-indenting them; this takes linear time. In a mode where indenting a
-line individually is fast, there is no need for a short cut.
+the function definition: applying it to each line would be quadratic in
+time. The short cut can update the scan information as it moves through
+the lines indenting them; this takes linear time. In a mode where
+indenting a line individually is fast, there is no need for a short cut.
-@code{indent-region} with a non-@code{nil} argument has a different
-meaning and does not use this variable.
+@code{indent-region} with a non-@code{nil} argument @var{to-column} has
+a different meaning and does not use this variable.
@end defvar
@deffn Command indent-rigidly start end count
@@ -1647,7 +1658,7 @@ the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
@node Relative Indent
@subsection Indentation Relative to Previous Lines
- This section describes two commands which indent the current line
+ This section describes two commands that indent the current line
based on the contents of previous lines.
@deffn Command indent-relative &optional unindented-ok
@@ -1727,7 +1738,7 @@ column, this command does nothing.
@cindex tabs stops for indentation
This section explains the mechanism for user-specified ``tab stops''
-and the mechanisms which use and set them. The name ``tab stops'' is
+and the mechanisms that use and set them. The name ``tab stops'' is
used because the feature is similar to that of the tab stops on a
typewriter. The feature works by inserting an appropriate number of
spaces and tab characters to reach the next tab stop column; it does not
@@ -1842,9 +1853,8 @@ If @var{count} is negative, the function capitalizes the
@minus{}@var{count} previous words but does not move point. The value
is @code{nil}.
-If point is in the middle of a word, the part of word the before point
-(if moving forward) or after point (if operating backward) is ignored.
-The rest is treated as an entire word.
+If point is in the middle of a word, the part of the word before point
+is ignored when moving forward. The rest is treated as an entire word.
When @code{capitalize-word} is called interactively, @var{count} is
set to the numeric prefix argument.
@@ -1929,7 +1939,7 @@ string). The argument @var{object} is optional and defaults to the
current buffer.
If there is no @var{prop} property strictly speaking, but the character
-has a category which is a symbol, then @code{get-text-property} returns
+has a category that is a symbol, then @code{get-text-property} returns
the @var{prop} property of that symbol.
@end defun
@@ -2050,6 +2060,10 @@ argument to these functions, especially the ones that search for a
single property---otherwise, they may spend a long time considering
changes in other properties while scanning to the end of the buffer.
+Remember that a position is always between two characters; the position
+returned by these functions is between two characters with different
+properties.
+
@defun next-property-change pos &optional object limit
The function scans the text forward from position @var{pos} in the
string or buffer @var{object} till it finds a change in some text
@@ -2063,11 +2077,9 @@ If @var{limit} is non-@code{nil}, then the scan ends at position
@code{next-property-change} returns @var{limit}.
The value is @code{nil} if the properties remain unchanged all the way
-to the end of @var{object} and @var{limit} is @code{nil}.
-
-If the value is non-@code{nil}, it is a position greater than or equal
-to @var{pos}. The value equals @var{pos} only when @var{limit} equals
-@var{pos}.
+to the end of @var{object} and @var{limit} is @code{nil}. If the value
+is non-@code{nil}, it is a position greater than or equal to @var{pos}.
+The value equals @var{pos} only when @var{limit} equals @var{pos}.
Here is an example of how to scan the buffer by chunks of text within
which all properties are constant:
@@ -2106,17 +2118,13 @@ This is like @code{next-property-change}, but scans back from @var{pos}
instead of forward. If the value is non-@code{nil}, it is a position
less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
equals @var{pos}.
-
-Remember that a position is always between two characters; the position
-returned by this function is between two characters with different
-properties.
@end defun
@defun previous-single-property-change pos prop &optional object limit
-This is like @code{next-property-change}, but scans back from @var{pos}
-instead of forward. If the value is non-@code{nil}, it is a position
-less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
-equals @var{pos}.
+This is like @code{next-single-property-change}, but scans back from
+@var{pos} instead of forward. If the value is non-@code{nil}, it is a
+position less than or equal to @var{pos}; it equals @var{pos} only if
+@var{limit} equals @var{pos}.
@end defun
@defun text-property-any start end prop value &optional object
@@ -2170,9 +2178,10 @@ that all text between the character and where the mouse is have the same
@item local-map
@cindex keymap of character
@kindex local-map @r{(text property)}
-You can specify a different keymap for a portion of the text by means
-of a @code{local-map} property. The property's value, for the character
-after point, replaces the buffer's local map. @xref{Active Keymaps}.
+You can specify a different keymap for a portion of the text by means of
+a @code{local-map} property. The property's value for the character
+after point, if non-@code{nil}, replaces the buffer's local map.
+@xref{Active Keymaps}.
@item read-only
@cindex read-only character
@@ -2219,11 +2228,12 @@ the function will be called.
@itemx insert-behind-hooks
@kindex insert-in-front-hooks @r{(text property)}
@kindex insert-behind-hooks @r{(text property)}
-Assuming insertion is allowed, it then calls the functions
-listed in the @code{insert-in-front-hooks} property of the following
-character and in the @code{insert-behind-hooks} property of the
-preceding character. These functions receive two arguments, the
-beginning and end of the inserted text.
+The operation of inserting text in a buffer, after actually modifying
+the buffer, calls the functions listed in the
+@code{insert-in-front-hooks} property of the following character and in
+the @code{insert-behind-hooks} property of the preceding character.
+These functions receive two arguments, the beginning and end of the
+inserted text.
See also @ref{Change Hooks}, for other hooks that are called
when you change text in a buffer.
@@ -2253,8 +2263,9 @@ with two arguments: the old value of point, and the new one.
The same comparison is made for the characters before the old and new
locations. The result may be to execute two @code{point-left} functions
(which may be the same function) and/or two @code{point-entered}
-functions (which may be the same function). The @code{point-left}
-functions are always called before the @code{point-entered} functions.
+functions (which may be the same function). In any case, all the
+@code{point-left} functions are called first, followed by all the
+@code{point-entered} functions.
A primitive function may examine characters at various positions
without moving point to those positions. Only an actual change in the
@@ -2279,9 +2290,10 @@ depending on your choice of insertion primitive. The ordinary text
insertion functions such as @code{insert} do not inherit any properties.
They insert text with precisely the properties of the string being
inserted, and no others. This is correct for programs that copy text
-from one context to another---for example, into or out of the kill
-ring. To insert with inheritance, use the special primatives described
-in this section.
+from one context to another---for example, into or out of the kill ring.
+To insert with inheritance, use the special primitives described in this
+section. Self-inserting characters inherit properties because they work
+using these primitives.
When you do insertion with inheritance, @emph{which} properties are
inherited depends on two specific properties: @code{front-sticky} and
@@ -2330,7 +2342,7 @@ adjoining text.
@end defun
@node Saving Properties
-@subsection Saving Text Properites in Files
+@subsection Saving Text Properties in Files
@cindex text properties in files
@cindex saving text properties
@@ -2457,7 +2469,7 @@ defined by @var{start} and @var{end}.
@cindex undo avoidance
If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region}
does not record the change for undo and does not mark the buffer as
-modified. This feature is useful for changes which are not considered
+modified. This feature is useful for changes that are not considered
significant, such as when Outline mode changes visible lines to
invisible lines and vice versa.
@@ -2493,8 +2505,8 @@ characters with codes larger than the length of @var{table} are not
altered by the translation.
The return value of @code{translate-region} is the number of
-characters which were actually changed by the translation. This does
-not count characters which were mapped into themselves in the
+characters that were actually changed by the translation. This does
+not count characters that were mapped into themselves in the
translation table.
This function is available in Emacs versions 19 and later.
@@ -2510,7 +2522,7 @@ a frame configuration (of all frames). Each register is named by a
single character. All characters, including control and meta characters
(but with the exception of @kbd{C-g}), can be used to name registers.
Thus, there are 255 possible registers. A register is designated in
-Emacs Lisp by a character which is its name.
+Emacs Lisp by a character that is its name.
The functions in this section return unpredictable values unless
otherwise stated.