; Merge from origin/emacs-25

[gnu-emacs] / doc / lispref / macros.texi

diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index 5520bbbd1dfa7bffd5ea14d64fab339adb4f81e5..6472bd1b03afd893ceb368ecec4df6476a29547b 100644 (file)
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998, 2001-2013 Free Software Foundation,
+@c Copyright (C) 1990-1995, 1998, 2001-2016 Free Software Foundation,
 @c Inc.
 @c See the file elisp.texi for copying conditions.
 @node Macros
@@ -55,6 +55,11 @@ expansion, which is @code{(setq x (1+ x))}.  Once the macro definition
 returns this expansion, Lisp proceeds to evaluate it, thus incrementing
 @code{x}.
 
+@defun macrop object
+This predicate tests whether its argument is a macro, and returns
+@code{t} if so, @code{nil} otherwise.
+@end defun
+
 @node Expansion
 @section Expansion of a Macro Call
 @cindex expansion of macros
@@ -155,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
@@ -189,10 +200,12 @@ During Compile}).
 
 @node Defining Macros
 @section Defining Macros
+@cindex defining macros
+@cindex macro, how to define
 
   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
+whose @sc{cdr} is a function.  Expansion of the macro works
+by applying the function (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
@@ -248,6 +261,7 @@ Form}.
 
 @node Problems with Macros
 @section Common Problems Using Macros
+@cindex macro caveats
 
   Macro expansion can have counterintuitive consequences.  This
 section describes some important consequences that can lead to
@@ -299,7 +313,7 @@ program is actually run.
   When defining a macro you must pay attention to the number of times
 the arguments will be evaluated when the expansion is executed.  The
 following macro (used to facilitate iteration) illustrates the
-problem.  This macro allows us to write a ``for'' loop construct.
+problem.  This macro allows us to write a for-loop construct.
 
 @findex for
 @example
@@ -337,7 +351,7 @@ For example, (for i from 1 to 10 do (print i))."
 
 @noindent
 The arguments @code{from}, @code{to}, and @code{do} in this macro are
-``syntactic sugar''; they are entirely ignored.  The idea is that you
+syntactic sugar; they are entirely ignored.  The idea is that you
 will write noise words (such as @code{from}, @code{to}, and @code{do})
 in those positions in the macro call.
 
@@ -560,7 +574,7 @@ If @code{initialize} is interpreted, a new list @code{(nil)} is
 constructed each time @code{initialize} is called.  Thus, no side effect
 survives between calls.  If @code{initialize} is compiled, then the
 macro @code{empty-object} is expanded during compilation, producing a
-single ``constant'' @code{(nil)} that is reused and altered each time
+single constant @code{(nil)} that is reused and altered each time
 @code{initialize} is called.
 
 One way to avoid pathological cases like this is to think of
@@ -580,6 +594,11 @@ calls to the macro.  An indentation specification is written like this:
 (declare (indent @var{indent-spec}))
 @end example
 
+@noindent
+@cindex @code{lisp-indent-function} property
+This results in the @code{lisp-indent-function} property being set on
+the macro name.
+
 @noindent
 Here are the possibilities for @var{indent-spec}: