-

11 files changed, 288 insertions, 137 deletions

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 8842b8ea2f5..989d8ff7485 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1686,19 +1686,38 @@ permitted provided the copyright notice and this notice are preserved.
 Of course, you should substitute the proper years and copyright holder.
 
 @node Xref
-@section Find Identifier Definitions and References
+@section Find Identifier References
 @cindex xref
 
-  An @dfn{identifier} is a syntactic elements of the program: a
-function, a subroutine, a method, a class, a data type, a macro, etc.
-In a programming language, each identifier is a symbol in the
-language's syntax.  Many program development tools provide
-capabilities to extract references to identifiers from source files,
-record them on specialized data bases, and then use those data bases
-to quickly find where each identifier was defined and referenced.
+  An @dfn{identifier} is a name of a syntactical subunit of the
+program: a function, a subroutine, a method, a class, a data type, a
+macro, etc.  In a programming language, each identifier is a symbol in
+the language's syntax.  Program development and maintenance requires
+capabilities to quickly find where each identifier was defined and
+referenced, to rename identifiers across the entire project, etc.
 
-Emacs provides a unified user interface to these tools, called
-@samp{xref}.  The tools supported by @samp{xref} include:
+These capabilities are also useful for finding references in major
+modes other than those defined to support programming languages.  For
+example, chapters, sections, appendices, etc.@: of a text or a @TeX{}
+document can be treated as subunits as well, and their names can be
+used as identifiers.  In this chapter, we use the term ``identifiers''
+to collectively refer to the names of any kind of subunits, in program
+source and in other kinds of text alike.
+
+Emacs provides a unified interface to these capabilities, called
+@samp{xref}.
+
+@cindex xref backend
+To do its job, @code{xref} needs to make use of information and to
+employ methods specific to the major mode.  What files to search for
+identifiers, how to find references to identifiers, how to complete on
+identifiers---all this and more is mode-specific knowledge.
+@code{xref} delegates the mode-specific parts of its job to a
+@dfn{backend} provided by the mode; it also includes defaults for some
+of its commands, for those modes that don't provide their own.
+
+A backend can implement its capabilities in a variety of ways.  Here
+are a few examples:
 
 @enumerate a
 @item
@@ -1706,49 +1725,25 @@ Some major modes provide built-in means for looking up the language
 symbols.  For example, Emacs Lisp symbols can be identified by
 searching the package load history, maintained by the Emacs Lisp
 interpreter, and by consulting the built-in documentation strings; the
-Emacs Lisp mode uses these facilities to find definitions of symbols.
-
-@item
-Etags, the command for tagging identifier definitions which is part of
-the Emacs distribution.  @xref{Create Tags Table}.
-
-@item
-@acronym{GNU} GLOBAL, the source code tagging system, which provides
-the @command{gtags} command and associated utilities.  @xref{Command
-Line, gtags, , global, GNU GLOBAL source code tag system}.
+Emacs Lisp mode uses these facilities in its backend to allow finding
+definitions of symbols.  (One disadvantage of this kind of backend is
+that it only knows about subunits that were loaded into the
+interpreter.)
 
 @item
