Mercurial > emacs
changeset 8427:bc548090f760
*** empty log message ***
| author | Richard M. Stallman <rms@gnu.org> |
|---|---|
| date | Wed, 03 Aug 1994 00:12:07 +0000 |
| parents | 3abe02e03dc8 |
| children | 68b00de2ac0f |
| files | lispref/frames.texi lispref/searching.texi lispref/text.texi |
| diffstat | 3 files changed, 209 insertions(+), 195 deletions(-) [+] |
line wrap: on
line diff
--- a/lispref/frames.texi Tue Aug 02 21:59:19 1994 +0000 +++ b/lispref/frames.texi Wed Aug 03 00:12:07 1994 +0000 @@ -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 @@ 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 @@ 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 @@ @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 @@ @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 @@ @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 @@ @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 @@ @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 @@ 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 @@ 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 @@ @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 @@ 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 @@ 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 @@ 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 @@ @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 @@ 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 @@ @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.
--- a/lispref/searching.texi Tue Aug 02 21:59:19 1994 +0000 +++ b/lispref/searching.texi Wed Aug 03 00:12:07 1994 +0000 @@ -80,8 +80,11 @@ 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 @@ @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 @@ 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 @@ 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 @@ @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 @@ @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 @@ 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 @@ @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 @@ @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 @@ 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 @@ @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 @@ 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
--- a/lispref/text.texi Tue Aug 02 21:59:19 1994 +0000 +++ b/lispref/text.texi Wed Aug 03 00:12:07 1994 +0000 @@ -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 @@ @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 @@ 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 @@ @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 @@ @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 @@ @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 @@ 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 @@ @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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ * 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ @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 @@ 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 @@ 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 @@ 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 @@ @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 @@ @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 @@ 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 @@ @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 @@ @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 @@ 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 @@ @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 @@ @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 @@ 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 @@ 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 @@ @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 @@ 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. - -@code{indent-region} with a non-@code{nil} argument has a different -meaning and does not use this variable. +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 @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 @@ @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 @@ @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 @@ @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 @@ 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 @@ 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 @@ @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 @@ 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 @@ @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 @@ @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 @@ 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 @@ 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 @@ @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 @@ @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 @@ 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 @@ 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.