@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Non-ASCII Characters, Markers, Top
* Registers:: How registers are implemented. Accessing the text or
position stored in a register.
* Base 64:: Conversion to or from base 64 encoding.
-* MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''.
-* Atomic Changes:: Installing several buffer changs ``atomically''.
+* MD5 Checksum:: Compute the MD5 "message digest"/"checksum".
+* Atomic Changes:: Installing several buffer changes "atomically".
* Change Hooks:: Supplying functions to be run when text is changed.
@end menu
@node Near Point
@section Examining Text Near Point
+@cindex text near point
Many functions are provided to look at the characters around point.
Several simple functions are described here. See also @code{looking-at}
in @ref{Regexp Search}.
+In the following four functions, ``beginning'' or ``end'' of buffer
+refers to the beginning or end of the accessible portion.
+
@defun char-after &optional position
This function returns the character in the current buffer at (i.e.,
immediately after) position @var{position}. If @var{position} is out of
buffer. This is similar to @code{(char-after (point))}. However, if
point is at the end of the buffer, then @code{following-char} returns 0.
-Remember that point is always between characters, and the terminal
-cursor normally appears over the character following point. Therefore,
-the character returned by @code{following-char} is the character the
+Remember that point is always between characters, and the cursor
+normally appears over the character following point. Therefore, the
+character returned by @code{following-char} is the character the
cursor is over.
In this example, point is between the @samp{a} and the @samp{c}.
@node Buffer Contents
@section Examining Buffer Contents
- This section describes two functions that allow a Lisp program to
+ This section describes functions that allow a Lisp program to
convert any portion of the text in the buffer into a string.
@defun buffer-substring start end
arguments can be given in either order. But most often the smaller
argument is written first.
-If the text being copied has any text properties, these are copied into
-the string along with the characters they belong to. @xref{Text
-Properties}. However, overlays (@pxref{Overlays}) in the buffer and
-their properties are ignored, not copied.
+Here's an example which assumes Font-Lock mode is not enabled:
@example
@group
@group
(buffer-substring 1 10)
-@result{} "This is t"
+ @result{} "This is t"
@end group
@group
(buffer-substring (point-max) 10)
-@result{} "he contents of buffer foo
-"
+ @result{} "he contents of buffer foo\n"
+@end group
+@end example
+
+If the text being copied has any text properties, these are copied into
+the string along with the characters they belong to. @xref{Text
+Properties}. However, overlays (@pxref{Overlays}) in the buffer and
+their properties are ignored, not copied.
+
+For example, if Font-Lock mode is enabled, you might get results like
+these:
+
+@example
+@group
+(buffer-substring 1 10)
+ @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
@end group
@end example
@end defun
properties, just the characters themselves. @xref{Text Properties}.
@end defun
+@defun filter-buffer-substring start end &optional delete noprops
+This function passes the buffer text between @var{start} and @var{end}
+through the filter functions specified by the variable
+@code{buffer-substring-filters}, and returns the value from the last
+filter function. If @code{buffer-substring-filters} is @code{nil},
+the value is the unaltered text from the buffer, what
+@code{buffer-substring} would return.
+
+If @var{delete} is non-@code{nil}, this function deletes the text
+between @var{start} and @var{end} after copying it, like
+@code{delete-and-extract-region}.
+
+If @var{noprops} is non-@code{nil}, the final string returned does not
+include text properties, while the string passed through the filters
+still includes text properties from the buffer text.
+
+Lisp code should use this function instead of @code{buffer-substring},
+@code{buffer-substring-no-properties},
+or @code{delete-and-extract-region} when copying into user-accessible
+data structures such as the kill-ring, X clipboard, and registers.
+Major and minor modes can add functions to
+@code{buffer-substring-filters} to alter such text as it is copied out
+of the buffer.
+@end defun
+
+@defvar buffer-substring-filters
+This variable should be a list of functions that accept a single
+argument, a string, and return a string.
+@code{filter-buffer-substring} passes the buffer substring to the
+first function in this list, and the return value of each function is
+passed to the next function. The return value of the last function is
+used as the return value of @code{filter-buffer-substring}.
+
+As a special convention, point is set to the start of the buffer text
+being operated on (i.e., the @var{start} argument for
+@code{filter-buffer-substring}) before these functions are called.
+
+If this variable is @code{nil}, no filtering is performed.
+@end defvar
+
@defun buffer-string
This function returns the contents of the entire accessible portion of
the current buffer as a string. It is equivalent to
---------- Buffer: foo ----------
(buffer-string)
- @result{} "This is the contents of buffer foo
-"
+ @result{} "This is the contents of buffer foo\n"
@end group
@end example
@end defun
-@tindex current-word
@defun current-word &optional strict really-word
This function returns the symbol (or word) at or near point, as a string.
The return value includes no text properties.
-The optional argument @var{really-word} is non-@code{nil}, it finds a
-word; otherwise, it finds a symbol (which includes word characters and
-both symbol constituent characters).
+If the optional argument @var{really-word} is non-@code{nil}, it finds a
+word; otherwise, it finds a symbol (which includes both word
+characters and symbol constituent characters).
If the optional argument @var{strict} is non-@code{nil}, then point
must be in or next to the symbol or word---if no symbol or word is
@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
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
-current buffer.
+giving a buffer (or a buffer name) 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 current buffer.
The value is negative if the first substring is less, positive if the
first is greater, and zero if they are equal. The absolute value of
This function is unlike the other insertion functions in that it
relocates markers initially pointing at the insertion point, to point
-after the inserted text. If an overlay begins the insertion point, the
-inserted text falls outside the overlay; if a nonempty overlay ends at
-the insertion point, the inserted text falls inside that overlay.
+after the inserted text. If an overlay begins at the insertion point,
+the inserted text falls outside the overlay; if a nonempty overlay
+ends at the insertion point, the inserted text falls inside that
+overlay.
@end defun
@defun insert-char character count &optional inherit
This function inserts @var{count} instances of @var{character} into the
-current buffer before point. The argument @var{count} should be a
-number (@code{nil} means 1), and @var{character} must be a character.
-The value is @code{nil}.
+current buffer before point. The argument @var{count} should be an
+integer, and @var{character} must be a character. The value is @code{nil}.
This function does not convert unibyte character codes 128 through 255
to multibyte characters, not even if the current buffer is a multibyte
@defun insert-buffer-substring from-buffer-or-name &optional start end
This function inserts a portion of buffer @var{from-buffer-or-name}
(which must already exist) into the current buffer before point. The
-text inserted is the region from @var{start} and @var{end}. (These
+text inserted is the region between @var{start} and @var{end}. (These
arguments default to the beginning and end of the accessible portion of
that buffer.) This function returns @code{nil}.
programs.
@deffn Command insert-buffer from-buffer-or-name
-This command inserts the entire contents of @var{from-buffer-or-name}
-(which must exist) into the current buffer after point. It leaves
-the mark after the inserted text. The value is @code{nil}.
+This command inserts the entire accessible contents of
+@var{from-buffer-or-name} (which must exist) into the current buffer
+after point. It leaves the mark after the inserted text. The value
+is @code{nil}.
@end deffn
@deffn Command self-insert-command count
In an interactive call, @var{count} is the numeric prefix argument.
+Self-insertion translates the input character through
+@code{translation-table-for-input}. @xref{Translation of Characters}.
+
This command calls @code{auto-fill-function} whenever that is
non-@code{nil} and the character inserted is in the table
@code{auto-fill-chars} (@pxref{Auto Filling}).
@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
This command performs abbrev expansion if Abbrev mode is enabled and
the inserted character does not have word-constituent
-syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
-
-This is also responsible for calling @code{blink-paren-function} when
-the inserted character has close parenthesis syntax (@pxref{Blinking}).
+syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also
+responsible for calling @code{blink-paren-function} when the inserted
+character has close parenthesis syntax (@pxref{Blinking}).
Do not try substituting your own definition of
@code{self-insert-command} for the standard one. The editor command
is the numeric prefix argument.
@end deffn
-@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
-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.
-
-Programs hardly ever use this function.
-@end deffn
-
@defvar overwrite-mode
This variable controls whether overwrite mode is in effect. The value
should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
@node Deletion
@section Deleting Text
+@cindex text deletion
-@cindex deletion vs killing
+@cindex deleting text vs killing
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 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}.
+ All of the deletion functions operate on the current buffer.
@deffn Command erase-buffer
-This function deletes the entire text of the current buffer, leaving it
+This function deletes the entire text of the current buffer
+(@emph{not} just the accessible portion), leaving it
empty. If the buffer is read-only, it signals a @code{buffer-read-only}
error; if some of the text in it is read-only, it signals a
@code{text-read-only} error. Otherwise, it deletes the text without
asking for any confirmation. It returns @code{nil}.
Normally, deleting a large amount of text from a buffer inhibits further
-auto-saving of that buffer ``because it has shrunk''. However,
+auto-saving of that buffer ``because it has shrunk.'' However,
@code{erase-buffer} does not do this, the idea being that the future
text is not really related to the former text, and its size should not
be compared with that of the former text.
@end deffn
@defun delete-and-extract-region start end
-@tindex delete-and-extract-region
This function deletes the text between positions @var{start} and
@var{end} in the current buffer, and returns a string containing the
text just deleted.
@end deffn
@deffn Command delete-backward-char count &optional killp
-@cindex delete previous char
+@cindex deleting previous char
This command deletes @var{count} characters directly before point, or
after point if @var{count} is negative. If @var{killp} is
non-@code{nil}, then it saves the deleted characters in the kill ring.
This option specifies how @code{backward-delete-char-untabify} should
deal with whitespace. Possible values include @code{untabify}, the
default, meaning convert a tab to many spaces and delete one;
-@code{hungry}, meaning delete all the whitespace characters before point
-with one command, and @code{nil}, meaning do nothing special for
+@code{hungry}, meaning delete all tabs and spaces before point with
+one command; @code{all} meaning delete all tabs, spaces and newlines
+before point, and @code{nil}, meaning do nothing special for
whitespace characters.
@end defopt
commands intended primarily for the user but useful also in Lisp
programs.
-@deffn Command delete-horizontal-space
+@deffn Command delete-horizontal-space &optional backward-only
@cindex deleting whitespace
This function deletes all spaces and tabs around point. It returns
@code{nil}.
+If @var{backward-only} is non-@code{nil}, the function deletes
+spaces and tabs before point, but not after point.
+
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 line each time.
responsible for deciding whether to leave a space at the junction.
@end deffn
-@defun fixup-whitespace
-This function replaces all the whitespace surrounding point with either
-one space or no space, according to the context. It returns @code{nil}.
+@deffn Command fixup-whitespace
+This function replaces all the horizontal whitespace surrounding point
+with either one space or no space, according to the context. It
+returns @code{nil}.
At the beginning or end of a line, the appropriate amount of space is
none. Before a character with close parenthesis syntax, or after a
---------- Buffer: foo ----------
@end group
@end smallexample
-@end defun
+@end deffn
-@deffn Command just-one-space
+@deffn Command just-one-space &optional n
@comment !!SourceFile simple.el
This command replaces any spaces and tabs around point with a single
-space. It returns @code{nil}.
+space, or @var{n} spaces if @var{n} is specified. It returns
+@code{nil}.
@end deffn
@deffn Command delete-blank-lines
blank line with one or more blank lines before or after it, then all but
one of them are deleted. If point is on an isolated blank line, then it
is deleted. If point is on a nonblank line, the command deletes all
-blank lines following it.
+blank lines immediately following it.
A blank line is defined as a line containing only tabs and spaces.
Some people think this use of the word ``kill'' is unfortunate, since
it refers to operations that specifically @emph{do not} destroy the
-entities ``killed''. This is in sharp contrast to ordinary life, in
+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
term ``cut ring'' makes sense to people who, in pre-computer days, used
* Yanking:: How yanking is done.
* Yank Commands:: Commands that access the kill ring.
* Low-Level Kill Ring:: Functions and variables for kill ring access.
-* Internals of Kill Ring:: Variables that hold kill-ring data.
+* Internals of Kill Ring:: Variables that hold kill ring data.
@end menu
@node Kill Ring Concepts
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 kill-ring entry, which would be yanked as a
+succession build up a single kill ring entry, which would be yanked as a
unit; the second and subsequent consecutive kill commands add text to
the entry made by the first one.
commands to copy text from a read-only buffer into the kill ring.
If @var{yank-handler} is non-@code{nil}, this puts that value onto
-the string of killed text, as a @code{yank-handler} property.
-@xref{Yanking}.
+the string of killed text, as a @code{yank-handler} text property.
+@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, any
+@code{yank-handler} properties present on the killed text are copied
+onto the kill ring, like other text properties.
@end deffn
@defopt kill-read-only-ok
@deffn Command copy-region-as-kill start end
This command saves the region defined by @var{start} and @var{end} on
the kill ring (including text properties), but does not delete the text
-from the buffer. It returns @code{nil}. It also indicates the extent
-of the text copied by moving the cursor momentarily, or by displaying a
-message in the echo area.
+from the buffer. It returns @code{nil}.
The command does not set @code{this-command} to @code{kill-region}, so a
subsequent kill command does not append to the same kill ring entry.
@defun insert-for-yank string
This function normally works like @code{insert} except that it doesn't
insert the text properties in the @code{yank-excluded-properties}
-list. However, if the first character of @var{string} has a
-non-@code{nil}@code{yank-handler} text property, that property
-can do various special processing on the text being inserted.
+list. However, if any part of @var{string} has a non-@code{nil}
+@code{yank-handler} text property, that property can do various
+special processing on that part of the text being inserted.
@end defun
@defun insert-buffer-substring-as-yank buf &optional start end
@code{yank-excluded-properties} list.
@end defun
- You can put a @code{yank-handler} text property on the text to
-control how it will be inserted if it is yanked. The
-@code{insert-for-yank} function looks for a @code{yank-handler}
-property on the first character in its @var{string} argument. The
-property value must be a list of one to four elements, with the
-following format (where elements after the first may be omitted):
+ You can put a @code{yank-handler} text property on all or part of
+the text to control how it will be inserted if it is yanked. The
+@code{insert-for-yank} function looks for that property. The property
+value must be a list of one to four elements, with the following
+format (where elements after the first may be omitted):
@example
(@var{function} @var{param} @var{noexclude} @var{undo})
@table @var
@item function
-When @var{function} is present and non-nil, it is called instead of
+When @var{function} is present and non-@code{nil}, it is called instead of
@code{insert} to insert the string. @var{function} takes one
argument---the string to insert.
@item param
If @var{param} is present and non-@code{nil}, it replaces @var{string}
-as the object passed to @var{function} (or @code{insert}); for
-example, if @var{function} is @code{yank-rectangle}, @var{param}
-should be a list of strings to insert as a rectangle.
+(or the part of @var{string} being processed) as the object passed to
+@var{function} (or @code{insert}); for example, if @var{function} is
+@code{yank-rectangle}, @var{param} should be a list of strings to
+insert as a rectangle.
@item noexclude
If @var{noexclude} is present and non-@code{nil}, the normal removal of the
if @var{function} adjusts point before or after inserting the object.
@item undo
-If @var{undo} is present and non-nil, it is a function that will be
+If @var{undo} is present and non-@code{nil}, it is a function that will be
called by @code{yank-pop} to undo the insertion of the current object.
It is called with two arguments, the start and end of the current
region. @var{function} can set @code{yank-undo-function} to override
@comment node-name, next, previous, up
@subsection Functions for Yanking
- @dfn{Yanking} means reinserting an entry of previously killed text
-from the kill ring. The text properties are copied too.
+ This section describes higher-level commands for yanking, which are
+intended primarily for the user but useful also in Lisp programs.
+Both @code{yank} and @code{yank-pop} honor the
+@code{yank-excluded-properties} variable and @code{yank-handler} text
+property (@pxref{Yanking}).
@deffn Command yank &optional arg
@cindex inserting killed text
-This command inserts before point the text in the first entry in the
+This command inserts before point the text at the front of the
kill ring. It positions the mark at the beginning of that text, and
point at the end.
-If @var{arg} is a list (which occurs interactively when the user
-types @kbd{C-u} with no digits), then @code{yank} inserts the text as
-described above, but puts point before the yanked text and puts the mark
-after it.
+If @var{arg} is a non-@code{nil} list (which occurs interactively when
+the user types @kbd{C-u} with no digits), then @code{yank} inserts the
+text as described above, but puts point before the yanked text and
+puts the mark after it.
-If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
-recently killed text---the @var{arg}th element of the kill ring list.
+If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
+most recently killed text---the @var{arg}th element of the kill ring
+list, counted cyclically from the front, which is considered the
+first element for this purpose.
-@code{yank} does not alter the contents of the kill ring or rotate it.
-It returns @code{nil}.
+@code{yank} does not alter the contents of the kill ring, unless it
+used text provided by another program, in which case it pushes that text
+onto the kill ring. However if @var{arg} is an integer different from
+one, it rotates the kill ring to place the yanked string at the front.
+
+@code{yank} returns @code{nil}.
@end deffn
-@deffn Command yank-pop arg
+@deffn Command yank-pop &optional arg
This command replaces the just-yanked entry from the kill ring with a
different entry from the kill ring.
inserted by yanking. @code{yank-pop} deletes that text and inserts in
its place a different piece of killed text. It does not add the deleted
text to the kill ring, since it is already in the kill ring somewhere.
+It does however rotate the kill ring to place the newly yanked string at
+the front.
If @var{arg} is @code{nil}, then the replacement text is the previous
element of the kill ring. If @var{arg} is numeric, the replacement is
If this variable is non-@code{nil}, the function @code{yank-pop} uses
its value instead of @code{delete-region} to delete the text
inserted by the previous @code{yank} or
-@code{yank-pop} command.
+@code{yank-pop} command. The value must be a function of two
+arguments, the start and end of the current region.
The function @code{insert-for-yank} automatically sets this variable
according to the @var{undo} element of the @code{yank-handler}
If @var{n} is zero, indicating a request for the latest kill,
@code{current-kill} calls the value of
-@code{interprogram-paste-function} (documented below) before consulting
-the kill ring.
+@code{interprogram-paste-function} (documented below) before
+consulting the kill ring. If that value is a function and calling it
+returns a string, @code{current-kill} pushes that string onto the kill
+ring and returns it. It also sets the yanking pointer to point to
+that new entry, regardless of the value of @var{do-not-move}.
+Otherwise, @code{current-kill} does not treat a zero value for @var{n}
+specially: it returns the entry pointed at by the yanking pointer and
+does not move the yanking pointer.
@end defun
-@defun kill-new string &optional yank-handler
-This function puts the text @var{string} into the kill ring as a new
-entry at the front of the ring. It discards the oldest entry if
-appropriate. It also invokes the value of
+@defun kill-new string &optional replace yank-handler
+This function pushes the text @var{string} onto the kill ring and
+makes the yanking pointer point to it. It discards the oldest entry
+if appropriate. It also invokes the value of
@code{interprogram-cut-function} (see below).
+If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
+first element of the kill ring with @var{string}, rather than pushing
+@var{string} onto the kill ring.
+
If @var{yank-handler} is non-@code{nil}, this puts that value onto
the string of killed text, as a @code{yank-handler} property.
-@xref{Yanking}.
+@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, then
+@code{kill-new} copies any @code{yank-handler} properties present on
+@var{string} onto the kill ring, as it does with other text properties.
@end defun
@defun kill-append string before-p &optional yank-handler
This function appends the text @var{string} to the first entry in the
-kill ring. Normally @var{string} goes at the end of the entry, but if
+kill ring and makes the yanking pointer point to the combined entry.
+Normally @var{string} goes at the end of the entry, but if
@var{before-p} is non-@code{nil}, it goes at the beginning. This
-function also invokes the value of @code{interprogram-cut-function} (see
-below). This handles @var{yank-handler} just like @code{kill-new}.
+function also invokes the value of @code{interprogram-cut-function}
+(see below). This handles @var{yank-handler} just like
+@code{kill-new}, except that if @var{yank-handler} is different from
+the @code{yank-handler} property of the first entry of the kill ring,
+@code{kill-append} pushes the concatenated string onto the kill ring,
+instead of replacing the original first entry with it.
@end defun
@defvar interprogram-paste-function
@code{nil} or a function of no arguments.
If the value is a function, @code{current-kill} calls it to get the
-``most recent kill''. If the function returns a non-@code{nil} value,
-then that value is used as the ``most recent kill''. If it returns
-@code{nil}, then the first element of @code{kill-ring} is used.
+``most recent kill.'' If the function returns a non-@code{nil} value,
+then that value is used as the ``most recent kill.'' If it returns
+@code{nil}, then the front of the kill ring is used.
The normal use of this hook is to get the window system's primary
selection as the most recent kill, even if the selection belongs to
@defvar interprogram-cut-function
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.
+@code{nil} or a function of one required and one optional argument.
If the value is a function, @code{kill-new} and @code{kill-append} call
-it with the new first element of the kill ring as an argument.
+it with the new first element of the kill ring as the first argument.
+The second, optional, argument has the same meaning as the @var{push}
+argument to @code{x-set-cut-buffer} (@pxref{Definition of
+x-set-cut-buffer}) and only affects the second and later cut buffers.
The normal use of this hook is to set the window system's primary
-selection from the newly killed text. @xref{Window System Selections}.
+selection (and first cut buffer) from the newly killed text.
+@xref{Window System Selections}.
@end defvar
@node Internals of Kill Ring
@defopt kill-ring-max
The value of this variable is the maximum length to which the kill
ring can grow, before elements are thrown away at the end. The default
-value for @code{kill-ring-max} is 30.
+value for @code{kill-ring-max} is 60.
@end defopt
@node Undo
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
+assumes that undoing is not useful. In particular, any buffer whose
+name begins with a space has its undo recording off by default;
+see @ref{Buffer Names}.) 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.
-A value of @code{t} disables the recording of undo information.
+This buffer-local variable's value is the undo list of the current
+buffer. A value of @code{t} disables the recording of undo information.
@end defvar
Here are the kinds of elements an undo list can have:
@item (@var{text} . @var{position})
This kind of element indicates how to reinsert text that was deleted.
The deleted text itself is the string @var{text}. The place to
-reinsert it is @code{(abs @var{position})}.
+reinsert it is @code{(abs @var{position})}. If @var{position} is
+positive, point was at the beginning of the deleted text, otherwise it
+was at the end.
@item (t @var{high} . @var{low})
This kind of element indicates that an unmodified buffer became
@var{adjustment} character positions. Undoing this element moves
@var{marker} @minus{} @var{adjustment} characters.
+@item (apply @var{funname} . @var{args})
+This is an extensible undo item, which is undone by calling
+@var{funname} with arguments @var{args}.
+
+@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
+This is an extensible undo item, which records a change limited to the
+range @var{beg} to @var{end}, which increased the size of the buffer
+by @var{delta}. It is undone by calling @var{funname} with arguments
+@var{args}.
+
+This kind of element enables undo limited to a region to determine
+whether the element pertains to that region.
+
@item nil
This element is a boundary. The elements between two boundaries are
called a @dfn{change group}; normally, each change group corresponds to
undo individual replacements one by one.
@end defun
+@defvar undo-in-progress
+This variable is normally @code{nil}, but the undo commands bind it to
+@code{t}. This is so that various kinds of change hooks can tell when
+they're being called for the sake of undoing.
+@end defvar
+
@defun primitive-undo count list
This is the basic function for undoing elements of an undo list.
It undoes the first @var{count} elements of @var{list}, returning
-the rest of @var{list}. You could write this function in Lisp,
-but it is convenient to have it in C.
+the rest of @var{list}.
@code{primitive-undo} adds elements to the buffer's undo list when it
changes the buffer. Undo commands avoid confusion by saving the undo
undo operations use and update the saved value. The new elements added
by undoing are not part of this saved value, so they don't interfere with
continuing to undo.
+
+This function does not bind @code{undo-in-progress}.
@end defun
@node Maintaining Undo
You cannot specify any other buffer.
@end deffn
-@deffn Command buffer-disable-undo &optional buffer
-@deffnx Command buffer-flush-undo &optional buffer
-@cindex disable undo
-This function discards the undo list of @var{buffer}, and disables
+@deffn Command buffer-disable-undo &optional buffer-or-name
+@cindex disabling undo
+This function discards the undo list of @var{buffer-or-name}, and disables
further recording of undo information. As a result, it is no longer
possible to undo either previous changes or any subsequent changes. If
-the undo list of @var{buffer} is already disabled, this function
+the undo list of @var{buffer-or-name} is already disabled, this function
has no effect.
This function returns @code{nil}.
-
-The name @code{buffer-flush-undo} is not considered obsolete, but the
-preferred name is @code{buffer-disable-undo}.
@end deffn
As editing continues, undo lists get longer and longer. To prevent
them from using up all available memory space, garbage collection trims
them back to size limits you can set. (For this purpose, the ``size''
of an undo list measures the cons cells that make up the list, plus the
-strings of deleted text.) Two variables control the range of acceptable
-sizes: @code{undo-limit} and @code{undo-strong-limit}.
+strings of deleted text.) Three variables control the range of acceptable
+sizes: @code{undo-limit}, @code{undo-strong-limit} and
+@code{undo-outer-limit}. In these variables, size is counted as the
+number of bytes occupied, which includes both saved text and other
+data.
-@defvar undo-limit
+@defopt undo-limit
This is the soft limit for the acceptable size of an undo list. The
change group at which this size is exceeded is the last one kept.
-@end defvar
+@end defopt
-@defvar undo-strong-limit
+@defopt undo-strong-limit
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 no matter how big it is.
-@end defvar
+change group is only discarded if it exceeds @code{undo-outer-limit}.
+@end defopt
+
+@defopt undo-outer-limit
+If at garbage collection time the undo info for the current command
+exceeds this limit, Emacs discards the info and displays a warning.
+This is a last ditch limit to prevent memory overflow.
+@end defopt
+
+@defopt undo-ask-before-discard
+If this variable is non-@code{nil}, when the undo info exceeds
+@code{undo-outer-limit}, Emacs asks in the echo area whether to
+discard the info. The default value is @code{nil}, which means to
+discard it automatically.
+
+This option is mainly intended for debugging. Garbage collection is
+inhibited while the question is asked, which means that Emacs might
+leak memory if the user waits too long before answering the question.
+@end defopt
@node Filling
@comment node-name, next, previous, up
@section Filling
-@cindex filling, explicit
+@cindex filling text
@dfn{Filling} means adjusting the lengths of lines (by moving the line
breaks) so that they are nearly (but no greater than) a specified
argument implies the value @code{full} for @var{justify}.
@deffn Command fill-paragraph justify
-@cindex filling a paragraph
This command fills the paragraph at or after point. If
@var{justify} is non-@code{nil}, each line is justified as well.
It uses the ordinary paragraph motion commands to find paragraph
between paragraphs are removed. This function justifies as well as
filling when @var{justify} is non-@code{nil}.
-In an interactive call, any prefix argument requests justification.
-
If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
other than line breaks untouched. If @var{squeeze-after} is
non-@code{nil}, it specifies a position in the region, and means don't
follow specified justification style (see @code{current-justification},
below). @code{nil} means to do full justification.
-If @var{eop} is non-@code{nil}, that means do left-justification if
-@code{current-justification} specifies full justification. This is used
-for the last line of a paragraph; even if the paragraph as a whole is
-fully justified, the last line should not be.
+If @var{eop} is non-@code{nil}, that means do only left-justification
+if @code{current-justification} specifies full justification. This is
+used for the last line of a paragraph; even if the paragraph as a
+whole is fully justified, the last line should not be.
If @var{nosqueeze} is non-@code{nil}, that means do not change interior
whitespace.
@defun current-justification
This function returns the proper justification style to use for filling
the text around point.
+
+This returns the value of the @code{justification} text property at
+point, or the variable @var{default-justification} if there is no such
+text property. However, it returns @code{nil} rather than @code{none}
+to mean ``don't justify''.
@end defun
@defopt sentence-end-double-space
+@anchor{Definition of sentence-end-double-space}
If this variable is non-@code{nil}, a period followed by just one space
does not count as the end of a sentence, and the filling functions
avoid breaking the line at such a place.
@end defopt
+@defopt sentence-end-without-period
+If this variable is non-@code{nil}, a sentence can end without a
+period. This is used for languages like Thai, where sentences end
+with a double space but without a period.
+@end defopt
+
+@defopt sentence-end-without-space
+If this variable is non-@code{nil}, it should be a string of
+characters that can end a sentence without following spaces.
+@end defopt
+
@defvar fill-paragraph-function
This variable provides a way for major modes to override the filling of
paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
@section Margins for Filling
@defopt fill-prefix
-This buffer-local 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.
+This buffer-local variable, if non-@code{nil}, 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.
The fill prefix follows the left margin whitespace, if any.
@end defopt
@end defvar
@defvar fill-nobreak-predicate
-This variable gives major modes a way to specify not to break a line at
-certain places. Its value should be a function. This function is
-called during filling, with no arguments and with point located at the
-place where a break is being considered. If the function returns
+This variable gives major modes a way to specify not to break a line
+at certain places. Its value should be a list of functions. Whenever
+filling considers breaking the line at a certain place in the buffer,
+it calls each of these functions with no arguments and with point
+located at that place. If any of the functions returns
non-@code{nil}, then the line won't be broken there.
@end defvar
@node Adaptive Fill
@section Adaptive Fill Mode
-@cindex Adaptive Fill mode
+@c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent.
- Adaptive Fill mode chooses a fill prefix automatically from the text
-in each paragraph being filled.
+ When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
+prefix automatically from the text in each paragraph being filled
+rather than using a predetermined value. During filling, this fill
+prefix gets inserted at the start of the second and subsequent lines
+of the paragraph as described in @ref{Filling}, and in @ref{Auto
+Filling}.
@defopt adaptive-fill-mode
Adaptive Fill mode is enabled when this variable is non-@code{nil}.
@defun fill-context-prefix from to
This function implements the heart of Adaptive Fill mode; it chooses a
-fill prefix based on the text between @var{from} and @var{to}. It does
-this by looking at the first two lines of the paragraph, based on the
-variables described below.
+fill prefix based on the text between @var{from} and @var{to},
+typically the start and end of a paragraph. It does this by looking
+at the first two lines of the paragraph, based on the variables
+described below.
@c The optional argument first-line-regexp is not documented
@c because it exists for internal purposes and might be eliminated
@c in the future.
+
+Usually, this function returns the fill prefix, a string. However,
+before doing this, the function makes a final check (not specially
+mentioned in the following) that a line starting with this prefix
+wouldn't look like the start of a paragraph. Should this happen, the
+function signals the anomaly by returning @code{nil} instead.
+
+In detail, @code{fill-context-prefix} does this:
+
+@enumerate
+@item
+It takes a candidate for the fill prefix from the first line---it
+tries first the function in @code{adaptive-fill-function} (if any),
+then the regular expression @code{adaptive-fill-regexp} (see below).
+The first non-@code{nil} result of these, or the empty string if
+they're both @code{nil}, becomes the first line's candidate.
+@item
+If the paragraph has as yet only one line, the function tests the
+validity of the prefix candidate just found. The function then
+returns the candidate if it's valid, or a string of spaces otherwise.
+(see the description of @code{adaptive-fill-first-line-regexp} below).
+@item
+When the paragraph already has two lines, the function next looks for
+a prefix candidate on the second line, in just the same way it did for
+the first line. If it doesn't find one, it returns @code{nil}.
+@item
+The function now compares the two candidate prefixes heuristically: if
+the non-whitespace characters in the line 2 candidate occur in the
+same order in the line 1 candidate, the function returns the line 2
+candidate. Otherwise, it returns the largest initial substring which
+is common to both candidates (which might be the empty string).
+@end enumerate
@end defun
@defopt adaptive-fill-regexp
-This variable holds a regular expression to control Adaptive Fill mode.
Adaptive Fill mode matches this regular expression against the text
starting after the left margin whitespace (if any) on a line; the
characters it matches are that line's candidate for the fill prefix.
+
+The default value matches whitespace with certain punctuation
+characters intermingled.
@end defopt
@defopt adaptive-fill-first-line-regexp
-In a one-line paragraph, if the candidate fill prefix matches this
-regular expression, or if it matches @code{comment-start-skip}, then it
-is used---otherwise, spaces amounting to the same width are used
-instead.
-
-However, the fill prefix is never taken from a one-line paragraph
-if it would act as a paragraph starter on subsequent lines.
+Used only in one-line paragraphs, this regular expression acts as an
+additional check of the validity of the one available candidate fill
+prefix: the candidate must match this regular expression, or match
+@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix}
+replaces the candidate with a string of spaces ``of the same width''
+as it.
+
+The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
+matches only a string of whitespace. The effect of this default is to
+force the fill prefixes found in one-line paragraphs always to be pure
+whitespace.
@end defopt
@defopt adaptive-fill-function
You can specify more complex ways of choosing a fill prefix
automatically by setting this variable to a function. The function is
-called when @code{adaptive-fill-regexp} does not match, with point after
-the left margin of a line, and it should return the appropriate fill
-prefix based on that line. If it returns @code{nil}, that means it sees
-no fill prefix in that line.
+called with point after the left margin (if any) of a line, and it
+must preserve point. It should return either ``that line's'' fill
+prefix or @code{nil}, meaning it has failed to determine a prefix.
@end defopt
@node Auto Filling
justification style to refill portions of the text. @xref{Margins}.
@defvar auto-fill-function
-The value of this variable should be a function (of no arguments) to be
-called after self-inserting a character from the table
+The value of this buffer-local variable should be a function (of no
+arguments) to be called after self-inserting a character from the table
@code{auto-fill-chars}. It may be @code{nil}, in which case nothing
special is done in that case.
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
+@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
This function is the general text-sorting routine that subdivides a
buffer into records and then sorts them. Most of the commands in this
section use this function.
non-@code{nil} value.
@end enumerate
+The argument @var{predicate} is the function to use to compare keys.
+If keys are numbers, it defaults to @code{<}; otherwise it defaults to
+@code{string<}.
+
As an example of @code{sort-subr}, here is the complete function
definition for @code{sort-lines}:
BEG and END (region to sort).
The variable `sort-fold-case' determines\
whether alphabetic case affects
-the sort order.
+the sort order."
@end group
@group
(interactive "P\nr")
(save-restriction
(narrow-to-region beg end)
(goto-char (point-min))
- (sort-subr reverse 'forward-line 'end-of-line))))
+ (let ((inhibit-field-text-motion t))
+ (sort-subr reverse 'forward-line 'end-of-line)))))
@end group
@end example
@deffn Command sort-numeric-fields field start end
This command sorts lines in the region between @var{start} and
-@var{end}, comparing them numerically by the @var{field}th field of each
-line. The specified field must contain a number in each line of the
-region. Fields are separated by whitespace and numbered starting from
-1. If @var{field} is negative, sorting is by the
-@w{@minus{}@var{field}th} field from the end of the line. This command
-is useful for sorting tables.
+@var{end}, comparing them numerically by the @var{field}th field of
+each line. Fields are separated by whitespace and numbered starting
+from 1. The specified field must contain a number in each line of the
+region. Numbers starting with 0 are treated as octal, and numbers
+starting with @samp{0x} are treated as hexadecimal.
+
+If @var{field} is negative, sorting is by the
+@w{@minus{}@var{field}th} field from the end of the line. This
+command is useful for sorting tables.
@end deffn
+@defopt sort-numeric-base
+This variable specifies the default radix for
+@code{sort-numeric-fields} to parse numbers.
+@end defopt
+
@deffn Command sort-columns reverse &optional beg end
This command sorts the lines in the region between @var{beg} and
-@var{end}, comparing them alphabetically by a certain range of columns.
-The column positions of @var{beg} and @var{end} bound the range of
-columns to sort on.
+@var{end}, comparing them alphabetically by a certain range of
+columns. The column positions of @var{beg} and @var{end} bound the
+range of columns to sort on.
If @var{reverse} is non-@code{nil}, the sort is in reverse order.
containing position @var{beg}, and the entire line containing position
@var{end}, are included in the region sorted.
-Note that @code{sort-columns} uses the @code{sort} utility program,
-and so cannot work properly on text containing tab characters. Use
-@kbd{M-x untabify} to convert tabs to spaces before sorting.
+Note that @code{sort-columns} rejects text that contains tabs, because
+tabs could be split across the specified columns. Use @kbd{M-x
+untabify} to convert tabs to spaces before sorting.
+
+When possible, this command actually works by calling the @code{sort}
+utility program.
@end deffn
@node Columns
Column number computations ignore the width of the window and the
amount of horizontal scrolling. Consequently, a column value can be
-arbitrarily high. The first (or leftmost) column is numbered 0.
+arbitrarily high. The first (or leftmost) column is numbered 0. They
+also ignore overlays and text properties, aside from invisibility.
@defun current-column
This function returns the horizontal position of point, measured in
affect the display of tab characters in the buffer (@pxref{Usual
Display}). Note that the @key{TAB} character as input uses this tab
stop feature only in a few major modes, such as Text mode.
+@xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
@deffn Command tab-to-tab-stop
This command inserts spaces or tabs before point, up to the next tab
@code{nil}.
@end deffn
-@deffn Command backward-to-indentation arg
+@deffn Command backward-to-indentation &optional arg
@comment !!SourceFile simple.el
This command moves point backward @var{arg} lines and then to the
first nonblank character on that line. It returns @code{nil}.
+If @var{arg} is omitted or @code{nil}, it defaults to 1.
@end deffn
-@deffn Command forward-to-indentation arg
+@deffn Command forward-to-indentation &optional arg
@comment !!SourceFile simple.el
This command moves point forward @var{arg} lines and then to the first
nonblank character on that line. It returns @code{nil}.
+If @var{arg} is omitted or @code{nil}, it defaults to 1.
@end deffn
@node Case Changes
Lists}). The properties belong to a particular character at a
particular place, such as, the letter @samp{T} at the beginning of this
sentence or the first @samp{o} in @samp{foo}---if the same character
-occurs in two different places, the two occurrences generally have
+occurs in two different places, the two occurrences in general have
different properties.
Each property has a name and a value. Both of these can be any Lisp
-object, but the name is normally a symbol. The usual way to access the
-property list is to specify a name and ask what value corresponds to it.
+object, but the name is normally a symbol. Typically each property
+name symbol is used for a particular purpose; for instance, the text
+property @code{face} specifies the faces for displaying the character
+(@pxref{Special Properties}). The usual way to access the property
+list is to specify a name and ask what value corresponds to it.
If a character has a @code{category} property, we call it the
-@dfn{category} of the character. It should be a symbol. The properties
-of the symbol serve as defaults for the properties of the character.
+@dfn{property category} of the character. It should be a symbol. The
+properties of the symbol serve as defaults for the properties of the
+character.
Copying text between strings and buffers preserves the properties
along with the characters; this includes such diverse functions as
only when text is examined.
* Clickable Text:: Using text properties to make regions of text
do something when you click on them.
+* Links and Mouse-1:: How to make @key{Mouse-1} follow a link.
* Fields:: The @code{field} property defines
fields within the buffer.
* Not Intervals:: Why text properties do not use
current buffer.
If there is no @var{prop} property strictly speaking, but the character
-has a category that is a symbol, then @code{get-text-property} returns
+has a property category that is a symbol, then @code{get-text-property} returns
the @var{prop} property of that symbol.
@end defun
-@defun get-char-property pos prop &optional object
+@defun get-char-property position prop &optional object
This function is like @code{get-text-property}, except that it checks
overlays first and then text properties. @xref{Overlays}.
overlays.
@end defun
+@defun get-char-property-and-overlay position prop &optional object
+This is like @code{get-char-property}, but gives extra information
+about the overlay that the property value comes from.
+
+Its value is a cons cell whose @sc{car} is the property value, the
+same value @code{get-char-property} would return with the same
+arguments. Its @sc{cdr} is the overlay in which the property was
+found, or @code{nil}, if it was found as a text property or not found
+at all.
+
+If @var{position} is at the end of @var{object}, both the @sc{car} and
+the @sc{cdr} of the value are @code{nil}.
+@end defun
+
@defvar char-property-alias-alist
This variable holds an alist which maps property names to a list of
alternative property names. If a character does not specify a direct
@end defun
@defun remove-list-of-text-properties start end list-of-properties &optional object
-Like @code{remove-list-properties} except that
-@var{list-of-properties} is a list property names only, not an
-alternating list of property values.
+Like @code{remove-text-properties} except that
+@var{list-of-properties} is a list of property names only, not an
+alternating list of property names and values.
@end defun
@defun set-text-properties start end props &optional object
@example
(set-text-properties @var{start} @var{end} nil)
@end example
+
+Do not rely on the return value of this function.
@end defun
The easiest way to make a string with text properties
is with @code{propertize}:
@defun propertize string &rest properties
-@tindex propertize
This function returns a copy of @var{string} which has the text
properties @var{properties}. These properties apply to all the
characters in the string that is returned. Here is an example that
@end smallexample
@end defun
+@defun previous-property-change pos &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}.
+@end defun
+
@defun next-single-property-change pos prop &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 the @var{prop}
-property, then returns the position of the change. In other words, it
-returns the position of the first character beyond @var{pos} whose
-@var{prop} property differs from that of the character just after
-@var{pos}.
+The function scans text for a change in the @var{prop} property, then
+returns the position of the change. The scan goes forward from
+position @var{pos} in the string or buffer @var{object}. In other
+words, this function returns the position of the first character
+beyond @var{pos} whose @var{prop} property differs from that of the
+character just after @var{pos}.
If @var{limit} is non-@code{nil}, then the scan ends at position
@var{limit}. If there is no property change before that point,
equals @var{pos} only if @var{limit} equals @var{pos}.
@end defun
-@defun previous-property-change pos &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}.
-@end defun
-
@defun previous-single-property-change pos prop &optional object limit
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
@end defun
@defun next-single-char-property-change pos prop &optional object limit
-@tindex next-single-char-property-change
This is like @code{next-single-property-change} except that it
considers overlay properties as well as text properties, and if no
change is found before the end of the @var{object}, it returns the
@end defun
@defun previous-single-char-property-change pos prop &optional object limit
-@tindex previous-single-char-property-change
This is like @code{next-single-char-property-change}, but scans back
from @var{pos} instead of forward, and returns the minimum valid
position in @var{object} if no change is found.
have no standard meaning, and you can use them as you like.
@table @code
-@cindex category of text character
+@cindex property category of text character
@kindex category @r{(text property)}
@item category
If a character has a @code{category} property, we call it the
-@dfn{category} of the character. It should be a symbol. The properties
-of the symbol serve as defaults for the properties of the character.
+@dfn{property category} of the character. It should be a symbol. The
+properties of this symbol serve as defaults for the properties of the
+character.
@item face
@cindex face codes of text
A face name (a symbol or string).
@item
-Starting in Emacs 21, a property list of face attributes. This has the
+A property list of face attributes. This has the
form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
face attribute name and @var{value} is a meaningful value for that
attribute. With this feature, you do not need to create a face each
@xref{Face Attributes}.
@item
-A cons cell of the form @code{(foreground-color . @var{color-name})} or
+A cons cell with the form @code{(foreground-color . @var{color-name})} or
@code{(background-color . @var{color-name})}. These elements specify
-just the foreground color or just the background color.
+just the foreground color or just the background color. @xref{Color
+Names}, for the supported forms of @var{color-name}.
-@code{(foreground-color . @var{color-name})} is equivalent to
-@code{(:foreground @var{color-name})}, and likewise for the background.
+A cons cell of @code{(foreground-color . @var{color-name})} is equivalent to
+specifying @code{(:foreground @var{color-name})}; likewise for the
+background.
@end itemize
You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
property; rather, it is implemented in Font Lock mode using
@code{char-property-alias-alist}. @xref{Examining Properties}.
-This property is new in Emacs 21.4.
+This property is new in Emacs 22.1.
@item mouse-face
@kindex mouse-face @r{(text property)}
@item fontified
@kindex fontified @r{(text property)}
-This property, if non-@code{nil}, says that text in the buffer has
-had faces assigned automatically by a feature such as Font-Lock mode.
-@xref{Auto Faces}.
+This property says whether the character has a face assigned to it by font
+locking. The display engine tests it to decide whether a buffer
+portion needs refontifying before display. @xref{Auto Faces}. It
+takes one of three values:
+
+@table @asis
+@item @code{nil}
+Font locking is disabled, or the character's @code{face} property, if
+any, is invalid.
+
+@item @code{defer}
+This value is only used when ``just in time'' font locking is enabled
+and it means that the character's @code{face} property is invalid and
+needs deferred fontification.
+
+@item @code{t}
+The character's @code{face} property, or absence of one, is valid.
+@end table
@item display
-@kindex display @r{(text property)}
This property activates various features that change the
way text is displayed. For example, it can make text appear taller
or shorter, higher or lower, wider or narrow, or replaced with an image.
If the value of the @code{help-echo} property is a function, that
function is called with three arguments, @var{window}, @var{object} and
-@var{position} and should return a help string or @var{nil} for
+@var{pos} and should return a help string or @code{nil} for
none. The first argument, @var{window} is the window in which
the help was found. The second, @var{object}, is the buffer, overlay or
-string which had the @code{help-echo} property. The @var{position}
+string which had the @code{help-echo} property. The @var{pos}
argument is as follows:
@itemize @bullet{}
@item
-If @var{object} is a buffer, @var{pos} is the position in the buffer
-where the @code{help-echo} text property was found.
+If @var{object} is a buffer, @var{pos} is the position in the buffer.
@item
If @var{object} is an overlay, that overlay has a @code{help-echo}
-property, and @var{pos} is the position in the overlay's buffer under
-the mouse.
+property, and @var{pos} is the position in the overlay's buffer.
@item
If @var{object} is a string (an overlay string or a string displayed
with the @code{display} property), @var{pos} is the position in that
-string under the mouse.
+string.
@end itemize
If the value of the @code{help-echo} property is neither a function nor
@cindex keymap of character
@kindex keymap @r{(text property)}
The @code{keymap} property specifies an additional keymap for
-commands. The property's value for the character before point applies
-if it is non-@code{nil} and rear-sticky, and the property's value for
-the character after point applies if it is non-@code{nil} and
-front-sticky. When the value applies, it is used for key lookup
-before the buffer's local map. (For mouse clicks, the position of the
-click is used instead of the position of point.) If the property
-value is a symbol, the symbol's function definition is used as the
-keymap. @xref{Active Keymaps}.
+commands. When this keymap applies, it is used for key lookup before
+the minor mode keymaps and before the buffer's local map.
+@xref{Active Keymaps}. If the property value is a symbol, the
+symbol's function definition is used as the keymap.
+
+The property's value for the character before point applies if it is
+non-@code{nil} and rear-sticky, and the property's value for the
+character after point applies if it is non-@code{nil} and
+front-sticky. (For mouse clicks, the position of the click is used
+instead of the position of point.)
@item local-map
@kindex local-map @r{(text property)}
This property works like @code{keymap} except that it specifies a
keymap to use @emph{instead of} the buffer's local map. For most
-purposes (perhaps all purposes), the @code{keymap} is superior.
+purposes (perhaps all purposes), it is better to use the @code{keymap}
+property.
@item syntax-table
The @code{syntax-table} property overrides what the syntax table says
@kindex read-only @r{(text property)}
If a character has the property @code{read-only}, then modifying that
character is not allowed. Any command that would do so gets an error,
-@code{text-read-only}.
+@code{text-read-only}. If the property value is a string, that string
+is used as the error message.
Insertion next to a read-only character is an error if inserting
ordinary text there would inherit the @code{read-only} property due to
@code{beginning-of-line} stop moving at a field boundary.
@xref{Fields}.
+@item cursor
+@kindex cursor @r{(text property)}
+Normally, the cursor is displayed at the end of any overlay and text
+property strings present at the current window position. You can
+place the cursor on any desired character of these strings by giving
+that character a non-@code{nil} @var{cursor} text property.
+
+@item pointer
+@kindex pointer @r{(text property)}
+This specifies a specific pointer shape when the mouse pointer is over
+this text or image. @xref{Pointer Shape}, for possible pointer
+shapes.
+
+@item line-spacing
+@kindex line-spacing @r{(text property)}
+A newline can have a @code{line-spacing} text or overlay property that
+controls the height of the display line ending with that newline. The
+property value overrides the default frame line spacing and the buffer
+local @code{line-spacing} variable. @xref{Line Height}.
+
+@item line-height
+@kindex line-height @r{(text property)}
+A newline can have a @code{line-height} text or overlay property that
+controls the total height of the display line ending in that newline.
+@xref{Line Height}.
+
@item modification-hooks
@cindex change hooks for a character
@cindex hooks for changing a character
being modified by a single primitive, you can't predict how many times
the function will be called.
+If these functions modify the buffer, they should bind
+@code{inhibit-modification-hooks} to @code{t} around doing so, to
+avoid confusing the internal mechanism that calls these hooks.
+
@item insert-in-front-hooks
@itemx insert-behind-hooks
@kindex insert-in-front-hooks @r{(text property)}
@code{point-left} functions are called first, followed by all the
@code{point-entered} functions.
-It is possible using @code{char-after} to examine characters at various
-positions without moving point to those positions. Only an actual
-change in the value of point runs these hook functions.
+It is possible with @code{char-after} to examine characters at various
+buffer positions without moving point to those positions. Only an
+actual change in the value of point runs these hook functions.
@end table
@defvar inhibit-point-motion-hooks
@end defvar
@defvar show-help-function
-@tindex show-help-function
@anchor{Help display} If this variable is non-@code{nil}, it specifies a
function called to display help strings. These may be @code{help-echo}
properties, menu help strings (@pxref{Simple Menu Items},
@item hard
If a newline character has this property, it is a ``hard'' newline.
The fill commands do not alter hard newlines and do not move words
-across them. However, this property takes effect only if the variable
-@code{use-hard-newlines} is non-@code{nil}.
+across them. However, this property takes effect only if the
+@code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft
+Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
@item right-margin
This property specifies an extra right margin for filling this part of the
list.
@defvar text-property-default-nonsticky
-@tindex text-property-default-nonsticky
This variable holds an alist which defines the default rear-stickiness
of various text properties. Each element has the form
@code{(@var{property} . @var{nonstickiness})}, and it defines the
@code{buffer-access-fontified-property}.
@defvar buffer-access-fontified-property
-If this value's variable is non-@code{nil}, it is a symbol which is used
+If this variable's value is non-@code{nil}, it is a symbol which is used
as a text property name. A non-@code{nil} value for that text property
means, ``the other text properties for this character have already been
computed.''
@subsection Defining Clickable Text
@cindex clickable text
- There are two ways to set up @dfn{clickable text} in a buffer.
-There are typically two parts of this: to make the text highlight
-when the mouse is over it, and to make a mouse button do something
-when you click it on that part of the text.
-
- Highlighting is done with the @code{mouse-face} text property.
+ @dfn{Clickable text} is text that can be clicked, with either the
+the mouse or via keyboard commands, to produce some result. Many
+major modes use clickable text to implement features such as
+hyper-links. The @code{button} package provides an easy way to insert
+and manipulate clickable text. @xref{Buttons}.
+
+ In this section, we will explain how to manually set up clickable
+text in a buffer using text properties. This involves two things: (1)
+indicating clickability when the mouse moves over the text, and (2)
+making @kbd{RET} or a mouse click on that text do something.
+
+ Indicating clickability usually involves highlighting the text, and
+often involves displaying helpful information about the action, such
+as which mouse button to press, or a short summary of the action.
+This can be done with the @code{mouse-face} and @code{help-echo}
+text properties. @xref{Special Properties}.
Here is an example of how Dired does it:
@smallexample
(condition-case nil
(if (dired-move-to-filename)
- (put-text-property (point)
- (save-excursion
- (dired-move-to-end-of-filename)
- (point))
- 'mouse-face 'highlight))
+ (add-text-properties
+ (point)
+ (save-excursion
+ (dired-move-to-end-of-filename)
+ (point))
+ '(mouse-face highlight
+ help-echo "mouse-2: visit this file in other window")))
(error nil))
@end smallexample
@noindent
-The first two arguments to @code{put-text-property} specify the
+The first two arguments to @code{add-text-properties} specify the
beginning and end of the text.
The usual way to make the mouse do something when you click it
@smallexample
(defun dired-mouse-find-file-other-window (event)
- "In dired, visit the file or directory name you click on."
+ "In Dired, visit the file or directory name you click on."
(interactive "e")
- (let (file)
+ (let (window pos file)
(save-excursion
- (set-buffer (window-buffer (posn-window (event-end event))))
- (save-excursion
- (goto-char (posn-point (event-end event)))
- (setq file (dired-get-filename))))
- (select-window (posn-window (event-end event)))
- (find-file-other-window (file-name-sans-versions file t))))
+ (setq window (posn-window (event-end event))
+ pos (posn-point (event-end event)))
+ (if (not (windowp window))
+ (error "No file chosen"))
+ (set-buffer (window-buffer window))
+ (goto-char pos)
+ (setq file (dired-get-file-for-visit)))
+ (if (file-directory-p file)
+ (or (and (cdr dired-subdir-alist)
+ (dired-goto-subdir file))
+ (progn
+ (select-window window)
+ (dired-other-window file)))
+ (select-window window)
+ (find-file-other-window (file-name-sans-versions file t)))))
@end smallexample
@noindent
-The reason for the outer @code{save-excursion} construct is to avoid
-changing the current buffer; the reason for the inner one is to avoid
-permanently altering point in the buffer you click on. In this case,
-Dired uses the function @code{dired-get-filename} to determine which
-file to visit, based on the position found in the event.
+The reason for the @code{save-excursion} construct is to avoid
+changing the current buffer. In this case,
+Dired uses the functions @code{posn-window} and @code{posn-point}
+to determine which buffer the click happened in and where, and
+in that buffer, @code{dired-get-file-for-visit} to determine which
+file to visit.
Instead of defining a mouse command for the major mode, you can define
a key binding for the clickable text itself, using the @code{keymap}
global definition) remains available for the rest of the text in the
buffer.
+@node Links and Mouse-1
+@subsection Links and Mouse-1
+@cindex follow links
+@cindex mouse-1
+
+ The normal Emacs command for activating text in read-only buffers is
+@key{Mouse-2}, which includes following textual links. However, most
+graphical applications use @key{Mouse-1} for following links. For
+compatibility, @key{Mouse-1} follows links in Emacs too, when you
+click on a link quickly without moving the mouse. The user can
+customize this behavior through the variable
+@code{mouse-1-click-follows-link}.
+
+ To define text as a link at the Lisp level, you should bind the
+@code{mouse-2} event to a command to follow the link. Then, to indicate that
+@key{Mouse-1} should also follow the link, you should specify a
+@code{follow-link} condition either as a text property or as a key
+binding:
+
+@table @asis
+@item @code{follow-link} property
+If the clickable text has a non-@code{nil} @code{follow-link} text or overlay
+property, that specifies the condition.
+
+@item @code{follow-link} event
+If there is a binding for the @code{follow-link} event, either on the
+clickable text or in the local keymap, the binding is the condition.
+@end table
+
+ Regardless of how you set the @code{follow-link} condition, its
+value is used as follows to determine whether the given position is
+inside a link, and (if so) to compute an @dfn{action code} saying how
+@key{Mouse-1} should handle the link.
+
+@table @asis
+@item @code{mouse-face}
+If the condition is @code{mouse-face}, a position is inside a link if
+there is a non-@code{nil} @code{mouse-face} property at that position.
+The action code is always @code{t}.
+
+For example, here is how Info mode handles @key{Mouse-1}:
+
+@smallexample
+(define-key Info-mode-map [follow-link] 'mouse-face)
+@end smallexample
+
+@item a function
+If the condition is a valid function, @var{func}, then a position
+@var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates
+to non-@code{nil}. The value returned by @var{func} serves as the
+action code.
+
+For example, here is how pcvs enables @key{Mouse-1} to follow links on
+file names only:
+
+@smallexample
+(define-key map [follow-link]
+ (lambda (pos)
+ (eq (get-char-property pos 'face) 'cvs-filename-face)))
+@end smallexample
+
+@item anything else
+If the condition value is anything else, then the position is inside a
+link and the condition itself is the action code. Clearly you should
+only specify this kind of condition on the text that constitutes a
+link.
+@end table
+
+@noindent
+The action code tells @key{Mouse-1} how to follow the link:
+
+@table @asis
+@item a string or vector
+If the action code is a string or vector, the @key{Mouse-1} event is
+translated into the first element of the string or vector; i.e., the
+action of the @key{Mouse-1} click is the local or global binding of
+that character or symbol. Thus, if the action code is @code{"foo"},
+@key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
+@key{Mouse-1} translates into @key{foo}.
+
+@item anything else
+For any other non-@code{nil} action code, the @code{mouse-1} event is
+translated into a @code{mouse-2} event at the same position.
+@end table
+
+ To define @key{Mouse-1} to activate a button defined with
+@code{define-button-type}, give the button a @code{follow-link}
+property with a value as specified above to determine how to follow
+the link. For example, here is how Help mode handles @key{Mouse-1}:
+
+@smallexample
+(define-button-type 'help-xref
+ 'follow-link t
+ 'action #'help-button-action)
+@end smallexample
+
+ To define @key{Mouse-1} on a widget defined with
+@code{define-widget}, give the widget a @code{:follow-link} property
+with a value as specified above to determine how to follow the link.
+
+For example, here is how the @code{link} widget specifies that
+a @key{Mouse-1} click shall be translated to @key{RET}:
+
+@smallexample
+(define-widget 'link 'item
+ "An embedded link."
+ :button-prefix 'widget-link-prefix
+ :button-suffix 'widget-link-suffix
+ :follow-link "\C-m"
+ :help-echo "Follow the link."
+ :format "%[%t%]")
+@end smallexample
+
+@defun mouse-on-link-p pos
+This function returns non-@code{nil} if position @var{pos} in the
+current buffer is on a link. @var{pos} can also be a mouse event
+location, as returned by @code{event-start} (@pxref{Accessing Events}).
+@end defun
+
@node Fields
@subsection Defining and Using Fields
@cindex fields
to an empty field whose beginning and end are both at @var{pos}.
In all of these functions, if @var{pos} is omitted or @code{nil}, the
-value of point is used by default.
+value of point is used by default. If narrowing is in effect, then
+@var{pos} should fall within the accessible portion. @xref{Narrowing}.
@defun field-beginning &optional pos escape-from-edge limit
-@tindex field-beginning
This function returns the beginning of the field specified by @var{pos}.
If @var{pos} is at the beginning of its field, and
@end defun
@defun field-end &optional pos escape-from-edge limit
-@tindex field-end
This function returns the end of the field specified by @var{pos}.
If @var{pos} is at the end of its field, and @var{escape-from-edge} is
@end defun
@defun field-string &optional pos
-@tindex field-string
This function returns the contents of the field specified by @var{pos},
as a string.
@end defun
@defun field-string-no-properties &optional pos
-@tindex field-string-no-properties
This function returns the contents of the field specified by @var{pos},
as a string, discarding text properties.
@end defun
@defun delete-field &optional pos
-@tindex delete-field
This function deletes the text of the field specified by @var{pos}.
@end defun
@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
-@tindex constrain-to-field
This function ``constrains'' @var{new-pos} to the field that
@var{old-pos} belongs to---in other words, it returns the position
closest to @var{new-pos} that is in the same field as @var{old-pos}.
If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
-the value of point instead, and moves point to the resulting position.
+the value of point instead, and moves point to the resulting position
+as well as returning it.
If @var{old-pos} is at the boundary of two fields, then the acceptable
-positions for @var{new-pos} depend on the value of the optional argument
-@var{escape-from-edge}. If @var{escape-from-edge} is @code{nil}, then
-@var{new-pos} is constrained to the field that has the same @code{field}
-property (either a text-property or an overlay property) that new
-characters inserted at @var{old-pos} would get. (This depends on the
+final positions depend on the argument @var{escape-from-edge}. If
+@var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in
+the field whose @code{field} property equals what new characters
+inserted at @var{old-pos} would inherit. (This depends on the
stickiness of the @code{field} property for the characters before and
after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
-@var{new-pos} is constrained to the union of the two adjacent fields.
+@var{new-pos} can be anywhere in the two adjacent fields.
Additionally, if two fields are separated by another field with the
-special value @code{boundary}, then any point within this special field
-is also considered to be ``on the boundary.''
+special value @code{boundary}, then any point within this special
+field is also considered to be ``on the boundary.''
+
+Commands like @kbd{C-a} with no argumemt, that normally move backward
+to a specific kind of location and stay there once there, probably
+should specify @code{nil} for @var{escape-from-edge}. Other motion
+commands that check fields should probably pass @code{t}.
If the optional argument @var{only-in-line} is non-@code{nil}, and
constraining @var{new-pos} in the usual way would move it to a different
This function applies a translation table to the characters in the
buffer between positions @var{start} and @var{end}.
-The translation table @var{table} is a string; @code{(aref @var{table}
-@var{ochar})} gives the translated character corresponding to
-@var{ochar}. If the length of @var{table} is less than 256, any
+The translation table @var{table} is a string or a char-table;
+@code{(aref @var{table} @var{ochar})} gives the translated character
+corresponding to @var{ochar}. If @var{table} is a string, any
characters with codes larger than the length of @var{table} are not
altered by the translation.
A register is a sort of variable used in Emacs editing that can hold a
variety of different kinds of values. Each register is named by a
-single character. All @sc{ascii} characters and their meta variants
+single character. All @acronym{ASCII} characters and their meta variants
(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 the character that is its name.
@cindex base 64 encoding
Base 64 code is used in email to encode a sequence of 8-bit bytes as
-a longer sequence of @sc{ascii} graphic characters. It is defined in
+a longer sequence of @acronym{ASCII} graphic characters. It is defined in
Internet RFC@footnote{
An RFC, an acronym for @dfn{Request for Comments}, is a numbered
Internet informational document describing a standard. RFCs are
converting to and from this code.
@defun base64-encode-region beg end &optional no-line-break
-@tindex base64-encode-region
This function converts the region from @var{beg} to @var{end} into base
64 code. It returns the length of the encoded text. An error is
signaled if a character in the region is multibyte, i.e.@: in a
@end defun
@defun base64-encode-string string &optional no-line-break
-@tindex base64-encode-string
This function converts the string @var{string} into base 64 code. It
returns a string containing the encoded text. As for
@code{base64-encode-region}, an error is signaled if a character in the
@end defun
@defun base64-decode-region beg end
-@tindex base64-decode-region
This function converts the region from @var{beg} to @var{end} from base
64 code into the corresponding decoded text. It returns the length of
the decoded text.
@end defun
@defun base64-decode-string string
-@tindex base64-decode-string
This function converts the string @var{string} from base 64 code into
the corresponding decoded text. It returns a unibyte string containing the
decoded text.
If an error (or other nonlocal exit) occurs inside the body of
@code{atomic-change-group}, it unmakes all the changes in that buffer
that were during the execution of the body. This kind of change group
-has no effect on any other buffers--any such changes remain.
+has no effect on any other buffers---any such changes remain.
If you need something more sophisticated, such as to make changes in
various buffers constitute one atomic group, you must directly call
arguments.
@end defvar
- Output of messges into the @samp{*Messages*} buffer does not
+ Output of messages into the @samp{*Messages*} buffer does not
call these functions.
-@defmac combine-after-change-calls body...
+@defmac combine-after-change-calls body@dots{}
The macro executes @var{body} normally, but arranges to call the
after-change functions just once for a series of several changes---if
that seems safe.
@code{after-change-functions} within
the body of a @code{combine-after-change-calls} form.
-@strong{Note:} If the changes you combine occur in widely scattered
+@strong{Warning:} if the changes you combine occur in widely scattered
parts of the buffer, this will still work, but it is not advisable,
because it may lead to inefficient behavior for some change hook
functions.
@end defvar
@defvar inhibit-modification-hooks
-@tindex inhibit-modification-hooks
If this variable is non-@code{nil}, all of the change hooks are
disabled; none of them run. This affects all the hook variables
described above in this section, as well as the hooks attached to
certain special text properties (@pxref{Special Properties}) and overlay
properties (@pxref{Overlay Properties}).
-
-This variable is available starting in Emacs 21.
@end defvar
+
+@ignore
+ arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
+@end ignore