-Cscope (@uref{http://cscope.sourceforge.net/}, a tool for browsing
-source code.
-
-@item
-@acronym{GNU} IDUtils, a package for generating databases of
-identifier references and querying those databases.  @xref{Top,,,
-idutils, ID database utilities}.
-
-@item
-Grep, the venerable program that searches files for lines matching
-patterns.  @xref{Invoking,,, grep, GNU Grep Manual}.
+An external program can extract references by scanning the relevant
+files, and build a database of these references.  A backend can then
+access this database whenever it needs to list or look up references.
+The Emacs distribution includes @command{etags}, a command for tagging
+identifier definitions in programs, which supports many programming
+languages and other major modes, such as HTML, by extracting
+references into @dfn{tags tables}.  @xref{Create Tags Table}.  Major
+modes for languages supported by @command{etags} can use tags tables
+as basis for their backend.  (One disadvantage of this kind of backend
+is that tags tables need to be kept reasonably up to date, by
+rebuilding them from time to time.)
 @end enumerate
 
-@noindent
-Additional tools could be supported as they become available, or as
-user extensions.  Each such tool is used as a @dfn{backend} by
-commands described in this section.  Each command detects which
-backends are available for the current major mode, and uses the most
-capable of the available backends, with Grep generally serving as the
-fall-back backend.
-
-@cindex tag
-The commands described here are useful for finding references in major
-modes other than those defined to support programming languages.  For
-example, chapters, sections, appendices, etc. of a text or a @TeX{}
-document can be treated as identifiers as well.  In this chapter, we
-collectively refer to a reference that specifies the name of the file
-where the corresponding subunit is defined, and the position of the
-subunit's definition in that file, as a @dfn{tag}.  We refer to the
-backends used by @code{xref} as @dfn{tagging backends}.
-
 @menu
 * Find Identifiers::    Commands to find where an identifier is defined
                           or referenced, to list identifiers, etc.
@@ -1759,14 +1754,16 @@ backends used by @code{xref} as @dfn{tagging backends}.
 @node Find Identifiers
 @subsection Find Identifiers
 
-  This subsection describes the commands that use the tagging backends
-in order to find definitions of identifiers, references to
-identifiers, and perform various queries about identifiers.  With most
-backends, these definitions and references were recorded as tags in
-the database created and maintained by the backend.
+  This subsection describes the commands that find references to
+identifiers and perform various queries about identifiers.  Each such
+reference could @emph{define} an identifier, e.g., provide the
+implementation of a program subunit or the text of a document section;
+or it could @emph{use} the identifier, e.g., call a function or a
+method, assign a value to a variable, mention a chapter in a
+cross-reference, etc.
 
 @menu
-* Looking Up Identifiers:: Commands to find the definition of a specific tag.
+* Looking Up Identifiers:: Commands to find the definition of an identifier.
 * Xref Commands::          Commands in the @file{*xref*} buffer.
 * Identifier Search::      Searching and replacing identifiers.
 * List Identifiers::       Listing identifiers and completing on them.
@@ -1794,7 +1791,7 @@ Find definitions of identifier, but display it in another window
 Find definition of identifier, and display it in a new frame
 (@code{xref-find-definitions-other-frame}).
 @item M-,
-Pop back to where you previously invoked @kbd{M-.} and friends
+Go back to where you previously invoked @kbd{M-.} and friends
 (@code{xref-pop-marker-stack}).
 @end table
 
@@ -1832,7 +1829,8 @@ former is @w{@kbd{C-x 4 .}}
   The command @kbd{C-M-.} (@code{xref-find-apropos}) finds the
 definitions of one or more identifiers that match a specified regular
 expression.  It is just like @kbd{M-.} except that it does regexp
-matching of identifiers instead of symbol name matching.
+matching of identifiers instead of matching symbol names as fixed
+strings.
 
   When any of the above commands finds more than one definition, it
 presents the @file{*xref*} buffer showing the definition candidates.
@@ -1896,13 +1894,9 @@ without displaying the references.
 @cindex search and replace in multiple files
 @cindex multiple-file search and replace
 
-  The commands in this section visit and search all the files listed
-in the @code{xref} backend's database, one by one.  For these
-commands, the database serves only to specify a sequence of files to
-search.  These commands scan all the databases starting with the first
-one (if any) that describes the current file, proceed from there to
-the end of the list, and then scan from the beginning of the list
-until they have covered all the databases in the list.
+  The commands in this section perform various search and replace
+operations either on identifiers themselves or on files that reference
+them.
 
 @table @kbd
 @item M-?
@@ -1931,7 +1925,7 @@ referenced.  The XREF mode commands are available in this buffer, see
 
 @findex xref-query-replace
   @kbd{M-x xref-query-replace} reads a regexp to match identifier
-names and a string to replace with, just like ordinary @kbd{M-x
+names and a replacement string, just like ordinary @kbd{M-x
 query-replace-regexp}.  It then performs the specified replacement in
 the names of the matching identifiers in all the places in all the
 files where these identifiers are referenced.  This is useful when you
@@ -1943,15 +1937,14 @@ be invoked in the @file{*xref*} buffer generated by @code{M-?}.
 searches for matches in all the files in the selected tags table, one
 file at a time.  It displays the name of the file being searched so
 you can follow its progress.  As soon as it finds an occurrence,
-@code{tags-search} returns.  This command works only with the etags
-backend, and requires tags tables to be available (@pxref{Tags
-Tables}).
+@code{tags-search} returns.  This command requires tags tables to be
+available (@pxref{Tags Tables}).
 
 @findex tags-loop-continue
-  Having found one match, you probably want to find all the rest.
-Type @kbd{M-x tags-loop-continue}) to resume the @code{tags-search},
-finding one more match.  This searches the rest of the current buffer,
-followed by the remaining files of the tags table.
+  Having found one match with @code{tags-search}, you probably want to
+find all the rest.  Type @kbd{M-x tags-loop-continue} to resume the
+@code{tags-search}, finding one more match.  This searches the rest of
+the current buffer, followed by the remaining files of the tags table.
 
 @findex tags-query-replace
   @kbd{M-x tags-query-replace} performs a single
@@ -1960,7 +1953,6 @@ reads a regexp to search for and a string to replace with, just like
 ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
 tags-search}, but repeatedly, processing matches according to your
 input.  @xref{Query Replace}, for more information on query replace.
-This command works only with the etags backend.
 
 @vindex tags-case-fold-search
 @cindex case-sensitivity and tags search
@@ -1976,19 +1968,21 @@ has no special query replace meaning.  You can resume the query
 replace subsequently by typing @kbd{M-x tags-loop-continue}; this
 command resumes the last tags search or replace command that you did.
 For instance, to skip the rest of the current file, you can type
-@kbd{M-> M-x tags-loop-continue}.
+@w{@kbd{M-> M-x tags-loop-continue}}.
 
-  The commands in this section carry out much broader searches than
-the @code{xref-find-definitions} family.  The
+  Note that the commands described above carry out much broader
+searches than the @code{xref-find-definitions} family.  The
 @code{xref-find-definitions} commands search only for definitions of
 identifiers that match your string or regexp.  The commands
-@code{tags-search} and @code{tags-query-replace} find every occurrence
-of the regexp, as ordinary search commands and replace commands do in
-the current buffer.
+@code{xref-find-references}, @code{tags-search}, and
+@code{tags-query-replace} find every occurrence of the identifier or
+regexp, as ordinary search commands and replace commands do in the
+current buffer.
 
-  As an alternative to @code{tags-search}, you can run @command{grep}
-as a subprocess and have Emacs show you the matching lines one by one.
-@xref{Grep Searching}.
+  As an alternative to @code{xref-find-references} and
+@code{tags-search}, you can run @command{grep} as a subprocess and
+have Emacs show you the matching lines one by one.  @xref{Grep
+Searching}.
 
 @node List Identifiers
 @subsubsection Identifier Inquiries
@@ -1996,20 +1990,23 @@ as a subprocess and have Emacs show you the matching lines one by one.
 @table @kbd
 @item C-M-i
 @itemx M-@key{TAB}
-Perform completion on the text around point, using the @code{xref}
-backend if one is available (@code{completion-at-point}).
-@item M-x list-tags @key{RET} @var{file} @key{RET}
-Display a list of the tags defined in the program file @var{file}.
+Perform completion on the text around point, using the selected tags
+table if one is loaded (@code{completion-at-point}).
 @item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET}
 Display a list of all known identifiers matching @var{regexp}.
+@item M-x list-tags @key{RET} @var{file} @key{RET}
+Display a list of the identifiers defined in the program file
+@var{file}.
+@item M-x next-file
+Visit files recorded in the selected tags table.
 @end table
 
 @cindex completion (symbol names)
   In most programming language modes, you can type @kbd{C-M-i} or
 @kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
-at point.  If there is an @code{xref} backend available, this command
-can use it to generate completion candidates more intelligently.
-@xref{Symbol Completion}.
+at point.  If there is a tags table loaded, this command can use it to
+generate completion candidates more intelligently.  @xref{Symbol
+Completion}.
 
 @findex list-tags
   @kbd{M-x list-tags} reads the name of one of the files covered by
@@ -2044,12 +2041,15 @@ for details.
 The first time it is called, it visits the first file covered by the
 table.  Each subsequent call visits the next covered file, unless a
 prefix argument is supplied, in which case it returns to the first
-file.  This command works only with the etags backend.
+file.  This command requires a tags table to be selected.
 
 @node Tags Tables
 @subsection Tags Tables
 @cindex tags and tag tables
 
+@cindex tag
+  A @dfn{tag} is a synonym for identifier reference.  @xref{Xref}.
+
   A @dfn{tags table} records the tags extracted by scanning the source
 code of a certain program or a certain document.  Tags extracted from
 generated files reference the original files, rather than the
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index e4bd85c0ddd..780e00ca681 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -1358,7 +1358,7 @@ the @kbd{M-@key{TAB}} key is usually reserved by the window manager
 for switching graphical windows, so you should type @kbd{C-M-i} or
 @kbd{@key{ESC} @key{TAB}} instead.
 
