X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/21fa24820007018632b3719ac6855eef6b688852..595195a10e5dd568bf249f5fb6778ae3d7037cd5:/doc/lispref/macros.texi

diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index b0dee1bf21..6472bd1b03 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -1,6 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998, 2001-2016 Free Software Foundation,
+@c Inc.
 @c See the file elisp.texi for copying conditions.
 @node Macros
 @chapter Macros
@@ -35,7 +36,7 @@ instead.  @xref{Inline Functions}.
 @section A Simple Example of a Macro
 
   Suppose we would like to define a Lisp construct to increment a
-variable value, much like the @code{++} operator in C.  We would like to
+variable value, much like the @code{++} operator in C@.  We would like to
 write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}.
 Here's a macro definition that does the job:
 
@@ -54,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
@@ -154,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
@@ -188,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
@@ -247,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
@@ -298,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
@@ -336,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.
 
@@ -559,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
@@ -579,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}:
 
@@ -605,12 +625,12 @@ calculate the indentation of a line within this expression.  The
 function receives two arguments:
 
 @table @asis
+@item @var{pos}
+The position at which the line being indented begins.
 @item @var{state}
 The value returned by @code{parse-partial-sexp} (a Lisp primitive for
 indentation and nesting computation) when it parses up to the
 beginning of this line.
-@item @var{pos}
-The position at which the line being indented begins.
 @end table
 
 @noindent