7 files changed, 63 insertions, 30 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index b3b4abf2460..1ef5bca1d46 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,21 @@
+2004-01-03  Richard M. Stallman  <rms@gnu.org>
+
+        * frames.texi (Frames and Windows): Delete frame-root-window.
+
+2004-01-03  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * eval.texi, hash.texi, help.texi, symbols.texi: Add anchors.
+
+        * functions.texi: Various small changes in addition to the
+        following.
+        (What Is a Function): `functionp' returns nil for macros.  Clarify
+        behavior of this and following functions for symbol arguments.
+        (Function Documentation): Add `\' in front of (fn @var{arglist})
+        and explain why.
+        (Defining Functions): Mention DOCSTRING argument to `defalias'.
+        Add anchor.
+        (Mapping Functions): Add anchor.  Unquote nil in mapcar* example.
+
 2004-01-01  Miles Bader  <miles@gnu.org>
 
         * display.texi (Buttons): New section.
diff --git a/lispref/eval.texi b/lispref/eval.texi
index fcfde5849dd..7d1ebb9d307 100644
--- a/lispref/eval.texi
+++ b/lispref/eval.texi
@@ -313,6 +313,7 @@ symbol function indirection when calling @code{erste}.
 perform symbol function indirection explicitly.
 
 @c Emacs 19 feature
+@anchor{Definition of indirect-function}
 @defun indirect-function function
 This function returns the meaning of @var{function} as a function.  If
 @var{function} is a symbol, then it finds @var{function}'s function
diff --git a/lispref/frames.texi b/lispref/frames.texi
index ec3c1c6dc7c..a9b29332200 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -933,10 +933,6 @@ selected window.
   Conversely, selecting a window for Emacs with @code{select-window} also
 makes that window selected within its frame.  @xref{Selecting Windows}.
 
-@defun frame-root-window frame
-This function returns the window at the top left corner of @var{frame}.
-@end defun
-
   Another function that (usually) returns one of the windows in a given
 frame is @code{minibuffer-window}.  @xref{Minibuffer Misc}.
 
diff --git a/lispref/functions.texi b/lispref/functions.texi
index 4ee101ca871..4b727e76506 100644
--- a/lispref/functions.texi
+++ b/lispref/functions.texi
@@ -113,10 +113,15 @@ byte compiler.  @xref{Byte-Code Type}.
 @end table
 
 @defun functionp object
-This function returns @code{t} if @var{object} is any kind of function,
-or a special form or macro.
+This function returns @code{t} if @var{object} is any kind of
+function, or a special form, or, recursively, a symbol whose function
+definition is a function or special form.  (This does not include
+macros.)
 @end defun
 
+Unlike @code{functionp}, the next three functions do @emph{not}
+treat a symbol as its function definition.
+
 @defun subrp object
 This function returns @code{t} if @var{object} is a built-in function
 (i.e., a Lisp primitive).
@@ -428,13 +433,14 @@ conventions different from the actual function arguments.  Write
 text like this:
 
 @example
-(fn @var{arglist})
+\(fn @var{arglist})
 @end example
 
 @noindent
-following a blank line, with no newline following it inside the
-documentation string.  This feature is particularly useful for
-macro definitions.
+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
@@ -571,9 +577,15 @@ defined is often done deliberately, and there is no way to distinguish
 deliberate redefinition from unintentional redefinition.
 @end defspec
 
-@defun defalias name definition
+@anchor{Definition of defalias}
+@defun defalias name definition &optional docstring
 This special form defines the symbol @var{name} as a function, with
 definition @var{definition} (which can be any valid Lisp function).
+It returns @var{definition}.
+
+If @var{docstring} is non-@code{nil}, it becomes the function
+documentation of @var{name}.  Otherwise, any documentation provided by
+@var{definition} is used.
 
 The proper place to use @code{defalias} is where a specific function
 name is being defined---especially where that name appears explicitly in
@@ -587,7 +599,7 @@ records.
 @end defun
 
   You cannot create a new primitive function with @code{defun} or
-@code{defalias}, but you use them to change the function definition of
+@code{defalias}, but you can use them to change the function definition of
 any symbol, even one such as @code{car} or @code{x-popup-menu} whose
 normal definition is a primitive.  However, this is risky: for
 instance, it is next to impossible to redefine @code{car} without
@@ -700,8 +712,8 @@ primitive function; special forms and macros do not make sense in
 @end group
 @end example
 
-For an interesting example of using @code{apply}, see the description of
-@code{mapcar}, in @ref{Mapping Functions}.
+For an interesting example of using @code{apply}, see @ref{Definition
+of mapcar}.
 @end defun
 
 @cindex functionals
@@ -726,19 +738,21 @@ This function ignores any arguments and returns @code{nil}.
 @section Mapping Functions
 @cindex mapping functions
 
-  A @dfn{mapping function} applies a given function to each element of a
-list or other collection.  Emacs Lisp has several such functions;
-@code{mapcar} and @code{mapconcat}, which scan a list, are described
-here.  @xref{Creating Symbols}, for the function @code{mapatoms} which
-maps over the symbols in an obarray.  @xref{Hash Access}, for the
-function @code{maphash} which maps over key/value associations in a
-hash table.
+  A @dfn{mapping function} applies a given function (@emph{not} a
+special form or macro) to each element of a list or other collection.
+Emacs Lisp has several such functions; @code{mapcar} and
+@code{mapconcat}, which scan a list, are described here.
+@xref{Definition of mapatoms}, for the function @code{mapatoms} which
+maps over the symbols in an obarray.  @xref{Definition of maphash},
+for the function @code{maphash} which maps over key/value associations
+in a hash table.
 
   These mapping functions do not allow char-tables because a char-table
 is a sparse array whose nominal range of indices is very large.  To map
 over a char-table in a way that deals properly with its sparse nature,
 use the function @code{map-char-table} (@pxref{Char-Tables}).
 
+@anchor{Definition of mapcar}
 @defun mapcar function sequence
 @code{mapcar} applies @var{function} to each element of @var{sequence}
 in turn, and returns a list of the results.
@@ -770,7 +784,7 @@ length of @var{sequence}.
   "Apply FUNCTION to successive cars of all ARGS.
 Return the list of results."
   ;; @r{If no list is exhausted,}
-  (if (not (memq 'nil args))
+  (if (not (memq nil args))
       ;; @r{apply function to @sc{car}s.}
       (cons (apply function (mapcar 'car args))
             (apply 'mapcar* function
@@ -961,8 +975,8 @@ to be used only as a function, and therefore can safely be compiled.
 Contrast this with @code{quote}, in @ref{Quoting}.
 @end defspec
 
-  See @code{documentation} in @ref{Accessing Documentation}, for a
-realistic example using @code{function} and an anonymous function.
+  @xref{describe-symbols example}, for a realistic example using
+@code{function} and an anonymous function.
 
 @node Function Cells
 @section Accessing Function Cell Contents
@@ -971,8 +985,8 @@ realistic example using @code{function} and an anonymous function.
 function cell of the symbol.  The functions described here access, test,
 and set the function cell of symbols.
 
-  See also the function @code{indirect-function} in @ref{Function
-Indirection}.
+  See also the function @code{indirect-function}.  @xref{Definition of
+indirect-function}.
 
 @defun symbol-function symbol
 @kindex void-function
@@ -1027,8 +1041,9 @@ is a legitimate function.
 
 @defun fmakunbound symbol
 This function makes @var{symbol}'s function cell void, so that a
-subsequent attempt to access this cell will cause a @code{void-function}
-error.  (See also @code{makunbound}, in @ref{Void Variables}.)
+subsequent attempt to access this cell will cause a
+@code{void-function} error.  It returns @var{symbol}.  (See also
+@code{makunbound}, in @ref{Void Variables}.)
 
 @example
 @group
@@ -1064,7 +1079,7 @@ There are three normal uses of this function:
 Copying one symbol's function definition to another---in other words,
 making an alternate name for a function.  (If you think of this as the
 definition of the new name, you should use @code{defalias} instead of
-@code{fset}; see @ref{Defining Functions}.)
+@code{fset}; see @ref{Definition of defalias}.)
 
 @item
 Giving a symbol a function definition that is not a list and therefore
@@ -1305,7 +1320,7 @@ See @ref{Anonymous Functions}.
 See @ref{Calling Functions}.
 
 @item indirect-function
-See @ref{Function Indirection}.
+See @ref{Definition of indirect-function}.
 
 @item interactive
 See @ref{Using Interactive}.
diff --git a/lispref/hash.texi b/lispref/hash.texi
index a27894fa24b..909c7fb0b7c 100644
--- a/lispref/hash.texi
+++ b/lispref/hash.texi
@@ -205,6 +205,7 @@ table.
 @end defun
 
 @tindex maphash
+@anchor{Definition of maphash}
 @defun maphash function table
 This function calls @var{function} once for each of the associations in
 @var{table}.  The function @var{function} should accept two
diff --git a/lispref/help.texi b/lispref/help.texi
index 343ffb66078..dc14b0226b5 100644
--- a/lispref/help.texi
+++ b/lispref/help.texi
@@ -156,6 +156,7 @@ Here is an example of using the two functions, @code{documentation} and
 @code{documentation-property}, to display the documentation strings for
 several symbols in a @samp{*Help*} buffer.
 
+@anchor{describe-symbols example}
 @smallexample
 @group
 (defun describe-symbols (pattern)
diff --git a/lispref/symbols.texi b/lispref/symbols.texi
index 6cde2115259..632f2cc5174 100644
--- a/lispref/symbols.texi
+++ b/lispref/symbols.texi
@@ -360,6 +360,7 @@ This variable is the standard obarray for use by @code{intern} and
 @code{read}.
 @end defvar
 
+@anchor{Definition of mapatoms}
 @defun mapatoms function &optional obarray
 This function calls @var{function} once with each symbol in the obarray
 @var{obarray}.  Then it returns @code{nil}.  If @var{obarray} is