-@cindex xref-based completion
+@cindex tags-based completion
 @findex completion-at-point
 @cindex Lisp symbol completion
 @cindex completion (Lisp symbols)
@@ -1368,7 +1368,7 @@ which generates its completion list in a flexible way.  If Semantic
 mode is enabled, it tries to use the Semantic parser data for
 completion (@pxref{Semantic}).  If Semantic mode is not enabled or
 fails at performing completion, it tries to complete using the
-available @code{xref} backend (@pxref{Xref}).  If in Emacs Lisp mode, it
+selected tags table (@pxref{Tags Tables}).  If in Emacs Lisp mode, it
 performs completion using the function, variable, or property names
 defined in the current Emacs session.
 
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index bef74e3b2c5..e854646d056 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -12,10 +12,10 @@ a string.  Emacs also has commands to replace occurrences of a string
 with a different string.  There are also commands that do the same
 thing, but search for patterns instead of fixed strings.
 
-  You can also search multiple files under the control of an
-@code{xref} backend (@pxref{Identifier Search}) or through the Dired
-@kbd{A} command (@pxref{Operating on Files}), or ask the @code{grep}
-program to do it (@pxref{Grep Searching}).
+  You can also search multiple files under the control of @code{xref}
+(@pxref{Identifier Search}) or through the Dired @kbd{A} command
+(@pxref{Operating on Files}), or ask the @code{grep} program to do it
+(@pxref{Grep Searching}).
 
 @menu
 * Incremental Search::        Search happens as you type the string.
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index dee43cefb15..9c1df895161 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -691,6 +691,14 @@ default is the return value of @code{this-command-keys-vector}.
 @xref{Definition of this-command-keys-vector}.
 @end defun
 
+@defun funcall-interactively function &rest arguments
+This function works like @code{funcall} (@pxref{Calling Functions}),
+but it makes the call look like an interactive invocation: a call to
+@code{called-interactively-p} inside @var{function} will return
+@code{t}.  If @var{function} is not a command, it is called without
+signaling an error.
+@end defun
+
 @defun command-execute command &optional record-flag keys special
 @cindex keyboard macro execution
 This function executes @var{command}.  The argument @var{command} must
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 1c6674cdda9..614b7db0cac 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1188,8 +1188,8 @@ named, this parameter will be @code{nil}.
 @cindex window position on display
 @cindex frame position
 
-  Position parameters' values are normally measured in pixels, but on
-text terminals they count characters or lines instead.
+  Position parameters' values are measured in pixels.  (Note that none
+of these parameters exist on TTY frames.)
 
 @table @code
 @vindex left, a frame parameter
