@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2014 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
* Base 64:: Conversion to or from base 64 encoding.
* Checksum/Hash:: Computing cryptographic hashes.
* Parsing HTML/XML:: Parsing HTML and XML.
-* Atomic Changes:: Installing several buffer changes "atomically".
+* Atomic Changes:: Installing several buffer changes atomically.
* Change Hooks:: Supplying functions to be run when text is changed.
@end menu
@node Buffer Contents
@section Examining Buffer Contents
+@cindex buffer portion as string
This section describes functions that allow a Lisp program to
convert any portion of the text in the buffer into a string.
the current buffer, as a string.
@end defun
+ If you need to make sure the resulting string, when copied to a
+different location, will not change its visual appearance due to
+reordering of bidirectional text, use the
+@code{buffer-substring-with-bidi-context} function
+(@pxref{Bidirectional Display, buffer-substring-with-bidi-context}).
+
@defun filter-buffer-substring start end &optional delete
-This function passes the buffer text between @var{start} and @var{end}
-through the filter functions specified by the wrapper hook
-@code{filter-buffer-substring-functions}, and returns the result. The
-obsolete variable @code{buffer-substring-filters} is also consulted.
-If both of these variables are @code{nil}, the value is the unaltered
-text from the buffer, i.e., what @code{buffer-substring} would
-return.
-
-If @var{delete} is non-@code{nil}, this function deletes the text
+This function filters the buffer text between @var{start} and @var{end}
+using a function specified by the variable
+@code{filter-buffer-substring-function}, and returns the result.
+
+The default filter function consults the obsolete wrapper hook
+@code{filter-buffer-substring-functions}, and the obsolete variable
+@code{buffer-substring-filters}. If both of these are @code{nil}, it
+returns the unaltered text from the buffer, i.e., what
+@code{buffer-substring} would return.
+
+If @var{delete} is non-@code{nil}, the function deletes the text
between @var{start} and @var{end} after copying it, like
@code{delete-and-extract-region}.
@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
-@code{filter-buffer-substring-functions} to alter such text as it is
-copied out of the buffer.
+Major and minor modes can modify @code{filter-buffer-substring-function}
+to alter such text as it is copied out of the buffer.
@end defun
-@c FIXME: `filter-buffer-substring-function' should be documented.
+@defvar filter-buffer-substring-function
+The value of this variable is a function that @code{filter-buffer-substring}
+will call to do the actual work. The function receives three
+arguments, the same as those of @code{filter-buffer-substring},
+which it should treat as per the documentation of that function. It
+should return the filtered text (and optionally delete the source text).
+@end defvar
+
+@noindent The following two variables are obsoleted by
+@code{filter-buffer-substring-function}, but are still supported for
+backward compatibility.
+
@defvar filter-buffer-substring-functions
-This variable is a wrapper hook (@pxref{Running Hooks}), whose members
-should be functions that accept four arguments: @var{fun},
-@var{start}, @var{end}, and @var{delete}. @var{fun} is a function
-that takes three arguments (@var{start}, @var{end}, and @var{delete}),
-and returns a string. In both cases, the @var{start}, @var{end}, and
-@var{delete} arguments are the same as those of
-@code{filter-buffer-substring}.
+This obsolete variable is a wrapper hook, whose members should be functions
+that accept four arguments: @var{fun}, @var{start}, @var{end}, and
+@var{delete}. @var{fun} is a function that takes three arguments
+(@var{start}, @var{end}, and @var{delete}), and returns a string. In
+both cases, the @var{start}, @var{end}, and @var{delete} arguments are
+the same as those of @code{filter-buffer-substring}.
The first hook function is passed a @var{fun} that is equivalent to
the default operation of @code{filter-buffer-substring}, i.e., it
@end defvar
@defvar buffer-substring-filters
-This variable is obsoleted by
-@code{filter-buffer-substring-functions}, but is still supported for
-backward compatibility. Its value should should be a list of
-functions which accept a single string argument and return another
-string. @code{filter-buffer-substring} passes the buffer substring to
-the first function in this list, and the return value of each function
-is passed to the next function. The return value of the last function
-is passed to @code{filter-buffer-substring-functions}.
+The value of this obsolete variable should be a list of functions
+that accept a single string argument and return another string.
+The default @code{filter-buffer-substring} function passes the buffer
+substring to the first function in this list, and the return value of
+each function is passed to the next function. The return value of the
+last function is passed to @code{filter-buffer-substring-functions}.
@end defvar
@defun current-word &optional strict really-word
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!,''
if @code{case-fold-search} is non-@code{nil}. It always ignores
text properties.
-Suppose the current buffer contains the text @samp{foobarbar
-haha!rara!}; then in this example the two substrings are @samp{rbar }
-and @samp{rara!}. The value is 2 because the first substring is greater
-at the second character.
+Suppose you have the text @w{@samp{foobarbar haha!rara!}} in the
+current buffer; then in this example the two substrings are @samp{rbar
+} and @samp{rara!}. The value is 2 because the first substring is
+greater at the second character.
@example
(compare-buffer-substrings nil 6 11 nil 16 21)
@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
+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}).
asking for any confirmation. It returns @code{nil}.
Normally, deleting a large amount of text from a buffer inhibits further
-auto-saving of that buffer ``because it has shrunk''. However,
+auto-saving of that buffer because it has shrunk. However,
@code{erase-buffer} does not do this, the idea being that the future
text is not really related to the former text, and its size should not
be compared with that of the former text.
@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}.
This command deletes whitespace characters after the last
non-whitespace character in each line in the region.
-If this command acts on the entire buffer (i.e. if called
+If this command acts on the entire buffer (i.e., if called
interactively with the mark inactive, or called from Lisp with
-@var{end} nil), it also deletes all trailing lines at the end of the
+@var{end} @code{nil}), it also deletes all trailing lines at the end of the
buffer if the variable @code{delete-trailing-lines} is non-@code{nil}.
@end deffn
it so that the user can reinsert it by @dfn{yanking}. Most of these
functions have @samp{kill-} in their name. By contrast, the functions
whose names start with @samp{delete-} normally do not save text for
-yanking (though they can still be undone); these are ``deletion''
+yanking (though they can still be undone); these are deletion
functions.
Most of the kill commands are primarily for interactive use, and are
Some people think this use of the word ``kill'' is unfortunate, since
it refers to operations that specifically @emph{do not} destroy the
-entities ``killed''. This is in sharp contrast to ordinary life, in
-which death is permanent and ``killed'' entities do not come back to
+entities killed. This is in sharp contrast to ordinary life, in
+which death is permanent and killed entities do not come back to
life. Therefore, other metaphors have been proposed. For example, the
term ``cut ring'' makes sense to people who, in pre-computer days, used
scissors and paste to cut up and rearrange manuscripts. However, it
unit; the second and subsequent consecutive kill commands add text to
the entry made by the first one.
- For yanking, one entry in the kill ring is designated the ``front'' of
-the ring. Some yank commands ``rotate'' the ring by designating a
-different element as the ``front''. But this virtual rotation doesn't
+ For yanking, one entry in the kill ring is designated the front of
+the ring. Some yank commands rotate the ring by designating a
+different element as the front. But this virtual rotation doesn't
change the list itself---the most recent entry always comes first in the
list.
@subsection Functions for Killing
@code{kill-region} is the usual subroutine for killing text. Any
-command that calls this function is a ``kill command'' (and should
+command that calls this function is a kill command (and should
probably have @samp{kill} in its name). @code{kill-region} puts the
newly killed text in a new element at the beginning of the kill ring or
adds it to the most recent element. It determines automatically (using
@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
@defun current-kill n &optional do-not-move
The function @code{current-kill} rotates the yanking pointer, which
-designates the ``front'' of the kill ring, by @var{n} places (from newer
+designates the front of the kill ring, by @var{n} places (from newer
kills to older ones), and returns the text at that place in the ring.
If the optional second argument @var{do-not-move} is non-@code{nil},
@code{nil} or a function of no arguments.
If the value is a function, @code{current-kill} calls it to get the
-``most recent kill''. If the function returns a non-@code{nil} value,
-then that value is used as the ``most recent kill''. If it returns
+most recent kill. If the function returns a non-@code{nil} value,
+then that value is used as the most recent kill. If it returns
@code{nil}, then the front of the kill ring is used.
To facilitate support for window systems that support multiple
selections, this function may also return a list of strings. In that
-case, the first string is used as the ``most recent kill'', and all
+case, the first string is used as the most recent kill, and all
the other strings are pushed onto the kill ring, for easy access by
@code{yank-pop}.
The @code{kill-ring-yank-pointer} variable points to a link in the
kill ring list, whose @sc{car} is the text to yank next. We say it
-identifies the ``front'' of the ring. Moving
+identifies the front of the ring. Moving
@code{kill-ring-yank-pointer} to a different link is called
@dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
the functions that move the yank pointer wrap around from the end of the
@defvar kill-ring-yank-pointer
This variable's value indicates which element of the kill ring is at the
-``front'' of the ring for yanking. More precisely, the value is a tail
+front of the ring for yanking. More precisely, the value is a tail
of the value of @code{kill-ring}, and its @sc{car} is the kill string
that @kbd{C-y} should yank.
@end defvar
The deleted text itself is the string @var{text}. The place to
reinsert it is @code{(abs @var{position})}. If @var{position} is
positive, point was at the beginning of the deleted text, otherwise it
-was at the end.
+was at the end. Zero or more (@var{marker} . @var{adjustment})
+elements follow immediately after this element.
@item (t . @var{time-flag})
This kind of element indicates that an unmodified buffer became
@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.
+@var{adjustment} character positions. If the marker's location is
+consistent with the (@var{text} . @var{position}) element preceding it
+in the undo list, then undoing this element moves @var{marker}
+@minus{} @var{adjustment} characters.
@item (apply @var{funname} . @var{args})
This is an extensible undo item, which is undone by calling
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
As editing continues, undo lists get longer and longer. To prevent
them from using up all available memory space, garbage collection trims
-them back to size limits you can set. (For this purpose, the ``size''
+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
@defvar use-hard-newlines
If this variable is non-@code{nil}, the filling functions do not delete
-newlines that have the @code{hard} text property. These ``hard
-newlines'' act as paragraph separators. @xref{Hard and Soft
+newlines that have the @code{hard} text property. These hard
+newlines act as paragraph separators. @xref{Hard and Soft
Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
@end defvar
@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
additional check of the validity of the one available candidate fill
prefix: the candidate must match this regular expression, or match
@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix}
-replaces the candidate with a string of spaces ``of the same width''
+replaces the candidate with a string of spaces of the same width
as it.
The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
You can specify more complex ways of choosing a fill prefix
automatically by setting this variable to a function. The function is
called with point after the left margin (if any) of a line, and it
-must preserve point. It should return either ``that line's'' fill
+must preserve point. It should return either that line's fill
prefix or @code{nil}, meaning it has failed to determine a prefix.
@end defopt
columns, counting from 0 at the left margin. The column position is the
sum of the widths of all the displayed representations of the characters
between the start of the current line and point.
-
-For an example of using @code{current-column}, see the description of
-@code{count-lines} in @ref{Text Lines}.
@end defun
@deffn Command move-to-column column &optional force
text at point (@pxref{Completion in Buffers}).
@end defopt
+@cindex literate programming
+@cindex multi-mode indentation
+ Some major modes need to support embedded regions of text whose
+syntax belongs to a different major mode. Examples include
+@dfn{literate programming} source files that combine documentation and
+snippets of source code, Yacc/Bison programs that include snippets of
+plain C code, etc. To correctly indent the embedded chunks, the major
+mode needs to delegate the indentation to another mode's indentation
+engine (e.g., call @code{c-indent-defun} for C code or
+@code{python-indent-line} for Python), while providing it with some
+context to guide the indentation. The following facilities support
+such multi-mode indentation.
+
+@defvar prog-indentation-context
+This variable, when non-@code{nil}, holds the indentation context for
+the sub-mode's indentation engine provided by the superior major mode.
+The value should be a list of the form @code{(@var{first-column}
+@w{(@var{start} . @var{end})} @code{prev-chunk})}. The members of the
+list have the following meaning:
+
+@table @var
+@item first-column
+The column to be used for top-level constructs. This replaces the
+default value of the top-level column used by the sub-mode, usually
+zero.
+@item start
+@itemx end
+The region of the code chunk to be indented by the sub-mode. The
+value of @var{end} can be @code{nil}, which stands for the value of
+@code{point-max}.
+@item prev-chunk
+If this is non-@code{nil}, it should provide the sub-mode's
+indentation engine with a virtual context of the code chunk. Valid
+values include:
+
+@itemize @minus
+@item
+A string whose contents is the text the sub-mode's indentation engine
+should consider to precede the code chunk. The sub-mode's indentation
+engine can add text properties to that string, to be reused in
+repeated calls with the same string, thus using it as a cache. An
+example where this is useful is code chunks that need to be indented
+as function bodies, but lack the function's preamble---the string
+could then include that missing preamble.
+@item
+A function. It is expected to be called with the start position of
+the current chunk, and should return a cons cell
+@w{@code{(@var{prev-start} . @var{prev-end})}} that specifies the
+region of the previous code chunk, or @code{nil} if there is no previous
+chunk. This is useful in literate-programming sources, where code is
+split into chunks, and correct indentation needs to access previous
+chunks.
+@end itemize
+@end table
+@end defvar
+
+The following convenience functions should be used by major mode's
+indentation engine in support of invocations as sub-modes of another
+major mode.
+
+@defun prog-first-column
+Call this function instead of using a literal value (usually, zero) of
+the column number for indenting top-level program constructs. The
+function's value is the column number to use for top-level constructs.
+When no superior mode is in effect, this function returns zero.
+@end defun
+
+@defun prog-widen
+Call this function instead of @code{widen} to remove any restrictions
+imposed by the mode's indentation engine and restore the restrictions
+recorded in @code{prog-indentation-context}. This prevents the
+indentation engine of a sub-mode from inadvertently operating on text
+outside of the chunk it was supposed to indent, and preserves the
+restriction imposed by the superior mode. When no superior mode is in
+effect, this function just calls @code{widen}.
+@end defun
+
+
@node Region Indent
@subsection Indenting an Entire Region
@deffn Command indent-rigidly start end count
This function indents all lines starting between @var{start}
(inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
-This ``preserves the shape'' of the affected region, moving it as a
+This preserves the shape of the affected region, moving it as a
rigid unit.
This is useful not only for indenting regions of unindented text, but
@end deffn
@node Indent Tabs
-@subsection Adjustable ``Tab Stops''
+@subsection Adjustable Tab Stops
@cindex tabs stops for indentation
- This section explains the mechanism for user-specified ``tab stops''
+ This section explains the mechanism for user-specified tab stops
and the mechanisms that use and set them. The name ``tab stops'' is
used because the feature is similar to that of the tab stops on a
typewriter. The feature works by inserting an appropriate number of
@node Examining Properties
@subsection Examining Text Properties
+@cindex examining text properties
+@cindex text properties, examining
The simplest way to examine text properties is to ask for the value of
a particular property of a particular character. For that, use
@defun get-pos-property position prop &optional object
This function is like @code{get-char-property}, except that it pays
attention to properties' stickiness and overlays' advancement settings
-instead of the property of the character at (i.e. right after)
+instead of the property of the character at (i.e., right after)
@var{position}.
@end defun
@node Changing Properties
@subsection Changing Text Properties
+@cindex changing text properties
+@cindex text properties, changing
The primitives for changing properties apply to a specified range of
text in a buffer or string. The function @code{set-text-properties}
(@pxref{Special Properties}), such as a face name or an anonymous face
(@pxref{Faces}).
-If any text in the region already has a non-nil @code{face} property,
+If any text in the region already has a non-@code{nil} @code{face} property,
those face(s) are retained. This function sets the @code{face}
property to a list of faces, with @var{face} as the first element (by
default) and the pre-existing faces as the remaining elements. If the
@node Property Search
@subsection Text Property Search Functions
+@cindex searching text properties
+@cindex text properties, searching
In typical use of text properties, most of the time several or many
consecutive characters have the same value for a property. Rather than
@code{nil}, Emacs's redisplay routine calls the functions in
@code{fontification-functions} (@pxref{Auto Faces}) to prepare this
part of the buffer before it is displayed. It is used internally by
-the ``just in time'' font locking code.
+the just-in-time font locking code.
@item display
This property activates various features that change the
@item help-echo
@kindex help-echo @r{(text property)}
-@cindex tooltip
+@cindex tooltip for help strings
@anchor{Text help-echo}
If text has a string as its @code{help-echo} property, then when you
move the mouse onto that text, Emacs displays that string in the echo
-area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
-Manual}).
+area, or in the tooltip window (@pxref{Tooltips}).
If the value of the @code{help-echo} property is a function, that
function is called with three arguments, @var{window}, @var{object} and
special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
and then remove the property. @xref{Read Only Buffers}.
+@item inhibit-read-only
+@kindex inhibit-read-only @r{(text property)}
+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)}
A non-@code{nil} @code{invisible} property can make a character invisible
@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
properties, menu help strings (@pxref{Simple Menu Items},
@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
Bar}). The specified function is called with one argument, the help
-string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
-Manual}) provides an example.
+string to display, which is passed through
+@code{substitute-command-keys} before being given to the function; see
+@ref{Keys in Documentation}. Tooltip mode (@pxref{Tooltips,,, emacs,
+The GNU Emacs Manual}) provides an example.
@end defvar
@node Format Properties
@cindex sticky text properties
@cindex inheritance, text property
- Self-inserting characters normally take on the same properties as the
-preceding character. This is called @dfn{inheritance} of properties.
+ Self-inserting characters, the ones that get inserted into a buffer
+when the user types them (@pxref{Commands for Insertion}), normally
+take on the same properties as the preceding character. This is
+called @dfn{inheritance} of properties.
- A Lisp program can do insertion with inheritance or without,
+ By contrast, a Lisp program can do insertion with inheritance or without,
depending on the choice of insertion primitive. The ordinary text
insertion functions, such as @code{insert}, do not inherit any
properties. They insert text with precisely the properties of the
@defvar buffer-access-fontified-property
If this variable's value is non-@code{nil}, it is a symbol which is used
as a text property name. A non-@code{nil} value for that text property
-means, ``the other text properties for this character have already been
-computed''.
+means the other text properties for this character have already been
+computed.
If all the characters in the range specified for @code{buffer-substring}
have a non-@code{nil} value for this property, @code{buffer-substring}
controlled by the user option @code{mouse-1-click-follows-link}.
@xref{Mouse References,,, emacs, The GNU Emacs Manual}.
+@cindex follow-link (text or overlay property)
To set up the link so that it obeys
@code{mouse-1-click-follows-link}, you must either (1) apply a
@code{follow-link} text or overlay property to the link text, or (2)
bind the @code{follow-link} event to a keymap (which can be a major
mode keymap or a local keymap specified via the @code{keymap} text
property). The value of the @code{follow-link} property, or the
-binding for the @code{follow-link} event, acts as a ``condition'' for
+binding for the @code{follow-link} event, acts as a condition for
the link action. This condition tells Emacs two things: the
circumstances under which a @kbd{Mouse-1} click should be regarded as
-occurring ``inside'' the link, and how to compute an ``action code''
+occurring inside the link, and how to compute an action code
that says what to translate the @kbd{Mouse-1} click into. The link
action condition can be one of the following:
@end defun
@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
-This function ``constrains'' @var{new-pos} to the field that
+This function constrains @var{new-pos} to the field that
@var{old-pos} belongs to---in other words, it returns the position
closest to @var{new-pos} that is in the same field as @var{old-pos}.
@var{new-pos} can be anywhere in the two adjacent fields.
Additionally, if two fields are separated by another field with the
special value @code{boundary}, then any point within this special
-field is also considered to be ``on the boundary''.
+field is also considered to be on the boundary.
Commands like @kbd{C-a} with no argument, that normally move backward
to a specific kind of location and stay there once there, probably
@cindex intervals
Some editors that support adding attributes to text in the buffer do
-so by letting the user specify ``intervals'' within the text, and adding
+so by letting the user specify intervals within the text, and adding
the properties to the intervals. Those editors permit the user or the
programmer to determine where individual intervals start and end. We
deliberately provided a different sort of interface in Emacs Lisp to
same properties. Thus, editing does not preserve the distinction
between one interval and two.
- Suppose we ``fix'' this problem by coalescing the two intervals when
+ Suppose we attempt to fix this problem by coalescing the two intervals when
the text is inserted. That works fine if the buffer originally was a
single interval. But suppose instead that we have two adjacent
intervals with the same properties, and we kill the text of one interval
@node Substitution
@section Substituting for a Character Code
+@cindex replace characters in region
+@cindex substitute characters
The following functions replace characters within a specified region
based on their character codes.
Normally, this command puts point before the inserted text, and the
mark after it. However, if the optional second argument @var{beforep}
is non-@code{nil}, it puts the mark before and point after.
-You can pass a non-@code{nil} second argument @var{beforep} to this
-function interactively by supplying any prefix argument.
+
+When called interactively, the command defaults to putting point after
+text, and a prefix argument inverts this behavior.
If the register contains a rectangle, then the rectangle is inserted
with its upper left corner at point. This means that text is inserted
changed in the future.
@end deffn
+@defun register-read-with-preview prompt
+@cindex register preview
+This function reads and returns a register name, prompting with
+@var{prompt} and possibly showing a preview of the existing registers
+and their contents. The preview is shown in a temporary window, after
+the delay specified by the user option @code{register-preview-delay},
+if its value and @code{register-alist} are both non-@code{nil}. The
+preview is also shown if the user requests help (e.g., by typing the
+help character). We recommend that all interactive commands which
+read register names use this function.
+@end defun
+
@node Transposition
@section Transposition of Text
@cindex cryptographic hash
Emacs has built-in support for computing @dfn{cryptographic hashes}.
-A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint''
+A cryptographic hash, or @dfn{checksum}, is a digital fingerprint
of a piece of data (e.g., a block of text) which can be used to check
that you have an unaltered copy of that data.
SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the
oldest of these algorithms, and is commonly used in @dfn{message
digests} to check the integrity of messages transmitted over a
-network. MD5 is not ``collision resistant'' (i.e., it is possible to
+network. MD5 is not collision resistant (i.e., it is possible to
deliberately design different pieces of data which have the same MD5
hash), so you should not used it for anything security-related. A
similar theoretical weakness also exists in SHA-1. Therefore, for
coding instead.
@end defun
+@defun buffer-hash &optional buffer-or-name
+Return a hash of @var{buffer-or-name}. If @code{nil}, this defaults
+to the current buffer. As opposed to @code{secure-hash}, this
+function computes the hash based on the internal representation of the
+buffer, disregarding any coding systems. It's therefore only useful
+when comparing two buffers running in the same Emacs, and is not
+guaranteed to return the same hash between different Emacs versions.
+It should be somewhat more efficient on larger buffers than
+@code{secure-hash} is, and should not allocate more memory.
+@c Note that we do not document what hashing function we're using, or
+@c even whether it's a cryptographic hash, since that may change
+@c according to what we find useful.
+@end defun
+
@node Parsing HTML/XML
@section Parsing HTML and XML
@cindex parsing html
When Emacs is compiled with libxml2 support, the following functions
are available to parse HTML or XML text into Lisp object trees.
-@defun libxml-parse-html-region start end &optional base-url
+@defun libxml-parse-html-region start end &optional base-url discard-comments
This function parses the text between @var{start} and @var{end} as
HTML, and returns a list representing the HTML @dfn{parse tree}. It
-attempts to handle ``real world'' HTML by robustly coping with syntax
+attempts to handle real-world HTML by robustly coping with syntax
mistakes.
The optional argument @var{base-url}, if non-@code{nil}, should be a
string specifying the base URL for relative URLs occurring in links.
+If the optional argument @var{discard-comments} is non-@code{nil},
+then the parse tree is created without any comments.
+
In the parse tree, each HTML node is represented by a list in which
the first element is a symbol representing the node name, the second
element is an alist of node attributes, and the remaining elements are
@end example
@noindent
-A call to @code{libxml-parse-html-region} returns this:
+A call to @code{libxml-parse-html-region} returns this @acronym{DOM}
+(document object model):
@example
-(html ()
- (head ())
- (body ((width . "101"))
- (div ((class . "thing"))
- "Foo"
- (div ()
- "Yes"))))
+(html nil
+ (head nil)
+ (body ((width . "101"))
+ (div ((class . "thing"))
+ "Foo"
+ (div nil
+ "Yes"))))
@end example
@end defun
@end defun
@cindex parsing xml
-@defun libxml-parse-xml-region start end &optional base-url
+@defun libxml-parse-xml-region start end &optional base-url discard-comments
This function is the same as @code{libxml-parse-html-region}, except
that it parses the text as XML rather than HTML (so it is stricter
about syntax).
@end defun
+@menu
+* Document Object Model:: Access, manipulate and search the @acronym{DOM}.
+@end menu
+
+@node Document Object Model
+@subsection Document Object Model
+@cindex HTML DOM
+@cindex XML DOM
+@cindex DOM
+@cindex Document Object Model
+
+The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the
+other @acronym{XML} parsing functions) is a tree structure where each
+node has a node name (called a @dfn{tag}), and optional key/value
+@dfn{attribute} list, and then a list of @dfn{child nodes}. The child
+nodes are either strings or @acronym{DOM} objects.
+
+@example
+(body ((width . "101"))
+ (div ((class . "thing"))
+ "Foo"
+ (div nil
+ "Yes")))
+@end example
+
+@defun dom-node tag &optional attributes &rest children
+This function creates a @acronym{DOM} node of type @var{tag}. If
+given, @var{attributes} should be a key/value pair list.
+If given, @var{children} should be @acronym{DOM} nodes.
+@end defun
+
+The following functions can be used to work with this structure. Each
+function takes a @acronym{DOM} node, or a list of nodes. In the
+latter case, only the first node in the list is used.
+
+Simple accessors:
+
+@table @code
+@item dom-tag @var{node}
+Return the @dfn{tag} (also called ``node name'') of the node.
+
+@item dom-attr @var{node} @var{attribute}
+Return the value of @var{attribute} in the node. A common usage
+would be:
+
+@lisp
+(dom-attr img 'href)
+=> "http://fsf.org/logo.png"
+@end lisp
+
+@item dom-children @var{node}
+Return all the children of the node.
+
+@item dom-non-text-children @var{node}
+Return all the non-string children of the node.
+
+@item dom-attributes @var{node}
+Return the key/value pair list of attributes of the node.
+
+@item dom-text @var{node}
+Return all the textual elements of the node as a concatenated string.
+
+@item dom-texts @var{node}
+Return all the textual elements of the node, as well as the textual
+elements of all the children of the node, recursively, as a
+concatenated string. This function also takes an optional separator
+to be inserted between the textual elements.
+
+@item dom-parent @var{dom} @var{node}
+Return the parent of @var{node} in @var{dom}.
+@end table
+
+The following are functions for altering the @acronym{DOM}.
+
+@table @code
+@item dom-set-attribute @var{node} @var{attribute} @var{value}
+Set the @var{attribute} of the node to @var{value}.
+
+@item dom-append-child @var{node} @var{child}
+Append @var{child} as the last child of @var{node}.
+
+@item dom-add-child-before @var{node} @var{child} @var{before}
+Add @var{child} to @var{node}'s child list before the @var{before}
+node. If @var{before} is @code{nil}, make @var{child} the first child.
+
+@item dom-set-attributes @var{node} @var{attributes}
+Replace all the attributes of the node with a new key/value list.
+@end table
+
+The following are functions for searching for elements in the
+@acronym{DOM}. They all return lists of matching nodes.
+
+@table @code
+@item dom-by-tag @var{dom} @var{tag}
+Return all nodes in @var{dom} that are of type @var{tag}. A typical
+use would be:
+
+@lisp
+(dom-by-tag dom 'td)
+=> '((td ...) (td ...) (td ...))
+@end lisp
+
+@item dom-by-class @var{dom} @var{match}
+Return all nodes in @var{dom} that have class names that match
+@var{match}, which is a regular expression.
+
+@item dom-by-style @var{dom} @var{style}
+Return all nodes in @var{dom} that have styles that match @var{match},
+which is a regular expression.
+
+@item dom-by-id @var{dom} @var{style}
+Return all nodes in @var{dom} that have IDs that match @var{match},
+which is a regular expression.
+
+@item dom-strings @var{dom}
+Return all strings in @var{DOM}.
+
+@end table
+
+Utility functions:
+
+@table @code
+@item dom-pp @var{dom} &optional @var{remove-empty}
+Pretty-print @var{dom} at point. If @var{remove-empty}, don't print
+textual nodes that just contain white-space.
+@end table
+
+
@node Atomic Changes
@section Atomic Change Groups
@cindex atomic changes
@defun prepare-change-group &optional buffer
This function sets up a change group for buffer @var{buffer}, which
-defaults to the current buffer. It returns a ``handle'' that
+defaults to the current buffer. It returns a handle that
represents the change group. You must use this handle to activate the
change group and subsequently to finish it.
@end defun