17 files changed, 309 insertions, 192 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 42ec24fac5f..3584c89d5fe 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,41 @@
+2012-03-11  Chong Yidong  <cyd@gnu.org>
+
+        * windows.texi (Window Configurations): save-window-excursion is
+        now a macro.
+
+        * display.texi (Temporary Displays): with-output-to-temp-buffer is
+        now a macro.
+
+        * text.texi (Fields): Minor copyedit.
+
+2012-03-10  Eli Zaretskii  <eliz@gnu.org>
+
+        * strings.texi (String Basics):
+        * sequences.texi (Sequence Functions): Mention that `length' is
+        not appropriate for computing the string width on display; add a
+        cross-reference to the description of `string-width'.  (Bug#10978)
+
+        * eval.texi (Autoloading): Minor change of wording.
+
+2012-03-10  Chong Yidong  <cyd@gnu.org>
+
+        * loading.texi (Autoload): Explicitly state which forms are
+        processed specially (Bug#7783).
+
+        * keymaps.texi (Mouse Menus): Describe non-toolkit behavior as the
+        non-default situation.  Describe one-submenu exception (Bug#7695).
+
+        * nonascii.texi (Character Properties): Copyedits.
+
+2012-03-08  Chong Yidong  <cyd@gnu.org>
+
+        * text.texi (Mode-Specific Indent): Document new behavior of
+        indent-for-tab-command.  Document tab-always-indent.
+        (Special Properties): Copyedits.
+        (Checksum/Hash): Improve secure-hash doc.  Do not recommend MD5.
+        (Parsing HTML/XML): Rename from Parsing HTML.  Update doc of
+        libxml-parse-html-region.
+
 2012-03-07  Glenn Morris  <rgm@gnu.org>
 
         * markers.texi (The Region): Briefly mention use-empty-active-region
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 281ddda9cec..c70418be52b 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1031,7 +1031,7 @@ You can use a display table to substitute other text for the ellipsis
 buffer and then present it to the user for perusal rather than for
 editing.  Many help commands use this feature.
 
-@defspec with-output-to-temp-buffer buffer-name forms@dots{}
+@defmac with-output-to-temp-buffer buffer-name forms@dots{}
 This function executes @var{forms} while arranging to insert any output
 they print into the buffer named @var{buffer-name}, which is first
 created if necessary, and put into Help mode.  Finally, the buffer is
@@ -1083,7 +1083,7 @@ The value of the last form in @var{forms} is returned.
 ---------- Buffer: foo ----------
 @end group
 @end example
-@end defspec
+@end defmac
 
 @defopt temp-buffer-show-function
 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 7a444ee4039..ea304292497 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1054,7 +1054,8 @@ Text
 * Registers::               How registers are implemented.  Accessing
                               the text or position stored in a register.
 * Base 64::                 Conversion to or from base 64 encoding.
-* Checksum/Hash::           Computing "message digests"/"checksums"/"hashes".
+* 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.
 
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index cb3a4c54fac..429d999a2c8 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -521,8 +521,10 @@ values).@refill
 whose function definition has not yet been loaded into Emacs.  It
 specifies which file contains the definition.  When an autoload object
 appears as a symbol's function definition, calling that symbol as a
-function automatically loads the specified file; then it calls the real
-definition loaded from that file.  @xref{Autoload}.
+function automatically loads the specified file; then it calls the
+real definition loaded from that file.  The way to arrange for an
+autoload object to appear as a symbol's function definition is
+described in @ref{Autoload}.
 
 @node Quoting
 @section Quoting
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 83bbc140b13..55b18edf2ec 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -134,7 +134,7 @@ in a different location since it was dumped.
 This function delays the initialization of @var{symbol} to the next
 Emacs start.  You normally use this function by specifying it as the
 @code{:initialize} property of a customizable variable.  (The argument
-@var{value} is unused, and is provided only for compatiblity with the
+@var{value} is unused, and is provided only for compatibility with the
 form Custom expects.)
 @end defun
 
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 669f058ef13..5dd57ccb4ac 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -2345,24 +2345,25 @@ multiple levels or comes from the menu bar.)
   It's often best to use a button-down event to trigger the menu.  Then
 the user can select a menu item by releasing the button.
 
