@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/text
-@node Text, Non-ASCII Characters, Markers, Top
+@node Text
@chapter Text
@cindex text
* Case Changes:: Case conversion of parts of the buffer.
* Text Properties:: Assigning Lisp property lists to text characters.
* Substitution:: Replacing a given character wherever it appears.
-* Transposition:: Swapping two portions of a buffer.
* Registers:: How registers are implemented. Accessing the text or
position stored in a register.
+* Transposition:: Swapping two portions of a buffer.
+* Decompression:: Dealing with compressed data.
* Base 64:: Conversion to or from base 64 encoding.
-* MD5 Checksum:: Compute the MD5 "message digest"/"checksum".
-* Parsing HTML:: Parsing HTML and XML.
+* Checksum/Hash:: Computing cryptographic hashes.
+* Parsing HTML/XML:: Parsing HTML and XML.
* Atomic Changes:: Installing several buffer changes "atomically".
* Change Hooks:: Supplying functions to be run when text is changed.
@end menu
@defun buffer-substring start end
This function returns a string containing a copy of the text of the
region defined by positions @var{start} and @var{end} in the current
-buffer. If the arguments are not positions in the accessible portion of
-the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
-error.
-
-It is not necessary for @var{start} to be less than @var{end}; the
-arguments can be given in either order. But most often the smaller
-argument is written first.
+buffer. If the arguments are not positions in the accessible portion
+of the buffer, @code{buffer-substring} signals an
+@code{args-out-of-range} error.
Here's an example which assumes Font-Lock mode is not enabled:
properties, just the characters themselves. @xref{Text Properties}.
@end defun
-@defun filter-buffer-substring start end &optional delete noprops
-This function passes the buffer text between @var{start} and @var{end}
-through the filter functions specified by the variable
-@code{buffer-substring-filters}, and returns the value from the last
-filter function. If @code{buffer-substring-filters} is @code{nil},
-the value is the unaltered text from the buffer, what
+@defun buffer-string
+This function returns the contents of the entire accessible portion of
+the current buffer, as a string.
+@end defun
+
+@defun filter-buffer-substring start end &optional delete
+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}, this function deletes the text
+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}.
-If @var{noprops} is non-@code{nil}, the final string returned does not
-include text properties, while the string passed through the filters
-still includes text properties from the buffer text.
-
Lisp code should use this function instead of @code{buffer-substring},
@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{buffer-substring-filters} 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
-@defvar buffer-substring-filters
-This variable should be a list of functions that accept a single
-argument, a string, and return a 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
-used as the return value of @code{filter-buffer-substring}.
-
-As a special convention, point is set to the start of the buffer text
-being operated on (i.e., the @var{start} argument for
-@code{filter-buffer-substring}) before these functions are called.
-
-If this variable is @code{nil}, no filtering is performed.
+@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
-@defun buffer-string
-This function returns the contents of the entire accessible portion of
-the current buffer as a string. It is equivalent to
-
-@example
-(buffer-substring (point-min) (point-max))
-@end example
-
-@example
-@group
----------- Buffer: foo ----------
-This is the contents of buffer foo
-
----------- Buffer: foo ----------
+@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 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
+returns the buffer-substring between @var{start} and @var{end}
+(processed by any @code{buffer-substring-filters}) and optionally
+deletes the original text from the buffer. In most cases, the hook
+function will call @var{fun} once, and then do its own processing of
+the result. The next hook function receives a @var{fun} equivalent to
+this, and so on. The actual return value is the result of all the
+hook functions acting in sequence.
+@end defvar
-(buffer-string)
- @result{} "This is the contents of buffer foo\n"
-@end group
-@end example
-@end defun
+@defvar buffer-substring-filters
+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
-This function returns the symbol (or word) at or near point, as a string.
-The return value includes no text properties.
+This function returns the symbol (or word) at or near point, as a
+string. The return value includes no text properties.
If the optional argument @var{really-word} is non-@code{nil}, it finds a
word; otherwise, it finds a symbol (which includes both word
the inserted text, regardless of the markers' insertion type.
Insertion functions signal an error if the current buffer is
-read-only or if they insert within read-only text.
+read-only (@pxref{Read Only Buffers}) or if they insert within
+read-only text (@pxref{Special Properties}).
These functions copy text characters from strings and buffers along
with their properties. The inserted characters have exactly the same
overlay.
@end defun
-@defun insert-char character count &optional inherit
-This function inserts @var{count} instances of @var{character} into the
-current buffer before point. The argument @var{count} should be an
-integer, and @var{character} must be a character. The value is @code{nil}.
+@deffn Command insert-char character &optional count inherit
+This command inserts @var{count} instances of @var{character} into the
+current buffer before point. The argument @var{count} must be an
+integer, and @var{character} must be a character.
+
+If called interactively, this command prompts for @var{character}
+using its Unicode name or its code point. @xref{Inserting Text,,,
+emacs, The GNU Emacs Manual}.
This function does not convert unibyte character codes 128 through 255
to multibyte characters, not even if the current buffer is a multibyte
buffer. @xref{Converting Representations}.
-If @var{inherit} is non-@code{nil}, then the inserted characters inherit
+If @var{inherit} is non-@code{nil}, the inserted characters inherit
sticky text properties from the two characters before and after the
insertion point. @xref{Sticky Properties}.
-@end defun
+@end deffn
@defun insert-buffer-substring from-buffer-or-name &optional start end
This function inserts a portion of buffer @var{from-buffer-or-name}
-(which must already exist) into the current buffer before point. The
-text inserted is the region between @var{start} and @var{end}. (These
-arguments default to the beginning and end of the accessible portion of
-that buffer.) This function returns @code{nil}.
+into the current buffer before point. The text inserted is the region
+between @var{start} (inclusive) and @var{end} (exclusive). (These
+arguments default to the beginning and end of the accessible portion
+of that buffer.) This function returns @code{nil}.
In this example, the form is executed with buffer @samp{bar} as the
current buffer. We assume that buffer @samp{bar} is initially empty.
In an interactive call, @var{count} is the numeric prefix argument.
+@c FIXME: This variable is obsolete since 23.1.
Self-insertion translates the input character through
@code{translation-table-for-input}. @xref{Translation of Characters}.
responsible for calling @code{blink-paren-function} when the inserted
character has close parenthesis syntax (@pxref{Blinking}).
+@vindex post-self-insert-hook
+The final thing this command does is to run the hook
+@code{post-self-insert-hook}. You could use this to automatically
+reindent text as it is typed, for example.
+
Do not try substituting your own definition of
@code{self-insert-command} for the standard one. The editor command
loop handles this function specially.
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{nil}.
@end deffn
+@c There is also cycle-spacing, but I cannot see it being useful in
+@c Lisp programs, so it is not mentioned here.
+
@deffn Command delete-blank-lines
This function deletes blank lines surrounding point. If point is on a
blank line with one or more blank lines before or after it, then all but
blank lines immediately following it.
A blank line is defined as a line containing only tabs and spaces.
+@c and the Newline character?
@code{delete-blank-lines} returns @code{nil}.
@end deffn
+@deffn Command delete-trailing-whitespace 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
+interactively with the mark inactive, or called from Lisp with
+@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
+
@node The Kill Ring
@section The Kill Ring
@cindex kill ring
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
+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
@end menu
@node Kill Ring Concepts
-@comment node-name, next, previous, up
@subsection Kill Ring Concepts
The kill ring records killed text as strings in a list, most recent
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
+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.
@node Kill Functions
-@comment node-name, next, previous, up
@subsection Functions for Killing
@code{kill-region} is the usual subroutine for killing text. Any
@node Yanking
@subsection Yanking
- Yanking means inserting text from the kill ring, but it does
-not insert the text blindly. Yank commands and some other commands
-use @code{insert-for-yank} to perform special processing on the
-text that they copy into the buffer.
+ Yanking means inserting text from the kill ring, but it does not
+insert the text blindly. The @code{yank} command, and related
+commands, use @code{insert-for-yank} to perform special processing on
+the text before it is inserted.
@defun insert-for-yank string
-This function normally works like @code{insert} except that it doesn't
-insert the text properties (@pxref{Text Properties}) in the list
-variable @code{yank-excluded-properties}. However, if any part of
-@var{string} has a non-@code{nil} @code{yank-handler} text property,
-that property can do various special processing on that part of the
-text being inserted.
+This function works like @code{insert}, except that it processes the
+text in @var{string} according to the @code{yank-handler} text
+property, as well as the variables @code{yank-handled-properties} and
+@code{yank-excluded-properties} (see below), before inserting the
+result into the current buffer.
@end defun
@defun insert-buffer-substring-as-yank buf &optional start end
-This function resembles @code{insert-buffer-substring} except that it
-doesn't insert the text properties in the
-@code{yank-excluded-properties} list.
+This function resembles @code{insert-buffer-substring}, except that it
+processes the text according to @code{yank-handled-properties} and
+@code{yank-excluded-properties}. (It does not handle the
+@code{yank-handler} property, which does not normally occur in buffer
+text anyway.)
@end defun
- You can put a @code{yank-handler} text property on all or part of
-the text to control how it will be inserted if it is yanked. The
-@code{insert-for-yank} function looks for that property. The property
-value must be a list of one to four elements, with the following
-format (where elements after the first may be omitted):
+@c FIXME: Add an index for yank-handler.
+ If you put a @code{yank-handler} text property on all or part of a
+string, that alters how @code{insert-for-yank} inserts the string. If
+different parts of the string have different @code{yank-handler}
+values (comparison being done with @code{eq}), each substring is
+handled separately. The property value must be a list of one to four
+elements, with the following format (where elements after the first
+may be omitted):
@example
(@var{function} @var{param} @var{noexclude} @var{undo})
@table @var
@item function
-When @var{function} is present and non-@code{nil}, it is called instead of
-@code{insert} to insert the string. @var{function} takes one
-argument---the string to insert.
+When @var{function} is non-@code{nil}, it is called instead of
+@code{insert} to insert the string, with one argument---the string to
+insert.
@item param
If @var{param} is present and non-@code{nil}, it replaces @var{string}
-(or the part of @var{string} being processed) as the object passed to
-@var{function} (or @code{insert}); for example, if @var{function} is
-@code{yank-rectangle}, @var{param} should be a list of strings to
-insert as a rectangle.
+(or the substring of @var{string} being processed) as the object
+passed to @var{function} (or @code{insert}). For example, if
+@var{function} is @code{yank-rectangle}, @var{param} should be a list
+of strings to insert as a rectangle.
@item noexclude
-If @var{noexclude} is present and non-@code{nil}, the normal removal of the
-yank-excluded-properties is not performed; instead @var{function} is
-responsible for removing those properties. This may be necessary
-if @var{function} adjusts point before or after inserting the object.
+If @var{noexclude} is present and non-@code{nil}, that disables the
+normal action of @code{yank-handled-properties} and
+@code{yank-excluded-properties} on the inserted string.
@item undo
If @var{undo} is present and non-@code{nil}, it is a function that will be
@end table
@cindex yanking and text properties
+@defopt yank-handled-properties
+This variable specifies special text property handling conditions for
+yanked text. It takes effect after the text has been inserted (either
+normally, or via the @code{yank-handler} property), and prior to
+@code{yank-excluded-properties} taking effect.
+
+The value should be an alist of elements @code{(@var{prop}
+. @var{fun})}. Each alist element is handled in order. The inserted
+text is scanned for stretches of text having text properties @code{eq}
+to @var{prop}; for each such stretch, @var{fun} is called with three
+arguments: the value of the property, and the start and end positions
+of the text.
+@end defopt
+
@defopt yank-excluded-properties
-Yanking discards certain text properties from the yanked text, as
-described above. The value of this variable is the list of properties
-to discard. Its default value contains properties that might lead to
-annoying results, such as causing the text to respond to the mouse or
-specifying key bindings.
+The value of this variable is the list of properties to remove from
+inserted text. Its default value contains properties that might lead
+to annoying results, such as causing the text to respond to the mouse
+or specifying key bindings. It takes effect after
+@code{yank-handled-properties}.
@end defopt
+
@node Yank Commands
-@comment node-name, next, previous, up
@subsection Functions for Yanking
This section describes higher-level commands for yanking, which are
@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
the other strings are pushed onto the kill ring, for easy access by
@code{yank-pop}.
-The normal use of this function is to get the window system's primary
-selection as the most recent kill, even if the selection belongs to
+The normal use of this function is to get the window system's
+clipboard as the most recent kill, even if the selection belongs to
another application. @xref{Window System Selections}. However, if
-the selection was provided by the current Emacs session, this function
-should return @code{nil}. (If it is hard to tell whether Emacs or
-some other program provided the selection, it should be good enough to
-use @code{string=} to compare it with the last text Emacs provided.)
+the clipboard contents come from the current Emacs session, this
+function should return @code{nil}.
@end defvar
@defvar interprogram-cut-function
If the value is a function, @code{kill-new} and @code{kill-append} call
it with the new first element of the kill ring as the argument.
-The normal use of this function is to set the window system's primary
-selection from the newly killed text.
-@xref{Window System Selections}.
+The normal use of this function is to put newly killed text in the
+window system's clipboard. @xref{Window System Selections}.
@end defvar
@node Internals of Kill Ring
-@comment node-name, next, previous, up
@subsection Internals of the Kill Ring
The variable @code{kill-ring} holds the kill ring contents, in the
@end defopt
@node Undo
-@comment node-name, next, previous, up
@section Undo
@cindex redo
@defvar buffer-undo-list
This buffer-local variable's value is the undo list of the current
-buffer. A value of @code{t} disables the recording of undo information.
+buffer. A value of @code{t} disables the recording of undo information.
@end defvar
Here are the kinds of elements an undo list can have:
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{high} . @var{low})
+@item (t . @var{time-flag})
This kind of element indicates that an unmodified buffer became
-modified. The elements @var{high} and @var{low} are two integers, each
-recording 16 bits of the visited file's modification time as of when it
-was previously visited or saved. @code{primitive-undo} uses those
+modified. A @var{time-flag} of the form
+@code{(@var{sec-high} @var{sec-low} @var{microsec}
+@var{picosec})} represents the visited file's modification time as of
+when it was previously visited or saved, using the same format as
+@code{current-time}; see @ref{Time of Day}.
+A @var{time-flag} of 0 means the buffer does not correspond to any file;
+@minus{}1 means the visited file previously did not exist.
+@code{primitive-undo} uses these
values to determine whether to mark the buffer as unmodified once again;
-it does so only if the file's modification time matches those numbers.
+it does so only if the file's status matches that of @var{time-flag}.
@item (nil @var{property} @var{value} @var{beg} . @var{end})
This kind of element records a change in a text property.
@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
@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}.
+by @var{delta} characters. 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.
the undo list of @var{buffer-or-name} is already disabled, this function
has no effect.
-This function returns @code{nil}.
+In an interactive call, BUFFER-OR-NAME is the current buffer. You
+cannot specify any other buffer. This function returns @code{nil}.
@end deffn
As editing continues, undo lists get longer and longer. To prevent
@end defopt
@node Filling
-@comment node-name, next, previous, up
@section Filling
@cindex filling text
a regular expression; if it matches the beginning of a line, that line
is treated as a citation marker.
+@c FIXME: "That mode" is confusing. It isn't a major/minor mode.
Ordinarily, @code{fill-individual-paragraphs} regards each change in
indentation as starting a new paragraph. If
@code{fill-individual-varying-indent} is non-@code{nil}, then only
@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.
+newlines'' act as paragraph separators. @xref{Hard and Soft
+Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
@end defvar
@node Margins
@section Margins for Filling
+@cindex margins, filling
@defopt fill-prefix
This buffer-local variable, if non-@code{nil}, specifies a string of
@defopt left-margin
This variable specifies the base left margin column. In Fundamental
-mode, @kbd{C-j} indents to this column. This variable automatically
+mode, @kbd{RET} indents to this column. This variable automatically
becomes buffer-local when set in any fashion.
@end defopt
@end defopt
@node Auto Filling
-@comment node-name, next, previous, up
@section Auto Filling
@cindex filling, automatic
@cindex Auto Fill mode
+@c FIXME: I don't think any of the variables below is a/an normal/abnormal hook.
Auto Fill mode is a minor mode that fills lines automatically as text
is inserted. This section describes the hook used by Auto Fill mode.
For a description of functions that you can call explicitly to fill and
The value of @code{auto-fill-function} is @code{do-auto-fill} when
Auto-Fill mode is enabled. That is a function whose sole purpose is to
implement the usual strategy for breaking a line.
-
-@quotation
-In older Emacs versions, this variable was named @code{auto-fill-hook},
-but since it is not called with the standard convention for hooks, it
-was renamed to @code{auto-fill-function} in version 19.
-@end quotation
@end defvar
@defvar normal-auto-fill-function
@group
(sort-subr reverse
(function
- (lambda ()
- (while (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1))))
+ (lambda ()
+ (while (and (not (eobp))
+ (looking-at paragraph-separate))
+ (forward-line 1))))
'forward-paragraph)
@end group
@end example
@end deffn
@node Columns
-@comment node-name, next, previous, up
@section Counting Columns
@cindex columns
@cindex counting columns
When called interactively, @var{column} is the value of prefix numeric
argument. If @var{column} is not an integer, an error is signaled.
+@c This behavior used to be documented until 2013/08.
+@ignore
If column @var{column} is beyond the end of the line, point moves to
the end of the line. If @var{column} is negative, point moves to the
beginning of the line.
+@end ignore
If it is impossible to move to column @var{column} because that is in
the middle of a multicolumn character such as a tab, point moves to the
This section describes the primitive functions used to count and
insert indentation. The functions in the following sections use these
-primitives. @xref{Width}, for related functions.
+primitives. @xref{Size of Displayed Text}, for related functions.
@defun current-indentation
@comment !!Type Primitive Function
describes the mechanism of the @key{TAB} key and how to control it.
The functions in this section return unpredictable values.
-@defvar indent-line-function
-This variable's value is the function to be used by @key{TAB} (and
-various commands) to indent the current line. The command
-@code{indent-according-to-mode} does little more than call this function.
+@deffn Command indent-for-tab-command &optional rigid
+This is the command bound to @key{TAB} in most editing modes. Its
+usual action is to indent the current line, but it can alternatively
+insert a tab character or indent a region.
+
+Here is what it does:
+
+@itemize
+@item
+First, it checks whether Transient Mark mode is enabled and the region
+is active. If so, it called @code{indent-region} to indent all the
+text in the region (@pxref{Region Indent}).
+
+@item
+Otherwise, if the indentation function in @code{indent-line-function}
+is @code{indent-to-left-margin} (a trivial command that inserts a tab
+character), or if the variable @code{tab-always-indent} specifies that
+a tab character ought to be inserted (see below), then it inserts a
+tab character.
+
+@item
+Otherwise, it indents the current line; this is done by calling the
+function in @code{indent-line-function}. If the line is already
+indented, and the value of @code{tab-always-indent} is @code{complete}
+(see below), it tries completing the text at point.
+@end itemize
-In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
-mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
-The default value is @code{indent-relative}. @xref{Auto-Indentation}.
+If @var{rigid} is non-@code{nil} (interactively, with a prefix
+argument), then after this command indents a line or inserts a tab, it
+also rigidly indents the entire balanced expression which starts at
+the beginning of the current line, in order to reflect the new
+indentation. This argument is ignored if the command indents the
+region.
+@end deffn
+
+@defvar indent-line-function
+This variable's value is the function to be used by
+@code{indent-for-tab-command}, and various other indentation commands,
+to indent the current line. It is usually assigned by the major mode;
+for instance, Lisp mode sets it to @code{lisp-indent-line}, C mode
+sets it to @code{c-indent-line}, and so on. The default value is
+@code{indent-relative}. @xref{Auto-Indentation}.
@end defvar
@deffn Command indent-according-to-mode
indent the current line in a way appropriate for the current major mode.
@end deffn
-@deffn Command indent-for-tab-command &optional rigid
-This command calls the function in @code{indent-line-function} to
-indent the current line; however, if that function is
-@code{indent-to-left-margin}, @code{insert-tab} is called instead.
-(That is a trivial command that inserts a tab character.) If
-@var{rigid} is non-@code{nil}, this function also rigidly indents the
-entire balanced expression that starts at the beginning of the current
-line, to reflect change in indentation of the current line.
-@end deffn
-
@deffn Command newline-and-indent
This function inserts a newline, then indents the new line (the one
-following the newline just inserted) according to the major mode.
-
-It does indentation by calling the current @code{indent-line-function}.
-In programming language modes, this is the same thing @key{TAB} does,
-but in some text modes, where @key{TAB} inserts a tab,
-@code{newline-and-indent} indents to the column specified by
-@code{left-margin}.
+following the newline just inserted) according to the major mode. It
+does indentation by calling @code{indent-according-to-mode}.
@end deffn
@deffn Command reindent-then-newline-and-indent
-@comment !!SourceFile simple.el
This command reindents the current line, inserts a newline at point,
and then indents the new line (the one following the newline just
-inserted).
-
-This command does indentation on both lines according to the current
-major mode, by calling the current value of @code{indent-line-function}.
-In programming language modes, this is the same thing @key{TAB} does,
-but in some text modes, where @key{TAB} inserts a tab,
-@code{reindent-then-newline-and-indent} indents to the column specified
-by @code{left-margin}.
+inserted). It does indentation on both lines by calling
+@code{indent-according-to-mode}.
@end deffn
+@defopt tab-always-indent
+This variable can be used to customize the behavior of the @key{TAB}
+(@code{indent-for-tab-command}) command. If the value is @code{t}
+(the default), the command normally just indents the current line. If
+the value is @code{nil}, the command indents the current line only if
+point is at the left margin or in the line's indentation; otherwise,
+it inserts a tab character. If the value is @code{complete}, the
+command first tries to indent the current line, and if the line was
+already indented, it calls @code{completion-at-point} to complete the
+text at point (@pxref{Completion in Buffers}).
+@end defopt
+
@node Region Indent
@subsection Indenting an Entire Region
@end defvar
@deffn Command indent-rigidly start end count
-This command indents all lines starting between @var{start}
+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
-rigid unit. Consequently, this command is useful not only for indenting
-regions of unindented text, but also for indenting regions of formatted
-code.
+rigid unit.
-For example, if @var{count} is 3, this command adds 3 columns of
-indentation to each of the lines beginning in the region specified.
+This is useful not only for indenting regions of unindented text, but
+also for indenting regions of formatted code. For example, if
+@var{count} is 3, this command adds 3 columns of indentation to every
+line that begins in the specified region.
-In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
-@code{indent-rigidly} to indent the text copied from the message being
-replied to.
+If called interactively with no prefix argument, this command invokes
+a transient mode for adjusting indentation rigidly. @xref{Indentation
+Commands,,, emacs, The GNU Emacs Manual}.
@end deffn
@deffn Command indent-code-rigidly start end columns &optional nochange-regexp
@end deffn
@node Indent Tabs
-@comment node-name, next, previous, up
@subsection Adjustable ``Tab Stops''
@cindex tabs stops for indentation
@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
-as the column to indent to. It does nothing if no such element is
-found.
+stop column defined by @code{tab-stop-list}.
@end deffn
@defopt tab-stop-list
-This variable is the list of tab stop columns used by
-@code{tab-to-tab-stops}. The elements should be integers in increasing
-order. The tab stop columns need not be evenly spaced.
-
-Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
-interactively.
+This variable defines the tab stop columns used by @code{tab-to-tab-stop}.
+It should be either @code{nil}, or a list of increasing integers,
+which need not be evenly spaced. The list is implicitly
+extended to infinity through repetition of the interval between the
+last and penultimate elements (or @code{tab-width} if the list has
+fewer than two elements). A value of @code{nil} means a tab stop
+every @code{tab-width} columns.
+
+Use @kbd{M-x edit-tab-stops} to edit the location of tab stops interactively.
@end defopt
@node Motion by Indent
@end deffn
@node Case Changes
-@comment node-name, next, previous, up
@section Case Changes
@cindex case conversion in buffers
@end group
@group
-(capitalize-region 1 44)
+(capitalize-region 1 37)
@result{} nil
---------- Buffer: foo ----------
text properties are considered, since strings never have overlays.
@end defun
+@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)
+@var{position}.
+@end defun
+
@defun get-char-property-and-overlay position prop &optional object
This is like @code{get-char-property}, but gives extra information
about the overlay that the property value comes from.
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}:
+@defun add-face-text-property start end face &optional appendp object
+This function acts on the text between @var{start} and @var{end},
+adding the face @var{face} to the @code{face} text property.
+@var{face} should be a valid value for the @code{face} property
+(@pxref{Special Properties}), such as a face name or an anonymous face
+(@pxref{Faces}).
+
+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
+optional argument @var{append} is non-@code{nil}, @var{face} is
+appended to the end of the list instead. Note that in a face list,
+the first occurring value for each attribute takes precedence.
+
+For example, the following code would assign a italicized green face
+to the text between @var{start} and @var{end}:
+
+@example
+(add-face-text-property @var{start} @var{end} 'italic)
+(add-face-text-property @var{start} @var{end} '(:foreground "red"))
+(add-face-text-property @var{start} @var{end} '(:foreground "green"))
+@end example
+
+The optional argument @var{object}, if non-@code{nil}, specifies a
+buffer or string to act on, rather than the current buffer. If
+@var{object} is a string, then @var{start} and @var{end} are
+zero-based indices into the string.
+@end defun
+
+ The easiest way to make a string with text properties is with
+@code{propertize}:
@defun propertize string &rest properties
-This function returns a copy of @var{string} which has the text
-properties @var{properties}. These properties apply to all the
-characters in the string that is returned. Here is an example that
-constructs a string with a @code{face} property and a @code{mouse-face}
-property:
+This function returns a copy of @var{string} with the text properties
+@var{properties} added. These properties apply to all the characters
+in the string that is returned. Here is an example that constructs a
+string with a @code{face} property and a @code{mouse-face} property:
@smallexample
(propertize "foo" 'face 'italic
comparing property values. In all cases, @var{object} defaults to the
current buffer.
- For high performance, it's very important to use the @var{limit}
+ For good performance, it's very important to use the @var{limit}
argument to these functions, especially the ones that search for a
single property---otherwise, they may spend a long time scanning to the
end of the buffer, if the property you are interested in does not change.
@defun next-property-change pos &optional object limit
The function scans the text forward from position @var{pos} in the
-string or buffer @var{object} till it finds a change in some text
+string or buffer @var{object} until it finds a change in some text
property, then returns the position of the change. In other words, it
returns the position of the first character beyond @var{pos} whose
properties are not identical to those of the character just after
@var{pos}.
If @var{limit} is non-@code{nil}, then the scan ends at position
-@var{limit}. If there is no property change before that point,
-@code{next-property-change} returns @var{limit}.
+@var{limit}. If there is no property change before that point, this
+function returns @var{limit}.
The value is @code{nil} if the properties remain unchanged all the way
to the end of @var{object} and @var{limit} is @code{nil}. If the value
@table @code
@cindex property category of text character
+@c FIXME: Isn't @kindex for keyboard commands?
@kindex category @r{(text property)}
@item category
If a character has a @code{category} property, we call it the
@item face
@cindex face codes of text
@kindex face @r{(text property)}
-You can use the property @code{face} to control the font and color of
-text. @xref{Faces}, for more information.
-
-@code{face} can be the following:
+The @code{face} property controls the appearance of the character
+(@pxref{Faces}). The value of the property can be the following:
@itemize @bullet
@item
A face name (a symbol or string).
@item
-A property list of face attributes. This has the
-form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
-face attribute name and @var{value} is a meaningful value for that
-attribute. With this feature, you do not need to create a face each
-time you want to specify a particular attribute for certain text.
-@xref{Face Attributes}.
-@end itemize
+An anonymous face: a property list of the form @code{(@var{keyword}
+@var{value} @dots{})}, where each @var{keyword} is a face attribute
+name and @var{value} is a value for that attribute.
-@code{face} can also be a list, where each element uses one of the
-forms listed above.
+@item
+A list of faces. Each list element should be either a face name or an
+anonymous face. This specifies a face which is an aggregate of the
+attributes of each of the listed faces. Faces occurring earlier in
+the list have higher priority.
+
+@item
+A cons cell of the form @code{(foreground-color . @var{color-name})}
+or @code{(background-color . @var{color-name})}. This specifies the
+foreground or background color, similar to @code{(:foreground
+@var{color-name})} or @code{(:background @var{color-name})}. This
+form is supported for backward compatibility only, and should be
+avoided.
+@end itemize
Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
dynamically updating the @code{face} property of characters based on
the context.
+The @code{add-face-text-property} function provides a convenient way
+to set this text property. @xref{Changing Properties}.
+
@item font-lock-face
@kindex font-lock-face @r{(text property)}
This property specifies a value for the @code{face} property that Font
@code{mouse-face} property value.
Emacs ignores all face attributes from the @code{mouse-face} property
-that alter the text size (e.g. @code{:height}, @code{:weight}, and
+that alter the text size (e.g., @code{:height}, @code{:weight}, and
@code{:slant}). Those attributes are always the same as for the
unhighlighted text.
@item cursor
@kindex cursor @r{(text property)}
-Normally, the cursor is displayed at the end of any overlay and text
-property strings present at the current buffer position. You can
-place the cursor on any desired character of these strings by giving
-that character a non-@code{nil} @code{cursor} text property. In
-addition, if the value of the @code{cursor} property of an overlay
-string is an integer number, it specifies the number of buffer's
-character positions associated with the overlay string; this way,
-Emacs will display the cursor on the character with that property
-regardless of whether the current buffer position is actually covered
-by the overlay. Specifically, if the value of the @code{cursor}
-property of a character is the number @var{n}, the cursor will be
-displayed on this character for any buffer position in the range
-@code{[@var{ovpos}..@var{ovpos}+@var{n}]}, where @var{ovpos} is the
-starting buffer position covered by the overlay (@pxref{Managing
-Overlays}).
+Normally, the cursor is displayed at the beginning or the end of any
+overlay and text property strings present at the current buffer
+position. You can place the cursor on any desired character of these
+strings by giving that character a non-@code{nil} @code{cursor} text
+property. In addition, if the value of the @code{cursor} property is
+an integer, it specifies the number of buffer's character
+positions, starting with the position where the overlay or the
+@code{display} property begins, for which the cursor should be
+displayed on that character. Specifically, if the value of the
+@code{cursor} property of a character is the number @var{n}, the
+cursor will be displayed on this character for any buffer position in
+the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos}
+is the overlay's starting position given by @code{overlay-start}
+(@pxref{Managing Overlays}), or the position where the @code{display}
+text property begins in the buffer.
+
+In other words, the string character with the @code{cursor} property
+of any non-@code{nil} value is the character where to display the
+cursor. The value of the property says for which buffer positions to
+display the cursor there. If the value is an integer @var{n},
+the cursor is displayed there when point is anywhere between the
+beginning of the overlay or @code{display} property and @var{n}
+positions after that. If the value is anything else and
+non-@code{nil}, the cursor is displayed there only when point is at
+the beginning of the @code{display} property or at
+@code{overlay-start}.
+
+@cindex cursor position for @code{display} properties and overlays
+When the buffer has many overlay strings (e.g., @pxref{Overlay
+Properties, before-string}) or @code{display} properties that are
+strings, it is a good idea to use the @code{cursor} property on these
+strings to cue the Emacs display about the places where to put the
+cursor while traversing these strings. This directly communicates to
+the display engine where the Lisp program wants to put the cursor, or
+where the user would expect the cursor.
@item pointer
@kindex pointer @r{(text property)}
@node Sticky Properties
@subsection Stickiness of Text Properties
@cindex sticky text properties
-@cindex inheritance of 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.
- In a Lisp program, you can do insertion with inheritance or without,
-depending on your 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 string being
-inserted, and no others. This is correct for programs that copy text
-from one context to another---for example, into or out of the kill ring.
-To insert with inheritance, use the special primitives described in this
-section. Self-inserting characters inherit properties because they work
-using these primitives.
+ 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
+string being inserted, and no others. This is correct for programs
+that copy text from one context to another---for example, into or out
+of the kill ring. To insert with inheritance, use the special
+primitives described in this section. Self-inserting characters
+inherit properties because they work using these primitives.
When you do insertion with inheritance, @emph{which} properties are
inherited, and from where, depends on which properties are @dfn{sticky}.
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.''
+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}
@dfn{link}.
Implementing a link involves three separate steps: (1) indicating
-clickability when the mouse moves over the link; (2) making @kbd{RET}
+clickability when the mouse moves over the link; (2) making @key{RET}
or @kbd{Mouse-2} on that link do something; and (3) setting up a
@code{follow-link} condition so that the link obeys
@code{mouse-1-click-follows-link}.
If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
the value of point instead, and moves point to the resulting position
-as well as returning it.
+in addition to returning that position.
If @var{old-pos} is at the boundary of two fields, then the acceptable
final positions depend on the argument @var{escape-from-edge}. If
@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
intervals with the same properties, and we kill the text of one interval
and yank it back. The same interval-coalescence feature that rescues
the other case causes trouble in this one: after yanking, we have just
-one interval. One again, editing does not preserve the distinction
+one interval. Once again, editing does not preserve the distinction
between one interval and two.
Insertion of text at the border between intervals also raises
questions that have no satisfactory answer.
- However, it is easy to arrange for editing to behave consistently for
-questions of the form, ``What are the properties of this character?''
-So we have decided these are the only questions that make sense; we have
-not implemented asking questions about where intervals start or end.
+ However, it is easy to arrange for editing to behave consistently
+for questions of the form, ``What are the properties of text at this
+buffer or string position?'' So we have decided these are the only
+questions that make sense; we have not implemented asking questions
+about where intervals start or end.
In practice, you can usually use the text property search functions in
place of explicit interval boundaries. You can think of them as finding
This represents a window configuration to restore in one frame, and a
position to jump to in the current buffer.
+@c FIXME: Mention frameset here.
@item @code{(@var{frame-configuration} @var{position})}
This represents a frame configuration to restore, and a position
to jump to in the current buffer.
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
- This subroutine is used by the transposition commands.
+ This function can be used to transpose stretches of text:
@defun transpose-regions start1 end1 start2 end2 &optional leave-markers
This function exchanges two nonoverlapping portions of the buffer.
all markers unrelocated.
@end defun
+@node Decompression
+@section Dealing With Compressed Data
+
+When @code{auto-compression-mode} is enabled, Emacs automatically
+uncompresses compressed files when you visit them, and automatically
+recompresses them if you alter and save them. @xref{Compressed
+Files,,, emacs, The GNU Emacs Manual}.
+
+The above feature works by calling an external executable (e.g.,
+@command{gzip}). Emacs can also be compiled with support for built-in
+decompression using the zlib library, which is faster than calling an
+external program.
+
+@defun zlib-available-p
+This function returns non-@code{nil} if built-in zlib decompression is
+available.
+@end defun
+
+@defun zlib-decompress-region start end
+This function decompresses the region between @var{start} and
+@var{end}, using built-in zlib decompression. The region should
+contain data that were compressed with gzip or zlib. On success, the
+function replaces the contents of the region with the decompressed
+data. On failure, the function leaves the region unchanged and
+returns @code{nil}. This function can be called only in unibyte
+buffers.
+@end defun
+
+
@node Base 64
@section Base 64 Encoding
@cindex base 64 encoding
@deffn Command base64-encode-region beg end &optional no-line-break
This function converts the region from @var{beg} to @var{end} into base
64 code. It returns the length of the encoded text. An error is
-signaled if a character in the region is multibyte, i.e.@: in a
+signaled if a character in the region is multibyte, i.e., in a
multibyte buffer the region must contain only characters from the
charsets @code{ascii}, @code{eight-bit-control} and
@code{eight-bit-graphic}.
the output is just one long line.
@end deffn
-@deffn Command base64-encode-string string &optional no-line-break
+@defun base64-encode-string string &optional no-line-break
This function converts the string @var{string} into base 64 code. It
returns a string containing the encoded text. As for
@code{base64-encode-region}, an error is signaled if a character in the
text, to avoid overlong lines. However, if the optional argument
@var{no-line-break} is non-@code{nil}, these newlines are not added, so
the result string is just one long line.
-@end deffn
+@end defun
-@defun base64-decode-region beg end
+@deffn Command base64-decode-region beg end
This function converts the region from @var{beg} to @var{end} from base
64 code into the corresponding decoded text. It returns the length of
the decoded text.
The decoding functions ignore newline characters in the encoded text.
-@end defun
+@end deffn
@defun base64-decode-string string
This function converts the string @var{string} from base 64 code into
The decoding functions ignore newline characters in the encoded text.
@end defun
-@node MD5 Checksum
-@section MD5 Checksum
+@node Checksum/Hash
+@section Checksum/Hash
@cindex MD5 checksum
-@cindex message digest computation
-
- MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit
-``fingerprints'' of a document or program. They are used to verify
-that you have an exact and unaltered copy of the data. The algorithm
-to calculate the MD5 message digest is defined in Internet
-RFC@footnote{
-For an explanation of what is an RFC, see the footnote in @ref{Base
-64}.
-}1321. This section describes the Emacs facilities for computing
-message digests.
-
-@defun md5 object &optional start end coding-system noerror
-This function returns the MD5 message digest of @var{object}, which
-should be a buffer or a string.
+@cindex SHA hash
+@cindex hash, cryptographic
+@cindex cryptographic hash
+
+ Emacs has built-in support for computing @dfn{cryptographic hashes}.
+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.
+
+@cindex message digest
+ Emacs supports several common cryptographic hash algorithms: MD5,
+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
+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
+security-related applications you should use the other hash types,
+such as SHA-2.
+
+@defun secure-hash algorithm object &optional start end binary
+This function returns a hash for @var{object}. The argument
+@var{algorithm} is a symbol stating which hash to compute: one of
+@code{md5}, @code{sha1}, @code{sha224}, @code{sha256}, @code{sha384}
+or @code{sha512}. The argument @var{object} should be a buffer or a
+string.
-The two optional arguments @var{start} and @var{end} are character
+The optional arguments @var{start} and @var{end} are character
positions specifying the portion of @var{object} to compute the
-message digest for. If they are @code{nil} or omitted, the digest is
+message digest for. If they are @code{nil} or omitted, the hash is
computed for the whole of @var{object}.
-The function @code{md5} does not compute the message digest directly
-from the internal Emacs representation of the text (@pxref{Text
-Representations}). Instead, it encodes the text using a coding
-system, and computes the message digest from the encoded text. The
-optional fourth argument @var{coding-system} specifies which coding
-system to use for encoding the text. It should be the same coding
-system that you used to read the text, or that you used or will use
-when saving or sending the text. @xref{Coding Systems}, for more
-information about coding systems.
-
-If @var{coding-system} is @code{nil} or omitted, the default depends
-on @var{object}. If @var{object} is a buffer, the default for
-@var{coding-system} is whatever coding system would be chosen by
-default for writing this text into a file. If @var{object} is a
-string, the user's most preferred coding system (@pxref{Recognize
-Coding, prefer-coding-system, the description of
-@code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used.
+If the argument @var{binary} is omitted or @code{nil}, the function
+returns the @dfn{text form} of the hash, as an ordinary Lisp string.
+If @var{binary} is non-@code{nil}, it returns the hash in @dfn{binary
+form}, as a sequence of bytes stored in a unibyte string.
+
+This function does not compute the hash directly from the internal
+representation of @var{object}'s text (@pxref{Text Representations}).
+Instead, it encodes the text using a coding system (@pxref{Coding
+Systems}), and computes the hash from that encoded text. If
+@var{object} is a buffer, the coding system used is the one which
+would be chosen by default for writing the text into a file. If
+@var{object} is a string, the user's preferred coding system is used
+(@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}).
+@end defun
+
+@defun md5 object &optional start end coding-system noerror
+This function returns an MD5 hash. It is semi-obsolete, since for
+most purposes it is equivalent to calling @code{secure-hash} with
+@code{md5} as the @var{algorithm} argument. The @var{object},
+@var{start} and @var{end} arguments have the same meanings as in
+@code{secure-hash}.
+
+If @var{coding-system} is non-@code{nil}, it specifies a coding system
+to use to encode the text; if omitted or @code{nil}, the default
+coding system is used, like in @code{secure-hash}.
Normally, @code{md5} signals an error if the text can't be encoded
using the specified or chosen coding system. However, if
coding instead.
@end defun
-@node Parsing HTML
-@section Parsing HTML
+@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
-This function provides HTML parsing via the @code{libxml2} library.
-It parses ``real world'' HTML and tries to return a sensible parse tree
-regardless.
+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
+mistakes.
-In addition to @var{start} and @var{end} (specifying the start and end
-of the region to act on), it takes an optional parameter,
-@var{base-url}, which is used to expand relative URLs in the document,
-if any.
+The optional argument @var{base-url}, if non-@code{nil}, should be a
+string specifying the base URL for relative URLs occurring in links.
-Here's an example demonstrating the structure of the parsed data you
-get out. Given this HTML document:
+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
+the subnodes.
+
+The following example demonstrates this. Given this (malformed) HTML
+document:
@example
-<html><h
Ead></head><body width=101><div class=thing>Foo<div>Yes
+<html><h
ead></head><body width=101><div class=thing>Foo<div>Yes
@end example
-You get this parse tree:
+@noindent
+A call to @code{libxml-parse-html-region} returns this:
@example
-(html
- (head)
- (body
- (:width . "101")
- (div
- (:class . "thing")
- (text . "Foo")
- (div
- (text . "Yes\n")))))
+(html ()
+ (head ())
+ (body ((width . "101"))
+ (div ((class . "thing"))
+ "Foo"
+ (div ()
+ "Yes"))))
@end example
+@end defun
-It's a simple tree structure, where the @code{car} for each node is
-the name of the node, and the @code{cdr} is the value, or the list of
-values.
-
-Attributes are coded the same way as child nodes, but with @samp{:} as
-the first character.
+@cindex rendering html
+@defun shr-insert-document dom
+This function renders the parsed HTML in @var{dom} into the current
+buffer. The argument @var{dom} should be a list as generated by
+@code{libxml-parse-html-region}. This function is, e.g., used by
+@ref{Top, EWW,, eww, The Emacs Web Wowser Manual}.
@end defun
@cindex parsing xml
@defun libxml-parse-xml-region start end &optional base-url
-
-This is much the same as @code{libxml-parse-html-region} above, but
-operates on XML instead of HTML, and is correspondingly stricter about
-syntax.
+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
@node Atomic Changes
@defvar after-change-functions
This variable holds a list of functions to call after any buffer
-modification. Each function receives three arguments: the beginning and
-end of the region just changed, and the length of the text that existed
-before the change. All three arguments are integers. The buffer that's
-about to change is always the current buffer.
-
-The length of the old text is the difference between the buffer positions
-before and after that text as it was before the change. As for the
-changed text, its length is simply the difference between the first two
-arguments.
+modification. Each function receives three arguments: the beginning
+and end of the region just changed, and the length of the text that
+existed before the change. All three arguments are integers. The
+buffer that has been changed is always the current buffer.
+
+The length of the old text is the difference between the buffer
+positions before and after that text as it was before the change. As
+for the changed text, its length is simply the difference between the
+first two arguments.
@end defvar
- Output of messages into the @samp{*Messages*} buffer does not
+ Output of messages into the @file{*Messages*} buffer does not
call these functions.
@defmac combine-after-change-calls body@dots{}