comparison lispref/text.texi @ 90261:7beb78bc1f8e

Revision: [e-mail]--gnu-2005/emacs--unicode--0--patch-97 Merge from emacs--cvs-trunk--0 Patches applied: * emacs--cvs-trunk--0 (patch 616-696) - Add lisp/mh-e/.arch-inventory - Update from CVS - Merge from gnus--rel--5.10 - Update from CVS: lisp/smerge-mode.el: Add 'tools' to file keywords. - lisp/gnus/ChangeLog: Remove duplicate entry * gnus--rel--5.10 (patch 147-181) - Update from CVS - Merge from emacs--cvs-trunk--0 - Update from CVS: lisp/mml.el (mml-preview): Doc fix. - Update from CVS: texi/message.texi: Fix default values. - Update from CVS: texi/gnus.texi (RSS): Addition.

90260:0ca0d9181b5e

is the most frequently called function in Emacs, but programs rarely use
it except to install it on a keymap.

In an interactive call, @var{count} is the numeric prefix argument.

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}).

Do not try substituting your own definition of
@code{self-insert-command} for the standard one.  The editor command
loop handles this function specially.
@end deffn

@example
(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
@var{adjustment} character positions.  Undoing this element moves
@var{marker} @minus{} @var{adjustment} characters.

@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}.

@item nil
This element is a boundary.  The elements between two boundaries are
called a @dfn{change group}; normally, each change group corresponds to
one keyboard command, and undo commands normally undo an entire group as

  The sorting functions described in this section all rearrange text in
a buffer.  This is in contrast to the function @code{sort}, which
rearranges the order of the elements of a list (@pxref{Rearrangement}).
The values returned by these functions are not meaningful.

@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
This function is the general text-sorting routine that subdivides a
buffer into records and then sorts them.  Most of the commands in this
section use this function.

To understand how @code{sort-subr} works, consider the whole accessible

@var{startkeyfun} returns @code{nil} and this argument is omitted (or
@code{nil}), then the sort key extends to the end of the record.  There
is no need for @var{endkeyfun} if @var{startkeyfun} returns a
non-@code{nil} value.
@end enumerate

As an example of @code{sort-subr}, here is the complete function
definition for @code{sort-lines}:

@example

list.
@end defun

@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
alternating list of property names and values.
@end defun

@defun set-text-properties start end props &optional object
This function completely replaces the text property list for the text

from the specified range of text.  Here's an example:

@example
(set-text-properties @var{start} @var{end} nil)
@end example
@end defun

  The easiest way to make a string with text properties
is with @code{propertize}:

90261:7beb78bc1f8e

is the most frequently called function in Emacs, but programs rarely use
it except to install it on a keymap.

In an interactive call, @var{count} is the numeric prefix argument.

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}.)  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
loop handles this function specially.
@end deffn

@example
(put-text-property @var{beg} @var{end} @var{property} @var{value})
@end example

@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
@var{adjustment} character positions.  Undoing this element moves
@var{marker} @minus{} @var{adjustment} characters.

@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
one keyboard command, and undo commands normally undo an entire group as

  The sorting functions described in this section all rearrange text in
a buffer.  This is in contrast to the function @code{sort}, which
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 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.

To understand how @code{sort-subr} works, consider the whole accessible

@var{startkeyfun} returns @code{nil} and this argument is omitted (or
@code{nil}), then the sort key extends to the end of the record.  There
is no need for @var{endkeyfun} if @var{startkeyfun} returns a
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}:

@example

list.
@end defun

@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 of property names only, not an
alternating list of property names and values.
@end defun

@defun set-text-properties start end props &optional object
This function completely replaces the text property list for the text

from the specified range of text.  Here's an example:

@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}: