; Move the description of define-inline to a different node in functions.texi

1 files changed, 100 insertions, 96 deletions

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 8e3e6aefb00..5cf67ba6473 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -576,8 +576,9 @@ naming conventions, which are being phased out.
 @cindex defining a function
 
   We usually give a name to a function when it is first created.  This
-is called @dfn{defining a function}, and it is done with the
-@code{defun} macro.
+is called @dfn{defining a function}, and we usually do it with the
+@code{defun} macro.  This section also describes other ways to define
+a function.
 
 @defmac defun name args [doc] [declare] [interactive] body@dots{}
 @code{defun} is the usual way to define new Lisp functions.  It
@@ -682,95 +683,8 @@ definition will have no effect on them.
 and tells the Lisp compiler to perform inline expansion on it.
 @xref{Inline Functions}.
 
-  Alternatively, you can define a function by providing the code which
-will inline it as a compiler macro.  The following macros make this
-possible.
-
-@c FIXME: Can define-inline use the interactive spec?
-@defmac define-inline name args [doc] [declare] body@dots{}
-Define a function @var{name} by providing code that does its inlining,
-as a compiler macro.  The function will accept the argument list
-@var{args} and will have the specified @var{body}.
-
-If present, @var{doc} should be the function's documentation string
-(@pxref{Function Documentation}); @var{declare}, if present, should be
-a @code{declare} form (@pxref{Declare Form}) specifying the function's
-metadata.
-@end defmac
-
-Functions defined via @code{define-inline} have several advantages
-with respect to macros defined by @code{defsubst} or @code{defmacro}:
-
-@itemize @minus
-@item
-They can be passed to @code{mapcar} (@pxref{Mapping Functions}).
-
-@item
-They are more efficient.
-
-@item
-They can be used as @dfn{place forms} to store values
-(@pxref{Generalized Variables}).
-
-@item
-They behave in a more predictable way than @code{cl-defsubst}
-(@pxref{Argument Lists,,, cl, Common Lisp Extensions for GNU Emacs
-Lisp}).
-@end itemize
-
-Like @code{defmacro}, a function inlined with @code{define-inline}
-inherits the scoping rules, either dynamic or lexical, from the call
-site.  @xref{Variable Scoping}.
-
-The following macros should be used in the body of a function defined
-by @code{define-inline}.
-
-@defmac inline-quote expression
-Quote @var{expression} for @code{define-inline}.  This is similar to
-the backquote (@pxref{Backquote}), but quotes code and accepts only
-@code{,}, not @code{,@@}.
-@end defmac
-
-@defmac inline-letevals (bindings@dots{}) body@dots{}
-This is similar to @code{let} (@pxref{Local Variables}): it sets up
-local variables as specified by @var{bindings}, and then evaluates
-@var{body} with those bindings in effect.  Each element of
-@var{bindings} should be either a symbol or a list of the form
-@w{@code{(@var{var} @var{expr})}}; the result is to evaluate
-@var{expr} and bind @var{var} to the result.  The tail of
-@var{bindings} can be either @code{nil} or a symbol which should hold
-a list of arguments, in which case each argument is evaluated, and the
-symbol is bound to the resulting list.
-@end defmac
-
-@defmac inline-const-p expression
-Return non-@code{nil} if the value of @var{expression} is already
-known.
-@end defmac
-
-@defmac inline-const-val expression
-Return the value of @var{expression}.
-@end defmac
-
-@defmac inline-error format &rest args
-Signal an error, formatting @var{args} according to @var{format}.
-@end defmac
-
-Here's an example of using @code{define-inline}:
-
-@lisp
-(define-inline myaccessor (obj)
-  (inline-letevals (obj)
-    (inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2)))))
-@end lisp
-
-@noindent
-This is equivalent to
-
-@lisp
-(defsubst myaccessor (obj)
-  (if (foo-p obj) (aref (cdr obj) 3) (aref obj 2)))
-@end lisp
+  To undefine a function name, use @code{fmakunbound}.
+@xref{Function Cells}.
 
 @node Calling Functions
 @section Calling Functions
