comparison lispref/text.texi @ 72381:4300054c252b

* text.texi (Near Point): Say "cursor" not "terminal cursor". (Commands for Insertion): Removed split-line since it's not relevant for Lisp programming. (Yank Commands): Rewrite introduction. (Undo): Clarify. (Maintaining Undo): Clarify. Document undo-ask-before-discard. (Filling): Remove redundant comment. Clarify return value of current-justification. (Margins): Minor clarifications. (Adaptive Fill): Update default value of adaptive-fill-regexp. (Sorting): Update definition of sort-lines. (Columns): Clarify behavior of sort-columns. (Indent Tabs): Link to Tab Stops in Emacs manual. (Special Properties): Clarify. (Clickable Text): Mention Buttons package.

72380:37cc9e9df5a4

@defun following-char
This function returns the character following point in the current
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
cursor is over.

In this example, point is between the @samp{a} and the @samp{c}.

@example

The value returned is @code{nil}.  In an interactive call, @var{count}
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},
or @code{nil}.  @code{overwrite-mode-textual} specifies textual
overwrite mode (treats newlines and tabs specially), and

@node Yank Commands
@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.

@deffn Command yank &optional arg
@cindex inserting killed text
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

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

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

@code{primitive-undo} adds elements to the buffer's undo list when it
changes the buffer.  Undo commands avoid confusion by saving the undo
list value at the beginning of a sequence of undo operations.  Then the
undo operations use and update the saved value.  The new elements added

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.)  Three variables control the range of acceptable
sizes: @code{undo-limit}, @code{undo-strong-limit} and
@code{undo-outer-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 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

@node Filling
@comment  node-name,  next,  previous,  up
@section Filling

This command considers a region of text as a single paragraph and fills
it.  If the region was made up of many paragraphs, the blank lines
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
canonicalize spaces before that position.

@end defopt

@defun current-justification
This function returns the proper justification style to use for filling
the text around point.
@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

@node Margins
@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.

The fill prefix follows the left margin whitespace, if any.
@end defopt

@defopt fill-column

becomes buffer-local when set in any fashion.
@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 list of functions, but a
single function is also supported for compatibility.  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

@defopt adaptive-fill-regexp
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.

@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

  (interactive "P\nr")
  (save-excursion
    (save-restriction
      (narrow-to-region beg end)
      (goto-char (point-min))
      (sort-subr reverse 'forward-line 'end-of-line))))
@end group
@end example

Here @code{forward-line} moves point to the start of the next record,
and @code{end-of-line} moves point to the end of record.  We do not pass

One unusual thing about this command is that the entire line
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.
@end deffn

@node Columns
@comment  node-name,  next,  previous,  up
@section Counting Columns

typewriter.  The feature works by inserting an appropriate number of
spaces and tab characters to reach the next tab stop column; it does not
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.

@deffn Command tab-to-tab-stop
This command inserts spaces or tabs before point, up to the next tab
stop column defined by @code{tab-stop-list}.  It searches the list for
an element greater than the current column number, and uses that element

@item keymap
@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.  (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.

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

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

@item syntax-table
The @code{syntax-table} property overrides what the syntax table says
about this particular character.  @xref{Syntax Properties}.

@node Clickable Text
@subsection Defining Clickable Text
@cindex clickable text

  There are two parts of setting up @dfn{clickable text} in a buffer:
(1) to indicate clickability when the mouse moves over the text, and (2)
to make a mouse button do something when you click on that text.

  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}

72381:4300054c252b

@defun following-char
This function returns the character following point in the current
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 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}.

@example

The value returned is @code{nil}.  In an interactive call, @var{count}
is the numeric prefix argument.
@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},
or @code{nil}.  @code{overwrite-mode-textual} specifies textual
overwrite mode (treats newlines and tabs specially), and

@node Yank Commands
@comment  node-name,  next,  previous,  up
@subsection Functions for Yanking

  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 at the front of the
kill ring.  It positions the mark at the beginning of that text, and

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

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

@code{primitive-undo} adds elements to the buffer's undo list when it
changes the buffer.  Undo commands avoid confusion by saving the undo
list value at the beginning of a sequence of undo operations.  Then the
undo operations use and update the saved value.  The new elements added

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

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

This command considers a region of text as a single paragraph and fills
it.  If the region was made up of many paragraphs, the blank lines
between paragraphs are removed.  This function justifies as well as
filling when @var{justify} is non-@code{nil}.

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
canonicalize spaces before that position.

@end defopt

@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

@node Margins
@section Margins for Filling

@defopt 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

@defopt fill-column

becomes buffer-local when set in any fashion.
@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 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

@defopt adaptive-fill-regexp
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.

@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

  (interactive "P\nr")
  (save-excursion
    (save-restriction
      (narrow-to-region beg end)
      (goto-char (point-min))
      (let ((inhibit-field-text-motion t))
        (sort-subr reverse 'forward-line 'end-of-line)))))
@end group
@end example

Here @code{forward-line} moves point to the start of the next record,
and @code{end-of-line} moves point to the end of record.  We do not pass

One unusual thing about this command is that the entire line
containing position @var{beg}, and the entire line containing position
@var{end}, are included in the region sorted.

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
@comment  node-name,  next,  previous,  up
@section Counting Columns

typewriter.  The feature works by inserting an appropriate number of
spaces and tab characters to reach the next tab stop column; it does not
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
stop column defined by @code{tab-stop-list}.  It searches the list for
an element greater than the current column number, and uses that element

@item keymap
@cindex keymap of character
@kindex keymap @r{(text property)}
The @code{keymap} property specifies an additional keymap for
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), it is better to use the @code{keymap}
property.

@item syntax-table
The @code{syntax-table} property overrides what the syntax table says
about this particular character.  @xref{Syntax Properties}.

@node Clickable Text
@subsection Defining Clickable Text
@cindex clickable text

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