Sync up with r21-2-27.

[chise/xemacs-chise.git] / info / lispref.info-11

diff --git a/info/lispref.info-11 b/info/lispref.info-11
index 20e1353..023ded4 100644 (file)
--- a/info/lispref.info-11
+++ b/info/lispref.info-11
@@ -50,6 +50,74 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
+File: lispref.info,  Node: Compiling Macros,  Next: Defining Macros,  Prev: Expansion,  Up: Macros
+
+Macros and Byte Compilation
+===========================
+
+   You might ask why we take the trouble to compute an expansion for a
+macro and then evaluate the expansion.  Why not have the macro body
+produce the desired results directly?  The reason has to do with
+compilation.
+
+   When a macro call appears in a Lisp program being compiled, the Lisp
+compiler calls the macro definition just as the interpreter would, and
+receives an expansion.  But instead of evaluating this expansion, it
+compiles the expansion as if it had appeared directly in the program.
+As a result, the compiled code produces the value and side effects
+intended for the macro, but executes at full compiled speed.  This would
+not work if the macro body computed the value and side effects
+itself--they would be computed at compile time, which is not useful.
+
+   In order for compilation of macro calls to work, the macros must be
+defined in Lisp when the calls to them are compiled.  The compiler has a
+special feature to help you do this: if a file being compiled contains a
+`defmacro' form, the macro is defined temporarily for the rest of the
+compilation of that file.  To use this feature, you must define the
+macro in the same file where it is used and before its first use.
+
+   Byte-compiling a file executes any `require' calls at top-level in
+the file.  This is in case the file needs the required packages for
+proper compilation.  One way to ensure that necessary macro definitions
+are available during compilation is to require the files that define
+them (*note Named Features::.).  To avoid loading the macro definition
+files when someone *runs* the compiled program, write
+`eval-when-compile' around the `require' calls (*note Eval During
+Compile::.).
+
+\1f
+File: lispref.info,  Node: Defining Macros,  Next: Backquote,  Prev: Compiling Macros,  Up: Macros
+
+Defining Macros
+===============
+
+   A Lisp macro is a list whose CAR is `macro'.  Its CDR should be a
+function; expansion of the macro works by applying the function (with
+`apply') to the list of unevaluated argument-expressions 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 `mapcar'.  In practice, all
+Lisp macros have names, and they are usually defined with the special
+form `defmacro'.
+
+ - Special Form: defmacro NAME ARGUMENT-LIST BODY-FORMS...
+     `defmacro' defines the symbol NAME as a macro that looks like this:
+
+          (macro lambda ARGUMENT-LIST . BODY-FORMS)
+
+     This macro object is stored in the function cell of NAME.  The
+     value returned by evaluating the `defmacro' form is NAME, but
+     usually we ignore this value.
+
+     The shape and meaning of ARGUMENT-LIST is the same as in a
+     function, and the keywords `&rest' and `&optional' may be used
+     (*note Argument List::.).  Macros may have a documentation string,
+     but any `interactive' declaration is ignored since macros cannot be
+     called interactively.
+
+\1f
 File: lispref.info,  Node: Backquote,  Next: Problems with Macros,  Prev: Defining Macros,  Up: Macros
 
 Backquote