@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2016 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Text
@chapter Text
word on the same line is acceptable.
@end defun
-@defun thing-at-point thing
+@defun thing-at-point thing &optional no-properties
Return the @var{thing} around or next to point, as a string.
The argument @var{thing} is a symbol which specifies a kind of syntactic
@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
@code{whitespace}, @code{line}, @code{page}, and others.
+When the optional argument @var{no-properties} is non-@code{nil}, this
+function strips text properties from the return value.
+
@example
---------- Buffer: foo ----------
Gentlemen may cry ``Pea@point{}ce! Peace!,''
@code{delete-blank-lines} returns @code{nil}.
@end deffn
-@deffn Command delete-trailing-whitespace start end
+@deffn Command delete-trailing-whitespace &optional start end
Delete trailing whitespace in the region defined by @var{start} and
@var{end}.
@code{last-command}) whether the previous command was a kill command,
and if so appends the killed text to the most recent entry.
-@deffn Command kill-region start end
-This function kills the text in the region defined by @var{start} and
-@var{end}. The text is deleted but saved in the kill ring, along with
-its text properties. The value is always @code{nil}.
+@cindex filtering killed text
+ The commands described below can filter the killed text before they
+save it in the kill ring. They call @code{filter-buffer-substring}
+(@pxref{Buffer Contents}) to perform the filtering. By default,
+there's no filtering, but major and minor modes and hook functions can
+set up filtering, so that text saved in the kill ring is different
+from what was in the buffer.
+
+@deffn Command kill-region start end &optional region
+This function kills the stretch of text between @var{start} and
+@var{end}; but if the optional argument @var{region} is
+non-@code{nil}, it ignores @var{start} and @var{end}, and kills the
+text in the current region instead. The text is deleted but saved in
+the kill ring, along with its text properties. The value is always
+@code{nil}.
In an interactive call, @var{start} and @var{end} are point and
-the mark.
+the mark, and @var{region} is always non-@code{nil}, so the command
+always kills the text in the current region.
If the buffer or text is read-only, @code{kill-region} modifies the kill
ring just the same, then signals an error without modifying the buffer.
updating the kill ring but not changing the buffer.
@end defopt
-@deffn Command copy-region-as-kill start end
-This command saves the region defined by @var{start} and @var{end} on
-the kill ring (including text properties), but does not delete the text
-from the buffer. It returns @code{nil}.
+@deffn Command copy-region-as-kill start end &optional region
+This function saves the stretch of text between @var{start} and
+@var{end} on the kill ring (including text properties), but does not
+delete the text from the buffer. However, if the optional argument
+@var{region} is non-@code{nil}, the function ignores @var{start} and
+@var{end}, and saves the current region instead. It always returns
+@code{nil}.
+
+In an interactive call, @var{start} and @var{end} are point and
+the mark, and @var{region} is always non-@code{nil}, so the command
+always saves the text in the current region.
The command does not set @code{this-command} to @code{kill-region}, so a
subsequent kill command does not append to the same kill ring entry.
-
-@c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then?
-@c Why is it used in many places in Emacs?
-In Lisp programs, it is better to use @code{kill-new} or
-@code{kill-append} instead of this command. @xref{Low-Level Kill Ring}.
@end deffn
@node Yanking
command stops at such a boundary, and successive undo commands undo
to earlier and earlier boundaries. This function returns @code{nil}.
-The editor command loop automatically calls @code{undo-boundary} just
-before executing each key sequence, so that each undo normally undoes
-the effects of one command. As an exception, the command
-@code{self-insert-command}, which produces self-inserting input
-characters (@pxref{Commands for Insertion}), may remove the boundary
-inserted by the command loop: a boundary is accepted for the first
-such character, the next 19 consecutive self-inserting input
-characters do not have boundaries, and then the 20th does; and so on
-as long as the self-inserting characters continue. Hence, sequences
-of consecutive character insertions can be undone as a group.
-
-All buffer modifications add a boundary whenever the previous undoable
-change was made in some other buffer. This is to ensure that
-each command makes a boundary in each buffer where it makes changes.
-
Calling this function explicitly is useful for splitting the effects of
a command into more than one unit. For example, @code{query-replace}
calls @code{undo-boundary} after each replacement, so that the user can
undo individual replacements one by one.
+
+Mostly, however, this function is called automatically at an
+appropriate time.
@end defun
+@defun undo-auto-amalgamate
+@cindex amalgamating commands, and undo
+The editor command loop automatically calls @code{undo-boundary} just
+before executing each key sequence, so that each undo normally undoes
+the effects of one command. A few exceptional commands are
+@dfn{amalgamating}: these commands generally cause small changes to
+buffers, so with these a boundary is inserted only every 20th command,
+allowing to undo them as a group. By default, commands
+@code{self-insert-command}, which produces self-inserting input
+characters (@pxref{Commands for Insertion}), and @code{delete-char}
+which deletes characters (@pxref{Deletion}) are amalgamating.
+Where a command affects the contents of several buffers, as may happen,
+for example, when a function on the @code{post-command-hook} affects a
+buffer other than the @code{current-buffer}, then @code{undo-boundary}
+will be called in each of the affected buffers.
+@end defun
+
+@defvar undo-auto-current-boundary-timer
+Some buffers, such as process buffers, can change even when no
+commands are executing. In these cases, @code{undo-boundary} is
+normally called periodically by the timer in this variable. Setting
+this variable to non-@code{nil} prevents this behavior.
+@end defvar
+
@defvar undo-in-progress
This variable is normally @code{nil}, but the undo commands bind it to
@code{t}. This is so that various kinds of change hooks can tell when
@defopt left-margin
This variable specifies the base left margin column. In Fundamental
-mode, @kbd{RET} indents to this column. This variable automatically
+mode, @key{RET} indents to this column. This variable automatically
becomes buffer-local when set in any fashion.
@end defopt
text at point (@pxref{Completion in Buffers}).
@end defopt
+
@node Region Indent
@subsection Indenting an Entire Region
@item inhibit-read-only
@kindex inhibit-read-only @r{(text property)}
-If a character has the property @code{inhibit-read-only}, and the
-buffer is read-only, editing the character in question is allowed.
+Characters that have the property @code{inhibit-read-only} can be
+edited even in read-only buffers. @xref{Read Only Buffers}.
@item invisible
@kindex invisible @r{(text property)}
@code{intangible} properties, they belong to separate groups; each
group is separately treated as described above.
-When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
-the @code{intangible} property is ignored.
+When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}
+(as it is by default), the @code{intangible} property is ignored.
Beware: this property operates at a very low level, and affects a lot of code
in unexpected ways. So use it with extreme caution. A common misuse is to put
an intangible property on invisible text, which is actually unnecessary since
the command loop will move point outside of the invisible text at the end of
-each command anyway. @xref{Adjusting Point}.
+each command anyway. @xref{Adjusting Point}. For these reasons, this
+property is obsolete; use the @code{cursor-intangible} property instead.
+
+@item cursor-intangible
+@kindex cursor-intangible @r{(text property)}
+@findex cursor-intangible-mode
+When the minor mode @code{cursor-intangible-mode} is turned on, point
+is moved away of any position that has a non-@code{nil}
+@code{cursor-intangible} property, just before redisplay happens.
@item field
@kindex field @r{(text property)}
buffer positions without moving point to those positions. Only an
actual change in the value of point runs these hook functions.
-The variable @code{inhibit-point-motion-hooks} can inhibit running the
-@code{point-left} and @code{point-entered} hooks, see @ref{Inhibit
-point motion hooks}.
+The variable @code{inhibit-point-motion-hooks} by default inhibits
+running the @code{point-left} and @code{point-entered} hooks, see
+@ref{Inhibit point motion hooks}.
+
+These properties are obsolete; please use
+@code{cursor-sensor-functions} instead.
+
+@item cursor-sensor-functions
+@kindex cursor-sensor-functions @r{(text property)}
+@findex cursor-sensor-mode
+This special property records a list of functions that react to cursor
+motion. Each function in the list is called, just before redisplay,
+with 3 arguments: the affected window, the previous known position of
+the cursor, and one of the symbols @code{entered} or @code{left},
+depending on whether the cursor is entering the text that has this
+property or leaving it. The functions are called only when the minor
+mode @code{cursor-sensor-mode} is turned on.
@item composition
@kindex composition @r{(text property)}
@end table
@defvar inhibit-point-motion-hooks
-@anchor{Inhibit point motion hooks} When this variable is
+@anchor{Inhibit point motion hooks} When this obsolete variable is
non-@code{nil}, @code{point-left} and @code{point-entered} hooks are
not run, and the @code{intangible} property has no effect. Do not set
-this variable globally; bind it with @code{let}.
+this variable globally; bind it with @code{let}. Since the affected
+properties are obsolete, this variable's default value is @code{t}, to
+effectively disable them.
@end defvar
@defvar show-help-function