@@ -2637,18 +2637,19 @@ defined in the file @file{lisp/term/x-win.el}.  Use @kbd{M-x apropos
 @cindex primary selection
 @cindex secondary selection
 
-  In the X window system, data can be transferred between different
-applications by means of @dfn{selections}.  X defines an arbitrary
-number of @dfn{selection types}, each of which can store its own data;
-however, only three are commonly used: the @dfn{clipboard},
-@dfn{primary selection}, and @dfn{secondary selection}.  @xref{Cut and
-Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
-commands that make use of these selections.  This section documents
-the low-level functions for reading and setting X selections.
+  In window systems, such as X, data can be transferred between
+different applications by means of @dfn{selections}.  X defines an
+arbitrary number of @dfn{selection types}, each of which can store its
+own data; however, only three are commonly used: the @dfn{clipboard},
+@dfn{primary selection}, and @dfn{secondary selection}.  Other window
+systems support only the clipboard.  @xref{Cut and Paste,, Cut and
+Paste, emacs, The GNU Emacs Manual}, for Emacs commands that make use
+of these selections.  This section documents the low-level functions
+for reading and setting window-system selections.
 
-@deffn Command x-set-selection type data
-This function sets an X selection.  It takes two arguments: a
-selection type @var{type}, and the value to assign to it, @var{data}.
+@deffn Command gui-set-selection type data
+This function sets a window-system selection.  It takes two arguments:
+a selection type @var{type}, and the value to assign to it, @var{data}.
 
 @var{type} should be a symbol; it is usually one of @code{PRIMARY},
 @code{SECONDARY} or @code{CLIPBOARD}.  These are symbols with
@@ -2665,14 +2666,14 @@ stands for text in the overlay or between the markers.  The argument
 This function returns @var{data}.
 @end deffn
 
-@defun x-get-selection &optional type data-type
-This function accesses selections set up by Emacs or by other X
-clients.  It takes two optional arguments, @var{type} and
+@defun gui-get-selection &optional type data-type
+This function accesses selections set up by Emacs or by other
+programs.  It takes two optional arguments, @var{type} and
 @var{data-type}.  The default for @var{type}, the selection type, is
 @code{PRIMARY}.
 
 The @var{data-type} argument specifies the form of data conversion to
-use, to convert the raw data obtained from another X client into Lisp
+use, to convert the raw data obtained from another program into Lisp
 data.  Meaningful values include @code{TEXT}, @code{STRING},
 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
@@ -2680,7 +2681,8 @@ data.  Meaningful values include @code{TEXT}, @code{STRING},
 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
 @code{INTEGER}.  (These are symbols with upper-case names in accord
 with X conventions.)  The default for @var{data-type} is
-@code{STRING}.
+@code{STRING}.  Window systems other than X usually support only a
+small subset of these types, in addition to @code{STRING}.
 @end defun
 
 @defopt selection-coding-system
@@ -2692,10 +2694,15 @@ converts to the text representation that X11 normally uses.
 
 @cindex clipboard support (for MS-Windows)
 When Emacs runs on MS-Windows, it does not implement X selections in
-general, but it does support the clipboard.  @code{x-get-selection}
-and @code{x-set-selection} on MS-Windows support the text data type
+general, but it does support the clipboard.  @code{gui-get-selection}
+and @code{gui-set-selection} on MS-Windows support the text data type
 only; if the clipboard holds other types of data, Emacs treats the
-clipboard as empty.
+clipboard as empty.  The supported data type is @code{STRING}.
+
+For backward compatibility, there are obsolete aliases
+@code{x-get-selection} and @code{x-set-selection}, which were the
+names of @code{gui-get-selection} and @code{gui-set-selection} before
+Emacs 25.1.
 
 @node Drag and Drop
 @section Drag and Drop
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index e596badcdd2..1e8e7540395 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -623,6 +623,96 @@ definition will have no effect on them.
 and tells the Lisp compiler to perform inline expansion on it.
 @xref{Inline Functions}.
 
+  Alternatively, you can define a function by providing the code which
+will inline it as a compiler macro.  The following macros make this
+possible.
+
+@c FIXME: Can define-inline use the interactive spec?
+@defmac define-inline name args [doc] [declare] body@dots{}
+Define a function @var{name} by providing code that does its inlining,
+as a compiler macro.  The function will accept the argument list
+@var{args} and will have the specified @var{body}.
+
+If present, @var{doc} should be the function's documentation string
+(@pxref{Function Documentation}); @var{declare}, if present, should be
+a @code{declare} form (@pxref{Declare Form}) specifying the function's
+metadata.
+@end defmac
+
+Functions defined via @code{define-inline} have several advantages
+with respect to macros defined by @code{defsubst} or @code{defmacro}:
+
+@itemize @minus
+@item
+They can be passed to @code{mapcar} (@pxref{Mapping Functions}).
+
+@item
+They are more efficient.
+
+@item
+They can be used as @dfn{place forms} to store values
+(@pxref{Generalized Variables}).
+
+@item
+They behave in a more predictable way than @code{cl-defsubst}
+(@pxref{Argument Lists,,, cl, Common Lisp Extensions for GNU Emacs
+Lisp}).
+@end itemize
+
+Like @code{defmacro}, a function inlined with @code{define-inline}
+inherits the scoping rules, either dynamic or lexical, from the call
+site.  @xref{Variable Scoping}.
+
+The following macros should be used in the body of a function defined
+by @code{define-inline}.
+
+@defmac inline-quote expression
+Quote @var{expression} for @code{define-inline}.  This is similar to
+the backquote (@pxref{Backquote}), but quotes code and accepts only
+@code{,}, not @code{,@@}.
+@end defmac
+
+@defmac inline-letevals (bindings@dots{}) body@dots{}
+This is is similar to @code{let} (@pxref{Local Variables}): it sets up
+local variables as specified by @var{bindings}, and then evaluates
+@var{body} with those bindings in effect.  Each element of
+@var{bindings} should be either a symbol or a list of the form
+@w{@code{(@var{var} @var{expr})}}; the result is to evaluate
+@var{expr} and bind @var{var} to the result.  The tail of
+@var{bindings} can be either @code{nil} or a symbol which should hold
+a list of arguments, in which case each argument is evaluated, and the
+symbol is bound to the resulting list.
+@end defmac
+
+@defmac inline-const-p expression
+Return non-@code{nil} if the value of @var{expression} is already
+known.
+@end defmac
+
+@defmac inline-const-val expression
+Return the value of @var{expression}.
+@end defmac
+
+@defmac inline-error format &rest args
+Signal an error, formatting @var{args} according to @var{format}.
+@end defmac
+
+Here's an example of using @code{define-inline}:
+
+@lisp
+(define-inline myaccessor (obj)
+  (inline-letevals (obj)
+    (inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2)))))
+@end lisp
+
+@noindent
+This is equivalent to
+
+@lisp
+(defsubst myaccessor (obj)
+  (if (foo-p obj) (aref (cdr obj) 3) (aref obj 2)))
+@end lisp
+
 @node Calling Functions
 @section Calling Functions
 @cindex function invocation
