comparison lispref/text.texi @ 67769:20a39d204662

(Undo): Restore some explanation from the version that was deleted.

67768:edd5b99fd103

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

@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

67769:20a39d204662

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

@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