[Emacs-diffs] Changes to emacs/lispref/functions.texi

[Richard M . Stallman]

Index: emacs/lispref/functions.texi
diff -c emacs/lispref/functions.texi:1.29 emacs/lispref/functions.texi:1.30
*** emacs/lispref/functions.texi:1.29   Wed Jun 23 16:24:43 2004
--- emacs/lispref/functions.texi        Mon Feb 14 10:11:48 2005
***************
*** 53,59 ****
  @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
  considered primitives.)
  
  Usually the reason we implement a function as a primitive is either
--- 53,59 ----
  @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
  considered primitives.)
  
  Usually the reason we implement a function as a primitive is either
***************
*** 412,424 ****
  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.
  
    You may wonder how the documentation string could be optional, since
  there are required components of the function that follow it (the body).
--- 412,425 ----
  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.
  
    You may wonder how the documentation string could be optional, since
  there are required components of the function that follow it (the body).
***************
*** 438,446 ****
  
  @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.
  
  @node Function Names
  @section Naming a Function
--- 439,452 ----
  
  @noindent
  following a blank line, at the beginning of the line, with no newline
! 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,488 ****
    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.
  
    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
--- 487,494 ----
    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, 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,638 ****
  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}.
  
  @defun funcall function &rest arguments
  @code{funcall} calls @var{function} with @var{arguments}, and returns
--- 632,643 ----
  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, 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,651 ****
  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.
  
  The argument @var{function} must be either a Lisp function or a
  primitive function.  Special forms and macros are not allowed, because
--- 646,657 ----
  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}; 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,1166 ****
  @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}).
  
  @node Inline Functions
  @section Inline Functions
--- 1143,1154 ----
  @end example
  @end defun
  
!   @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