@@ -664,6 +754,10 @@ they make sense only when given the unevaluated argument
 expressions.  @code{funcall} cannot provide these because, as we saw
 above, it never knows them in the first place.
 
+If you need to use @code{funcall} to call a command and make it behave
+as if invoked interactively, use @code{funcall-interactively}
+(@pxref{Interactive Call}).
+
 @example
 @group
 (setq f 'list)
@@ -1706,19 +1800,24 @@ features of Emacs, you should not make a function inline, even if it's
 small, unless its speed is really crucial, and you've timed the code
 to verify that using @code{defun} actually has performance problems.
 
-  It's possible to define a macro to expand into the same code that an
-inline function would execute (@pxref{Macros}).  But the macro would
-be limited to direct use in expressions---a macro cannot be called
-with @code{apply}, @code{mapcar} and so on.  Also, it takes some work
-to convert an ordinary function into a macro.  To convert it into an
-inline function is easy; just replace @code{defun} with
-@code{defsubst}.  Since each argument of an inline function is
-evaluated exactly once, you needn't worry about how many times the
-body uses the arguments, as you do for macros.
-
   After an inline function is defined, its inline expansion can be
 performed later on in the same file, just like macros.
 
+  It's possible to use @code{defsubst} to define a macro to expand
+into the same code that an inline function would execute
+(@pxref{Macros}).  But the macro would be limited to direct use in
+expressions---a macro cannot be called with @code{apply},
+@code{mapcar} and so on.  Also, it takes some work to convert an
+ordinary function into a macro.  To convert it into an inline function
+is easy; just replace @code{defun} with @code{defsubst}.  Since each
+argument of an inline function is evaluated exactly once, you needn't
+worry about how many times the body uses the arguments, as you do for
+macros.
+
+  As an alternative to @code{defsubst}, you can use
+@code{define-inline} to define functions via their exhaustive compiler
+macro.  @xref{Defining Functions, define-inline}.
+
 @node Declare Form
 @section The @code{declare} Form
 @findex declare
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index d961caf49f6..c18c408209a 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1556,6 +1556,14 @@ keys may not be symbols:
 @end smallexample
 @end defun
 
+@defun alist-get key value &optional default
+This function is like @code{assq}, but instead of returning the entire
+association for @var{key}, @code{(@var{key} . @var{value})}, it
+returns just the @var{value}.  It returns @var{default} if @var{key}
+is not found in @var{alist}, defaulting to @code{nil} if @var{default}
+is omitted.
+@end defun
+
 @defun rassq value alist
 This function returns the first association with value @var{value} in
 @var{alist}.  It returns @code{nil} if no association in @var{alist} has
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 18e67f1abfe..06900a49477 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -73,12 +73,15 @@ To find the file, @code{load} first looks for a file named
 @var{filename} with the extension @samp{.elc} appended.  If such a
 file exists, it is loaded.  If there is no file by that name, then
 @code{load} looks for a file named @file{@var{filename}.el}.  If that
-file exists, it is loaded.  Finally, if neither of those names is
-found, @code{load} looks for a file named @var{filename} with nothing
-appended, and loads it if it exists.  (The @code{load} function is not
-clever about looking at @var{filename}.  In the perverse case of a
-file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will
-indeed find it.)
+file exists, it is loaded.  If Emacs was compiled with support for
+dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for
+a file named @file{@var{filename}.@var{ext}}, where @var{ext} is a
+system-dependent file-name extension of shared libraries.  Finally, if
+neither of those names is found, @code{load} looks for a file named
+@var{filename} with nothing appended, and loads it if it exists.  (The
+@code{load} function is not clever about looking at @var{filename}.
+In the perverse case of a file named @file{foo.el.el}, evaluation of
+@code{(load "foo.el")} will indeed find it.)
 
 If Auto Compression mode is enabled, as it is by default, then if
 @code{load} can not find a file, it searches for a compressed version
@@ -100,7 +103,8 @@ being tried.
 If the optional argument @var{must-suffix} is non-@code{nil}, then
 @code{load} insists that the file name used must end in either
 @samp{.el} or @samp{.elc} (possibly extended with a compression
-suffix), unless it contains an explicit directory name.
+suffix) or the shared-library extension, unless it contains an
+explicit directory name.
 
 If the option @code{load-prefer-newer} is non-@code{nil}, then when
 searching suffixes, @code{load} selects whichever version of a file
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index 7f3b670e328..3f9db8ce375 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -160,6 +160,12 @@ expand the embedded calls to @code{inc}:
 
 @end defun
 