@@ -2155,8 +2069,12 @@ this:
   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.  To define an inline function, use
-@code{defsubst} instead of @code{defun}.
+is expanded into the caller.
+
+  The simple way to define an inline function, is to write
+@code{defsubst} instead of @code{defun}.  The rest of the definition
+looks just the same, but using @code{defsubst} says to make it inline
+for byte compilation.
 
 @defmac defsubst name args [doc] [declare] [interactive] body@dots{}
 This macro defines an inline function.  Its syntax is exactly the same
@@ -2194,9 +2112,95 @@ argument of an inline function is evaluated exactly once, you needn't
 worry about how many times the body uses the arguments, as you do for
 macros.
 
-  As an alternative to @code{defsubst}, you can use
-@code{define-inline} to define functions via their exhaustive compiler
-macro.  @xref{Defining Functions, define-inline}.
+  Alternatively, you can define a function by providing the code which
+will inline it as a compiler macro.  The following macros make this
+possible.
+
+@c FIXME: Can define-inline use the interactive spec?
+@defmac define-inline name args [doc] [declare] body@dots{}
+Define a function @var{name} by providing code that does its inlining,
+as a compiler macro.  The function will accept the argument list
+@var{args} and will have the specified @var{body}.
+
+If present, @var{doc} should be the function's documentation string
+(@pxref{Function Documentation}); @var{declare}, if present, should be
+a @code{declare} form (@pxref{Declare Form}) specifying the function's
+metadata.
+@end defmac
+
+Functions defined via @code{define-inline} have several advantages
+with respect to macros defined by @code{defsubst} or @code{defmacro}:
+
+@itemize @minus
+@item
+They can be passed to @code{mapcar} (@pxref{Mapping Functions}).
+
+@item
+They are more efficient.
+
+@item
+They can be used as @dfn{place forms} to store values
+(@pxref{Generalized Variables}).
+
+@item
+They behave in a more predictable way than @code{cl-defsubst}
+(@pxref{Argument Lists,,, cl, Common Lisp Extensions for GNU Emacs
+Lisp}).
+@end itemize
+
+Like @code{defmacro}, a function inlined with @code{define-inline}
+inherits the scoping rules, either dynamic or lexical, from the call
+site.  @xref{Variable Scoping}.
+
+The following macros should be used in the body of a function defined
+by @code{define-inline}.
+
+@defmac inline-quote expression
+Quote @var{expression} for @code{define-inline}.  This is similar to
+the backquote (@pxref{Backquote}), but quotes code and accepts only
+@code{,}, not @code{,@@}.
+@end defmac
+
+@defmac inline-letevals (bindings@dots{}) body@dots{}
+This is similar to @code{let} (@pxref{Local Variables}): it sets up
+local variables as specified by @var{bindings}, and then evaluates
+@var{body} with those bindings in effect.  Each element of
+@var{bindings} should be either a symbol or a list of the form
+@w{@code{(@var{var} @var{expr})}}; the result is to evaluate
+@var{expr} and bind @var{var} to the result.  The tail of
+@var{bindings} can be either @code{nil} or a symbol which should hold
+a list of arguments, in which case each argument is evaluated, and the
+symbol is bound to the resulting list.
+@end defmac
+
+@defmac inline-const-p expression
+Return non-@code{nil} if the value of @var{expression} is already
+known.
+@end defmac
+
+@defmac inline-const-val expression
+Return the value of @var{expression}.
+@end defmac
+
+@defmac inline-error format &rest args
+Signal an error, formatting @var{args} according to @var{format}.
+@end defmac
+
+Here's an example of using @code{define-inline}:
+
+@lisp
+(define-inline myaccessor (obj)
+  (inline-letevals (obj)
+    (inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2)))))
+@end lisp
+
+@noindent
+This is equivalent to
+
+@lisp
+(defsubst myaccessor (obj)
+  (if (foo-p obj) (aref (cdr obj) 3) (aref obj 2)))
+@end lisp
 
 @node Declare Form
 @section The @code{declare} Form