@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 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Non-ASCII Characters, Markers, Top
properties, just the characters themselves. @xref{Text Properties}.
@end defun
-@defun filter-buffer-substring start end &optional delete
+@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
between @var{start} and @var{end} after copying it, like
@code{delete-and-extract-region}.
-Lisp code should use this function instead of @code{buffer-substring}
+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
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
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:
(put-text-property @var{beg} @var{end} @var{property} @var{value})
@end example
-@item (apply @var{funname} . @var{args})
-This kind of element records a change that can be undone by evaluating
-(@code{apply} @var{funname} @var{args}).
-
-@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
-This kind of element records a change that can be undone by evaluating
-(@code{apply} @var{funname} @var{args}). The integer values @var{beg}
-and @var{end} is buffer positions of the range affected by this change
-and @var{delta} is an integer value which is the number of bytes added
-or deleted in that range by this change. This kind of element
-enables undo limited to a region to determine whether the element
-pertains to that region.
-
@item (@var{marker} . @var{adjustment})
This kind of element records the fact that the marker @var{marker} was
relocated due to deletion of surrounding text, and that it moved
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
starting after the left margin whitespace (if any) on a line; the
characters it matches are that line's candidate for the fill prefix.
-@w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
+@w{@code{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
default value. This matches a number enclosed in parentheses or
followed by a period, or certain punctuation characters, or any
sequence of these intermingled with whitespace. In particular, it
replaces the candidate with a string of spaces ``of the same width''
as it.
-The default value of this variable is @w{@samp{"\\`[ \t]*\\'"}}, which
+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.
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}:
@defun remove-list-of-text-properties start end list-of-properties &optional object
Like @code{remove-text-properties} except that
-@var{list-of-properties} is a list property names only, not an
+@var{list-of-properties} is a list of property names only, not an
alternating list of property names and values.
@end defun
@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
@item
A cons cell of 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
specifying @code{(:foreground @var{color-name})}, and likewise for the
@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 text has had faces 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 these three values---other values are invalid:
+
+@table @asis
+@item @code{nil}
+Font locking is disabled, or the @code{face} properties on the text,
+if any, are invalid.
+
+@item The symbol @code{defer}
+This value states that the text's @code{face} properties are invalid
+and marks it for deferred fontification. It is used only when ``just
+in time'' font locking is enabled.
+
+@item @code{t}
+The @code{face} properties, or lack of them, on the text are currently
+valid.
+@end table
@item display
@kindex display @r{(text property)}
@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
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.