@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
@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
@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 function. Expansion of the macro works
@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
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
@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.
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
(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}: