(What Is a Function): Wording cleanup.

(Function Documentation): Minor cleanup.
Explain purpose of calling convention at end of doc string.
(Function Names): Wording cleanup.
(Calling Functions): Wording cleanup.
Explain better how funcall calls the function.
(Function Cells): Delete example of saving and redefining function.

1 files changed, 37 insertions, 49 deletions

diff --git a/lispref/functions.texi b/lispref/functions.texi
index 5c7433507b0..26c2449fee6 100644
--- a/lispref/functions.texi
+++ b/lispref/functions.texi
@@ -53,7 +53,7 @@ macros are not functions.
 @cindex built-in function
 A @dfn{primitive} is a function callable from Lisp that is written in C,
 such as @code{car} or @code{append}.  These functions are also called
-@dfn{built-in} functions or @dfn{subrs}.  (Special forms are also
+@dfn{built-in functions}, or @dfn{subrs}.  (Special forms are also
 considered primitives.)
 
 Usually the reason we implement a function as a primitive is either
@@ -412,13 +412,14 @@ are easier to access.
 because @code{apropos} displays just this first line.  It should consist
 of one or two complete sentences that summarize the function's purpose.
 
-  The start of the documentation string is usually indented in the source file,
-but since these spaces come before the starting double-quote, they are not part of
-the string.  Some people make a practice of indenting any additional
-lines of the string so that the text lines up in the program source.
-@emph{That is a mistake.}  The indentation of the following lines is
-inside the string; what looks nice in the source code will look ugly
-when displayed by the help commands.
+  The start of the documentation string is usually indented in the
+source file, but since these spaces come before the starting
+double-quote, they are not part of the string.  Some people make a
+practice of indenting any additional lines of the string so that the
+text lines up in the program source.  @emph{That is a mistake.}  The
+indentation of the following lines is inside the string; what looks
+nice in the source code will look ugly when displayed by the help
+commands.
 
   You may wonder how the documentation string could be optional, since
 there are required components of the function that follow it (the body).
@@ -438,9 +439,14 @@ text like this:
 
 @noindent
 following a blank line, at the beginning of the line, with no newline
-following it inside the documentation string.  This feature is
-particularly useful for macro definitions.  The @samp{\} is used to
-avoid confusing the Emacs motion commands.
+following it inside the documentation string.  (The @samp{\} is used
+to avoid confusing the Emacs motion commands.)  The calling convention
+specified in this way appears in help messages in place of the one
+derived from the actual arguments of the function.
+
+  This feature is particularly useful for macro definitions, since the
+arguments written in a macro definition often do not correspond to the
+way users think of the parts of the macro call.
 
 @node Function Names
 @section Naming a Function
@@ -481,8 +487,8 @@ practice).
   We often identify functions with the symbols used to name them.  For
 example, we often speak of ``the function @code{car}'', not
 distinguishing between the symbol @code{car} and the primitive
-subr-object that is its function definition.  For most purposes, there
-is no need to distinguish.
+subr-object that is its function definition.  For most purposes, the
+distinction is not important.
 
   Even so, keep in mind that a function need not have a unique name.  While
 a given function object @emph{usually} appears in the function cell of only
@@ -626,13 +632,12 @@ For example, evaluating the list @code{(concat "a" "b")} calls the
 function @code{concat} with arguments @code{"a"} and @code{"b"}.
 @xref{Evaluation}, for a description of evaluation.
 
-  When you write a list as an expression in your program, the function
-name it calls is written in your program.  This means that you choose
-which function to call, and how many arguments to give it, when you
-write the program.  Usually that's just what you want.  Occasionally you
-need to compute at run time which function to call.  To do that, use the
-function @code{funcall}.  When you also need to determine at run time
-how many arguments to pass, use @code{apply}.
+  When you write a list as an expression in your program, you specify
+which function to call, and how many arguments to give it, in the text
+of the program.  Usually that's just what you want.  Occasionally you
+need to compute at run time which function to call.  To do that, use
+the function @code{funcall}.  When you also need to determine at run
+time how many arguments to pass, use @code{apply}.
 
 @defun funcall function &rest arguments
 @code{funcall} calls @var{function} with @var{arguments}, and returns
@@ -641,11 +646,12 @@ whatever @var{function} returns.
 Since @code{funcall} is a function, all of its arguments, including
 @var{function}, are evaluated before @code{funcall} is called.  This
 means that you can use any expression to obtain the function to be
-called.  It also means that @code{funcall} does not see the expressions
-you write for the @var{arguments}, only their values.  These values are
-@emph{not} evaluated a second time in the act of calling @var{function};
-@code{funcall} enters the normal procedure for calling a function at the
-place where the arguments have already been evaluated.
+called.  It also means that @code{funcall} does not see the
+expressions you write for the @var{arguments}, only their values.
+These values are @emph{not} evaluated a second time in the act of
+calling @var{function}; the operation of @code{funcall} is like the
+normal procedure for calling a function, once its arguments have
+already been evaluated.
 
 The argument @var{function} must be either a Lisp function or a
 primitive function.  Special forms and macros are not allowed, because
@@ -1137,30 +1143,12 @@ Here are examples of these uses:
 @end example
 @end defun
 
-  When writing a function that extends a previously defined function,
-the following idiom is sometimes used:
-
-@example
-(fset 'old-foo (symbol-function 'foo))
-(defun foo ()
-  "Just like old-foo, except more so."
-@group
-  (old-foo)
-  (more-so))
-@end group
-@end example
-
-@noindent
-This does not work properly if @code{foo} has been defined to autoload.
-In such a case, when @code{foo} calls @code{old-foo}, Lisp attempts
-to define @code{old-foo} by loading a file.  Since this presumably
-defines @code{foo} rather than @code{old-foo}, it does not produce the
-proper results.  The only way to avoid this problem is to make sure the
-file is loaded before moving aside the old definition of @code{foo}.
-
-  But it is unmodular and unclean, in any case, for a Lisp file to
-redefine a function defined elsewhere.  It is cleaner to use the advice
-facility (@pxref{Advising Functions}).
+  @code{fset} is sometimes used to save the old definition of a
+function before redefining it.  That permits the new definition to
+invoke the old definition.  But it is unmodular and unclean for a Lisp
+file to redefine a function defined elsewhere.  If you want to modify
+a function defined by another package, it is cleaner to use
+@code{defadvice} (@pxref{Advising Functions}).
 
 @node Inline Functions
 @section Inline Functions