-  A single keymap can appear as multiple menu panes, if you explicitly
-arrange for this.  The way to do this is to make a keymap for each pane,
-then create a binding for each of those maps in the main keymap of the
-menu.  Give each of these bindings an item string that starts with
-@samp{@@}.  The rest of the item string becomes the name of the pane.
-See the file @file{lisp/mouse.el} for an example of this.  Any ordinary
-bindings with @samp{@@}-less item strings are grouped into one pane,
-which appears along with the other panes explicitly created for the
-submaps.
-
-  X toolkit menus don't have panes; instead, they can have submenus.
-Every nested keymap becomes a submenu, whether the item string starts
-with @samp{@@} or not.  In a toolkit version of Emacs, the only thing
-special about @samp{@@} at the beginning of an item string is that the
-@samp{@@} doesn't appear in the menu item.
-
-  Multiple keymaps that define the same menu prefix key produce
-separate panes or separate submenus.
+@cindex submenu
+  If the menu keymap contains a binding to a nested keymap, the nested
+keymap specifies a @dfn{submenu}.  There will be a menu item, labeled
+by the nested keymap's item string, and clicking on this item
+automatically pops up the specified submenu.  As a special exception,
+if the menu keymap contains a single nested keymap and no other menu
+items, the menu shows the contents of the nested keymap directly, not
+as a submenu.
+
+  However, if Emacs is compiled without X toolkit support, submenus
+are not supported.  Each nested keymap is shown as a menu item, but
+clicking on it does not automatically pop up the submenu.  If you wish
+to imitate the effect of submenus, you can do that by giving a nested
+keymap an item string which starts with @samp{@@}.  This causes Emacs
+to display the nested keymap using a separate @dfn{menu pane}; the
+rest of the item string after the @samp{@@} is the pane label.  If
+Emacs is compiled without X toolkit support, menu panes are not used;
+in that case, a @samp{@@} at the beginning of an item string is
+omitted when the menu label is displayed, and has no other effect.
 
 @node Keyboard Menus
 @subsection Menus and the Keyboard
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 3c2fa60248e..47a2a39ed63 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -500,14 +500,31 @@ Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
 autoloads for all files in the current directory.
 
   The same magic comment can copy any kind of form into
-@file{loaddefs.el}.  If the form following the magic comment is not a
-function-defining form or a @code{defcustom} form, it is copied
-verbatim.  ``Function-defining forms'' include @code{define-skeleton},
-@code{define-derived-mode}, @code{define-generic-mode} and
-@code{define-minor-mode} as well as @code{defun} and
-@code{defmacro}.  To save space, a @code{defcustom} form is converted to
-a @code{defvar} in @file{loaddefs.el}, with some additional information
-if it uses @code{:require}.
+@file{loaddefs.el}.  The form following the magic comment is copied
+verbatim, @emph{except} if it is one of the forms which the autoload
+facility handles specially (e.g.@: by conversion into an
+@code{autoload} call).  The forms which are not copied verbatim are
+the following:
+
+@table @asis
+@item Definitions for function or function-like objects:
+@code{defun} and @code{defmacro}; also @code{defun*} and
+@code{defmacro*} (@pxref{Argument Lists,,,cl,CL Manual}), and
+@code{define-overloadable-function} (see the commentary in
+@file{mode-local.el}).
+
+@item Definitions for major or minor modes:
+@code{define-derived-mode}, @code{define-minor-mode},
+@code{define-compilation-mode}, @code{define-generic-mode},
+@code{easy-mmode-define-global-mode}, @code{define-global-minor-mode},
+@code{define-globalized-minor-mode}, and
+@code{easy-mmode-define-minor-mode}.
+
+@item Other definition types:
+@code{defcustom}, @code{defgroup}, @code{defclass}
+(@pxref{Top,EIEIO,,eieio,EIEIO}), and @code{define-skeleton} (see the
+commentary in @file{skeleton.el}).
+@end table
 
   You can also use a magic comment to execute a form at build time
 @emph{without} executing it when the file itself is loaded.  To do this,
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index 19c72981174..c97cd099328 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -412,14 +412,13 @@ or @code{R} (strong R).
 Corresponds to the Unicode @code{Decomposition_Type} and
 @code{Decomposition_Value} properties.  The value is a list, whose
 first element may be a symbol representing a compatibility formatting
-tag, such as @code{small}@footnote{
-Note that the Unicode spec writes these tag names inside
-@samp{<..>} brackets.  The tag names in Emacs do not include the
-brackets; e.g., Unicode specifies @samp{<small>} where Emacs uses
-@samp{small}.
-}; the other elements are characters that give the compatibility
-decomposition sequence of this character.  For unassigned codepoints,
-the value is the character itself.
+tag, such as @code{small}@footnote{The Unicode specification writes
+these tag names inside @samp{<..>} brackets, but the tag names in
+Emacs do not include the brackets; e.g.@: Unicode specifies
+@samp{<small>} where Emacs uses @samp{small}.  }; the other elements
+are characters that give the compatibility decomposition sequence of
+this character.  For unassigned codepoints, the value is the character
+itself.
 
 @item decimal-digit-value
 Corresponds to the Unicode @code{Numeric_Value} property for
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 94f1bf666d2..50f75da2de8 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -108,6 +108,11 @@ Emacs character code.
 @noindent
 See also @code{string-bytes}, in @ref{Text Representations}.
 