+@defun macroexpand-1 form &optional environment
+This function expands macros like @code{macroexpand}, but it only
+performs one step of the expansion: if the result is another macro
+call, @code{macroexpand-1} will not expand it.
+@end defun
+
 @node Compiling Macros
 @section Macros and Byte Compilation
 @cindex byte-compiling macros
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 95723ca4487..091db5e4ebb 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -571,13 +571,19 @@ no characters is less than any other string.
 @end example
 
 Symbols are also allowed as arguments, in which case their print names
-are used.
+are compared.
 @end defun
 
 @defun string-lessp string1 string2
 @code{string-lessp} is another name for @code{string<}.
 @end defun
 
+@defun string-greaterp string1 string2
+This function returns the result of comparing @var{string1} and
+@var{string2} in the opposite order, i.e., it is equivalent to calling
+@code{(string-lessp @var{string2} @var{string1})}.
+@end defun
+
 @cindex locale-dependent string comparison
 @defun string-collate-lessp string1 string2 &optional locale ignore-case
 This function returns @code{t} if @var{string1} is less than
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index c99f993e5da..8c1ec3d85e2 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -461,10 +461,23 @@ You could define @code{put} in terms of @code{setplist} and
 @end example
 @end defun
 
-@defun function-get symbol property
+@defun function-get symbol property &optional autoload
 This function is identical to @code{get}, except that if @var{symbol}
 is the name of a function alias, it looks in the property list of the
-symbol naming the actual function.  @xref{Defining Functions}.
+symbol naming the actual function.  @xref{Defining Functions}.  If the
+optional argument @var{autoload} is non-@code{nil}, and @var{symbol}
+is auto-loaded, this function will try to autoload it, since
+autoloading might set @var{property} of @var{symbol}.  If
+@var{autoload} is the symbol @code{macro}, only try autoloading if
+@var{symbol} is an auto-loaded macro.
+@end defun
+
+@defun function-put function property value
+This function sets @var{property} of @var{function} to @var{value}.
+@var{function} should be a symbol.  This function is preferred to
+calling @code{put} for setting properties of a function, because it
+will allow us some day to implement remapping of old properties to new
+ones.
 @end defun
 
 @node Standard Properties