@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
-@c 2000, 2001, 2004, 2005
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@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
@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
@end defun
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
---------- 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
@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, 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
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
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
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.
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 of this variable is
-@w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}}. 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 matches a sequence of
-whitespace, possibly empty.
+@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
+matches a sequence of whitespace, possibly empty.
@end defopt
@defopt adaptive-fill-first-line-regexp
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
just the foreground color or just the background color.
@code{(foreground-color . @var{color-name})} is equivalent to
-@code{(:foreground @var{color-name})}, and likewise for the background.
+specifying @code{(:foreground @var{color-name})}, and likewise for the
+background.
@end itemize
You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
@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)}
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)}
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 behaviour through the variable
+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
For example, here is how Info mode handles @key{Mouse-1}:
-@example
+@smallexample
(define-key Info-mode-map [follow-link] 'mouse-face)
-@end example
+@end smallexample
@item a function
If the condition is a valid function, @var{func}, then a position
For example, here is how pcvs enables @key{Mouse-1} to follow links on
file names only:
-@example
+@smallexample
(define-key map [follow-link]
(lambda (pos)
- (if (eq (get-char-property pos 'face) 'cvs-filename-face) t)))
-@end example
+ (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
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.