+If you need to compute the width of a string on display, you should
+use @code{string-width} (@pxref{Width}), not @code{length}, since
+@code{length} only counts the number of characters, but does not
+account for the display width of each character.
+
 @defun elt sequence index
 @cindex elements of sequences
 This function returns the element of @var{sequence} indexed by
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index bbb75f1474d..64d0986493a 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -51,7 +51,9 @@ C are terminated by a character with @acronym{ASCII} code 0.)
 operate on them with the general array and sequence functions.
 (@xref{Sequences Arrays Vectors}.)  For example, you can access or
 change individual characters in a string using the functions @code{aref}
-and @code{aset} (@pxref{Array Functions}).
+and @code{aset} (@pxref{Array Functions}).  However, note that
+@code{length} should @emph{not} be used for computing the width of a
+string on display; use @code{string-width} (@pxref{Width}) instead.
 
   There are two text representations for non-@acronym{ASCII} characters in
 Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 88cb6a157f8..1ba0cae43b6 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -56,8 +56,8 @@ the character after point.
 * Registers::        How registers are implemented.  Accessing the text or
                        position stored in a register.
 * Base 64::          Conversion to or from base 64 encoding.
-* Checksum/Hash::    Computing "message digests"/"checksums"/"hashes".
-* 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
@@ -2203,14 +2203,48 @@ key to indent properly for the language being edited.  This section
 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:
 
-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}.
+@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
+
+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
@@ -2218,41 +2252,31 @@ This command calls the function in @code{indent-line-function} to
 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
 
@@ -2827,7 +2851,7 @@ faster to process chunks of text that have the same property value.
 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.
@@ -2839,15 +2863,15 @@ different properties.
 
 @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
@@ -2980,10 +3004,9 @@ character.
 @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,
+such as its font and color.  @xref{Faces}.  The value of the property
+can be the following:
 
 @itemize @bullet
 @item
@@ -2996,10 +3019,10 @@ 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
 
-@code{face} can also be a list, where each element uses one of the
-forms listed above.
+@item
+A list, where each element uses one of the two forms listed above.
+@end itemize
 
 Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
 dynamically updating the @code{face} property of characters based on
@@ -3354,15 +3377,15 @@ of the text.
   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}.
@@ -3754,7 +3777,7 @@ closest to @var{new-pos} that is in the same field as @var{old-pos}.
 
 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
@@ -4063,46 +4086,64 @@ The decoding functions ignore newline characters in the encoded text.
 @node Checksum/Hash
 @section Checksum/Hash
 @cindex MD5 checksum
-@cindex hashing, secure
-@cindex SHA-1
-@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 and other forms of ``secure hash''.
+@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 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.
+@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
@@ -4110,65 +4151,53 @@ using the specified or chosen coding system.  However, if
 coding instead.
 @end defun
 
-@defun secure-hash algorithm object &optional start end binary
-This function provides a general interface to a variety of secure
-hashing algorithms.  As well as the MD5 algorithm, it supports SHA-1,
-SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512.  The argument
-@var{algorithm} is a symbol stating which hash to compute.  The
-arguments @var{object}, @var{start}, and @var{end} are as for the
-@code{md5} function.  If the optional argument @var{binary} is
-non-@code{nil}, returns a string in binary form.
-@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><hEad></head><body width=101><div class=thing>Foo<div>Yes
+<html><head></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
-
-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.
 @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
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index a92a807b747..58092f23157 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -1076,7 +1076,8 @@ Text
 * Registers::               How registers are implemented.  Accessing
                               the text or position stored in a register.
 * Base 64::                 Conversion to or from base 64 encoding.
-* Checksum/Hash::           Computing "message digests"/"checksums"/"hashes".
+* 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.
 
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 97b21aba10b..a42b70d77a4 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -1075,7 +1075,8 @@ Text
 * Registers::               How registers are implemented.  Accessing
                               the text or position stored in a register.
 * Base 64::                 Conversion to or from base 64 encoding.
-* Checksum/Hash::           Computing "message digests"/"checksums"/"hashes".
+* 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.
 
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 07be7fa9079..b541b2419c8 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3142,7 +3142,7 @@ as @code{save-window-excursion}:
 @end example
 @end defun
 
-@defspec save-window-excursion forms@dots{}
+@defmac save-window-excursion forms@dots{}
 This special form records the window configuration, executes @var{forms}
 in sequence, then restores the earlier window configuration.  The window
 configuration includes, for each window, the value of point and the
@@ -3179,7 +3179,7 @@ For example:
      ;; @r{The screen is now split again.}
 @end group
 @end example
