merge trunk

8 files changed, 105 insertions, 66 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 47a4c8da522..5ab3c1ab5b8 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,11 @@
+2012-10-16  Juri Linkov  <juri@jurta.org>
+
+        * search.texi (Query Replace): Document multi-buffer replacement
+        keys.  (Bug#12655)
+
+        * maintaining.texi (Tags Search): Change link "Replace" to
+        "Query Replace".
+
 2012-10-13  Chong Yidong  <cyd@gnu.org>
 
         * files.texi (File Conveniences): ImageMagick enabled by default.
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index d21e3af83dd..67214bde22c 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2221,7 +2221,7 @@ the current buffer, followed by the remaining files of the tags table.
 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{Replace}, for more information on query replace.
+input.  @xref{Query Replace}, for more information on query replace.
 
 @vindex tags-case-fold-search
 @cindex case-sensitivity and tags search
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 21db02c8ab8..7e46e416219 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -1239,6 +1239,19 @@ occurrences.
 @item !
 to replace all remaining occurrences without asking again.
 
+@item Y @r{(Upper-case)}
+to replace all remaining occurrences in all remaining buffers in
+multi-buffer replacements (like the Dired `Q' command which performs
+query replace on selected files).  It answers this question and all
+subsequent questions in the series with "yes", without further
+user interaction.
+
+@item N @r{(Upper-case)}
+to skip to the next buffer in multi-buffer replacements without
+replacing remaining occurrences in the current buffer.  It answers
+this question "no", gives up on the questions for the current buffer,
+and continues to the next buffer in the sequence.
+
 @item ^
 to go back to the position of the previous occurrence (or what used to
 be an occurrence), in case you changed it by mistake or want to
diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog
index 11eacf25c96..6c524f5a0ae 100644
--- a/doc/lispintro/ChangeLog
+++ b/doc/lispintro/ChangeLog
@@ -1,3 +1,8 @@
+2012-10-17  Gregor Zattler  <grfz@gmx.de>  (tiny change)
+
+        * emacs-lisp-intro.texi (Narrowing advantages):
+        Minor update for changed what-line implementation.  (Bug#12629)
+
 2012-06-21  Glenn Morris  <rgm@gnu.org>
 
         * Makefile.in: Rename infodir to buildinfodir throughout.  (Bug#11737)
diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 04e3e0c8649..55c3ef4e09e 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -6600,8 +6600,8 @@ buffer; or conversely, an Emacs Lisp function needs to work on all of a
 buffer that has been narrowed.  The @code{what-line} function, for
 example, removes the narrowing from a buffer, if it has any narrowing
 and when it has finished its job, restores the narrowing to what it was.
-On the other hand, the @code{count-lines} function, which is called by
-@code{what-line}, uses narrowing to restrict itself to just that portion
+On the other hand, the @code{count-lines} function
+uses narrowing to restrict itself to just that portion
 of the buffer in which it is interested and then restores the previous
 situation.
 
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 40c457ffe07..acf6f8a51ff 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,14 @@
+2012-10-15  Chong Yidong  <cyd@gnu.org>
+
+        * macros.texi (Defining Macros): defmacro is now a macro.
+        Explicitly list the docstring and declare arguments.
+
+        * functions.texi (Anonymous Functions): Explicitly list the
+        docstring, declare, and interactive arguments to lambda.
+        (Defining Functions): Likewise for defun.
+        (Inline Functions): Likewise for defsubst.
+        (Declare Form): Tweak description.
+
 2012-10-13  Chong Yidong  <cyd@gnu.org>
 
         * display.texi (ImageMagick Images): ImageMagick enabled by default.
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 845561f91ec..c94e46dad18 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -522,21 +522,20 @@ Scheme.)
 is called @dfn{defining a function}, and it is done with the
 @code{defun} special form.
 
-@defmac defun name argument-list body-forms...
+@defmac defun name args [doc] [declare] [interactive] body@dots{}
 @code{defun} is the usual way to define new Lisp functions.  It
-defines the symbol @var{name} as a function that looks like this:
+defines the symbol @var{name} as a function with argument list
+@var{args} and body forms given by @var{body}.  Neither @var{name} nor
+@var{args} should be quoted.
 
-@example
-(lambda @var{argument-list} . @var{body-forms})
-@end example
+@var{doc}, if present, should be a string specifying the function's
+documentation string (@pxref{Function Documentation}).  @var{declare},
+if present, should be a @code{declare} form specifying function
+metadata (@pxref{Declare Form}).  @var{interactive}, if present,
+should be an @code{interactive} form specifying how the function is to
+be called interactively (@pxref{Interactive Call}).
 
-@code{defun} stores this lambda expression in the function cell of
-@var{name}.  Its return value is @emph{undefined}.
-
-As described previously, @var{argument-list} is a list of argument
-names and may include the keywords @code{&optional} and @code{&rest}.
-Also, the first two of the @var{body-forms} may be a documentation
-string and an interactive declaration.  @xref{Lambda Components}.
+The return value of @code{defun} is undefined.
 
 Here are some examples:
 
@@ -582,14 +581,14 @@ redefinition from unintentional redefinition.
 @end defmac
 
 @cindex function aliases
-@defun defalias name definition &optional docstring
+@defun defalias name definition &optional doc
 @anchor{Definition of defalias}
 This special form defines the symbol @var{name} as a function, with
 definition @var{definition} (which can be any valid Lisp function).
 Its return value is @emph{undefined}.
 
-If @var{docstring} is non-@code{nil}, it becomes the function
-documentation of @var{name}.  Otherwise, any documentation provided by
+If @var{doc} is non-@code{nil}, it becomes the function documentation
+of @var{name}.  Otherwise, any documentation provided by
 @var{definition} is used.
 
 The proper place to use @code{defalias} is where a specific function
@@ -902,11 +901,14 @@ function, you can in principle use any method to construct the list.
 But typically you should use the @code{lambda} macro, or the
 @code{function} special form, or the @code{#'} read syntax:
 
-@defmac lambda args body...
-This macro returns an anonymous function with argument list @var{args}
-and body forms given by @var{body}.  In effect, this macro makes
-@code{lambda} forms ``self-quoting'': evaluating a form whose @sc{car}
-is @code{lambda} yields the form itself:
+@defmac lambda args [doc] [interactive] body@dots{}
+This macro returns an anonymous function with argument list
+@var{args}, documentation string @var{doc} (if any), interactive spec
+@var{interactive} (if any), and body forms given by @var{body}.
+
+In effect, this macro makes @code{lambda} forms ``self-quoting'':
+evaluating a form whose @sc{car} is @code{lambda} yields the form
+itself:
 
 @example
 (lambda (x) (* x x))
@@ -1169,13 +1171,13 @@ If provided, @var{when} should be a string indicating when the function
 was first made obsolete---for example, a date or a release number.
 @end defun
 
-@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
+@defmac define-obsolete-function-alias obsolete-name current-name &optional when doc
 This convenience macro marks the function @var{obsolete-name} obsolete
 and also defines it as an alias for the function @var{current-name}.
 It is equivalent to the following:
 
 @example
-(defalias @var{obsolete-name} @var{current-name} @var{docstring})
+(defalias @var{obsolete-name} @var{current-name} @var{doc})
 (make-obsolete @var{obsolete-name} @var{current-name} @var{when})
 @end example
 @end defmac
@@ -1213,16 +1215,16 @@ this:
 @section Inline Functions
 @cindex inline functions
 
-@defmac defsubst name argument-list body-forms...
-Define an inline function.  The syntax is exactly the same as
-@code{defun} (@pxref{Defining Functions}).
-@end defmac
-
-  You can define an @dfn{inline function} by using @code{defsubst}
-instead of @code{defun}.  An inline function works just like an
-ordinary function except for one thing: when you byte-compile a call
+  An @dfn{inline function} is a function that works just like an
+ordinary function, except for one thing: when you byte-compile a call
 to the function (@pxref{Byte Compilation}), the function's definition
-is expanded into the caller.
+is expanded into the caller.  To define an inline function, use
+@code{defsubst} instead of @code{defun}.
+
+@defmac defsubst name args [doc] [declare] [interactive] body@dots{}
+This macro defines an inline function.  Its syntax is exactly the same
+as @code{defun} (@pxref{Defining Functions}).
+@end defmac
 
   Making a function inline often makes its function calls run faster.
 But it also has disadvantages.  For one thing, it reduces flexibility;
@@ -1266,16 +1268,13 @@ convention in Emacs Lisp mode.
 @anchor{Definition of declare}
 @defmac declare @var{specs}@dots{}
 This macro ignores its arguments and evaluates to @code{nil}; it has
-no run-time effect.  However, when a @code{declare} form occurs as the
-@emph{very first form} in the body of a @code{defun} function
-definition or a @code{defmacro} macro definition (@pxref{Defining
-Macros}, for a description of @code{defmacro}), it appends the
-properties specified by @var{specs} to the function or macro.  This
-work is specially performed by the @code{defun} and @code{defmacro}
-macros.
-
-Note that if you put a @code{declare} form in an interactive function,
-it should go before the @code{interactive} form.
+no run-time effect.  However, when a @code{declare} form occurs in the
+@var{declare} argument of a @code{defun} or @code{defsubst} function
+definition (@pxref{Defining Functions}) or a @code{defmacro} macro
+definition (@pxref{Defining Macros}), it appends the properties
+specified by @var{specs} to the function or macro.  This work is
+specially performed by @code{defun}, @code{defsubst}, and
+@code{defmacro}.
 
 Each element in @var{specs} should have the form @code{(@var{property}
 @var{args}@dots{})}, which should not be quoted.  These have the
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index 0a5152a43a1..8be6a3fbcde 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -185,35 +185,38 @@ During Compile}).
 @node Defining Macros
 @section Defining Macros
 
-  A Lisp macro is a list whose @sc{car} is @code{macro}.  Its @sc{cdr} should
-be a function; expansion of the macro works by applying the function
-(with @code{apply}) to the list of unevaluated argument-expressions
-from the macro call.
+  A Lisp macro object is a list whose @sc{car} is @code{macro}, and
+whose @sc{cdr} is a lambda expression.  Expansion of the macro works
+by applying the lambda expression (with @code{apply}) to the list of
+@emph{unevaluated} arguments from the macro call.
 
   It is possible to use an anonymous Lisp macro just like an anonymous
-function, but this is never done, because it does not make sense to pass
-an anonymous macro to functionals such as @code{mapcar}.  In practice,
-all Lisp macros have names, and they are usually defined with the
-special form @code{defmacro}.
+function, but this is never done, because it does not make sense to
+pass an anonymous macro to functionals such as @code{mapcar}.  In
+practice, all Lisp macros have names, and they are almost always
+defined with the @code{defmacro} macro.
 
-@defspec defmacro name argument-list body-forms@dots{}
-@code{defmacro} defines the symbol @var{name} as a macro that looks
-like this:
+@defmac defmacro name args [doc] [declare] body@dots{}
+@code{defmacro} defines the symbol @var{name} (which should not be
+quoted) as a macro that looks like this:
 
 @example
-(macro lambda @var{argument-list} . @var{body-forms})
+(macro lambda @var{args} . @var{body})
 @end example
 
-(Note that the @sc{cdr} of this list is a function---a lambda expression.)
-This macro object is stored in the function cell of @var{name}.  Its return
-value is @emph{undefined}.
-
-The shape and meaning of @var{argument-list} is the same as in a
-function, and the keywords @code{&rest} and @code{&optional} may be used
-(@pxref{Argument List}).  Macros may have a documentation string, but
-any @code{interactive} declaration is ignored since macros cannot be
-called interactively.
-@end defspec
+(Note that the @sc{cdr} of this list is a lambda expression.)  This
+macro object is stored in the function cell of @var{name}.  The
+meaning of @var{args} is the same as in a function, and the keywords
+@code{&rest} and @code{&optional} may be used (@pxref{Argument List}).
+Neither @var{name} nor @var{args} should be quoted.  The return value
+of @code{defmacro} is undefined.
+
+@var{doc}, if present, should be a string specifying the macro's
+documentation string.  @var{declare}, if present, should be a
+@code{declare} form specifying metadata for the macro (@pxref{Declare
+Form}).  Note that macros cannot have interactive declarations, since
+they cannot be called interactively.
+@end defmac
 
   Macros often need to construct large list structures from a mixture
 of constants and nonconstant parts.  To make this easier, use the