-@end defspec
+@end defmac
 
 @defun window-configuration-p object
 This function returns @code{t} if @var{object} is a window configuration.
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 1691c979fb6..c95aaa9b15d 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,15 @@
+2012-03-10  Eli Zaretskii  <eliz@gnu.org>
+
+        * info.texi (Expert Info): Move the index entry for "Texinfo" from
+        "Getting Started" to this node.  (Bug#10450)
+
+2012-03-10  Chong Yidong  <cyd@gnu.org>
+
+        * flymake.texi (Example -- Configuring a tool called via make):
+        Mention the Automake COMPILE variable (Bug#8715).
+
+        * info.texi (Getting Started): Add an index entry (Bug#10450).
+
 2012-03-02  Michael Albinus  <michael.albinus@gmx.de>
 
         * dbus.texi (Signals): Known names will be mapped onto unique
diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi
index 687a2f7b4d4..28fb7864f06 100644
--- a/doc/misc/flymake.texi
+++ b/doc/misc/flymake.texi
@@ -449,10 +449,10 @@ Finally, we add an entry to @code{flymake-err-line-patterns}:
 @cindex Adding support for C (gcc+make)
 
 In this example we will add support for C files syntax checked by
-@code{gcc} called via @code{make}.
+@command{gcc} called via @command{make}.
 
 We're not required to write any new functions, as Flymake already has
-functions for @code{make}. We just add a new entry to the
+functions for @command{make}. We just add a new entry to the
 @code{flymake-allowed-file-name-masks}:
 
 @lisp
@@ -464,7 +464,7 @@ functions for @code{make}. We just add a new entry to the
             flymake-allowed-file-name-masks))
 @end lisp
 
-@code{flymake-simple-make-init} builds the following @code{make}
+@code{flymake-simple-make-init} builds the following @command{make}
 command line:
 
 @lisp
@@ -486,9 +486,17 @@ check-syntax:
         gcc -o /dev/null -S ${CHK_SOURCES}
 @end verbatim
 
-The format of error messages reported by @code{gcc} is already
+@noindent
+The format of error messages reported by @command{gcc} is already
 supported by Flymake, so we don't have to add a new entry to
-@code{flymake-err-line-patterns}.
+@code{flymake-err-line-patterns}.  Note that if you are using
+Automake, you may want to replace @code{gcc} with the standard
+Automake variable @code{COMPILE}:
+
+@verbatim
+check-syntax:
+        $(COMPILE) -o /dev/null -S ${CHK_SOURCES}
+@end verbatim
 
 @node Flymake Implementation
 @chapter Flymake Implementation
@@ -548,9 +556,9 @@ These modes are handled inside init/cleanup/getfname functions, see
 @ref{Adding support for a new syntax check tool}.
 
 Flymake contains implementations of all functionality required to
-support different syntax check modes described above (making
-temporary copies, finding master files, etc.), as well as some
-tool-specific (routines for @code{make}, @code{Ant}, etc.) code.
+support different syntax check modes described above (making temporary
+copies, finding master files, etc.), as well as some tool-specific
+(routines for Make, Ant, etc.) code.
 
 
 @node Making a temporary copy
@@ -626,8 +634,8 @@ Therefore, a customizable variable
 way to implement the desired behavior.
 
 The default implementation, @code{flymake-get-project-include-dirs-imp},
-uses a @code{make} call. This requires a correct base directory, that is, a
-directory containing a correct @code{Makefile}, to be determined.
+uses a @command{make} call. This requires a correct base directory, that is, a
+directory containing a correct @file{Makefile}, to be determined.
 
 As obtaining the project include directories might be a costly operation, its
 return value is cached in the hash table. The cache is cleared in the beginning
@@ -641,16 +649,16 @@ of every syntax check attempt.
 
 Flymake can be configured to use different tools for performing syntax
 checks. For example, it can use direct compiler call to syntax check a perl
-script or a call to @code{make} for a more complicated case of a
+script or a call to @command{make} for a more complicated case of a
 @code{C/C++} source. The general idea is that simple files, like perl
 scripts and html pages, can be checked by directly invoking a
 corresponding tool. Files that are usually more complex and generally
 used as part of larger projects, might require non-trivial options to
 be passed to the syntax check tool, like include directories for
 C++. The latter files are syntax checked using some build tool, like
-@code{make} or @code{Ant}.
+Make or Ant.
 
-All @code{make} configuration data is usually stored in a file called
+All Make configuration data is usually stored in a file called
 @code{Makefile}. To allow for future extensions, flymake uses a notion of
 buildfile to reference the 'project configuration' file.
 
diff --git a/doc/misc/info.texi b/doc/misc/info.texi
index ed00e8da028..8952bfb9122 100644
--- a/doc/misc/info.texi
+++ b/doc/misc/info.texi
@@ -1235,6 +1235,7 @@ this:
 
 @node Expert Info
 @chapter Info for Experts
+@cindex Texinfo
 
   This chapter explains how to write an Info file by hand.  However,
 in most cases, writing a Texinfo file is better, since you can use it