entered into RCS

2 files changed, 58 insertions, 45 deletions

diff --git a/lispref/compile.texi b/lispref/compile.texi
index 38f2b8196f3..69b328fd905 100644
--- a/lispref/compile.texi
+++ b/lispref/compile.texi
@@ -86,9 +86,9 @@ the @code{byte-compile} function.  You can compile a whole file with
 @code{byte-compile-file}, or several files with
 @code{byte-recompile-directory} or @code{batch-byte-compile}.
 
-  When you run the byte compiler, you may get warnings in a buffer called
-@samp{*Compile-Log*}.  These report usage in your program that suggest a
-problem, but are not necessarily erroneous.
+  When you run the byte compiler, you may get warnings in a buffer
+called @samp{*Compile-Log*}.  These report things in your program that
+suggest a problem but are not necessarily erroneous.
 
 @cindex macro compilation
   Be careful when byte-compiling code that uses macros.  Macro calls are
@@ -97,7 +97,7 @@ for proper compilation.  For more details, see @ref{Compiling Macros}.
 
   Normally, compiling a file does not evaluate the file's contents or
 load the file.  But it does execute any @code{require} calls at
-top-level in the file.  One way to ensure that necessary macro
+top level in the file.  One way to ensure that necessary macro
 definitions are available during compilation is to require the file that
 defines them.  @xref{Features}.
 
@@ -201,7 +201,7 @@ The returned value of this command is unpredictable.
 This function runs @code{byte-compile-file} on files specified on the
 command line.  This function must be used only in a batch execution of
 Emacs, as it kills Emacs on completion.  An error in one file does not
-prevent processing of subsequent files.  (The file which gets the error
+prevent processing of subsequent files.  (The file that gets the error
 will not, of course, produce any compiled code.)
 
 @example
@@ -238,12 +238,13 @@ this way.
 @end defspec
 
 @defspec eval-when-compile body
-This form marks @var{body} to be evaluated at compile time @emph{only}.
-The result of evaluation by the compiler becomes a constant which
-appears in the compiled program.  When the program is interpreted, not
-compiled at all, @var{body} is evaluated normally.
+This form marks @var{body} to be evaluated at compile time and not when
+the compiled program is loaded.  The result of evaluation by the
+compiler becomes a constant which appears in the compiled program.  When
+the program is interpreted, not compiled at all, @var{body} is evaluated
+normally.
 
-At top-level, this is analogous to the Common Lisp idiom
+At top level, this is analogous to the Common Lisp idiom
 @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the Common Lisp
 @samp{#.} reader macro (but not when interpreting) is closer to what
 @code{eval-when-compile} does.
@@ -279,7 +280,8 @@ The list of argument symbols.
 The string containing the byte-code instructions.
 
 @item constants
-The vector of constants referenced by the byte code.
+The vector of Lisp objects referenced by the byte code.  These include
+symbols used as function names and variable names.
 
 @item stacksize
 The maximum stack size this function needs.
@@ -318,7 +320,7 @@ with @var{elements} as its elements.
 
   You should not try to come up with the elements for a byte-code
 function yourself, because if they are inconsistent, Emacs may crash
-when you call the function.  Always leave it to the byte-compiler to
+when you call the function.  Always leave it to the byte compiler to
 create these objects; it makes the elements consistent (we hope).
 
   You can access the elements of a byte-code object using @code{aref};
@@ -336,11 +338,11 @@ form.
 
   The byte-code interpreter is implemented as a simple stack machine.
 It pushes values onto a stack of its own, then pops them off to use them
-in calculations and push the result back on the stack.  When a byte-code
-function returns, it pops a value off the stack and returns it as the
-value of the function.
+in calculations whose results are themselves pushed back on the stack.
+When a byte-code function returns, it pops a value off the stack and
+returns it as the value of the function.
 
-  In addition to the stack, byte-code functions can use, bind and set
+  In addition to the stack, byte-code functions can use, bind, and set
 ordinary Lisp variables, by transferring values between variables and
 the stack.
 
@@ -442,7 +444,7 @@ they still serve their purpose.
 
 @group
                             ; @r{Stack now contains:}
-                            ;   @minus{} @r{result of result of recursive}
+                            ;   @minus{} @r{result of recursive}
                             ;        @r{call to @code{factorial}}
                             ;   @minus{} @r{value of @code{integer}}
                             ;   @minus{} @r{@code{*}}
@@ -537,10 +539,10 @@ The @code{silly-loop} function is somewhat more complex:
 @end group
 
 @group
-9   goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} > 0}
+9   goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
+                            ;   @r{(this exits the while loop).}
                             ;   @r{else pop top of stack}
                             ;   @r{and continue}
-                            ;   @r{(this exits the while loop).}
 @end group
 
 @group
@@ -563,6 +565,8 @@ The @code{silly-loop} function is somewhat more complex:
 @group
 17  discard                 ; @r{Discard result of while loop}
                             ;   @r{by popping top of stack.}
+                            ;   @r{This result is the value @code{nil} that}
+                            ;   @r{was not popped by the goto at 9.}
 @end group
 
 @group
diff --git a/lispref/loading.texi b/lispref/loading.texi
index 59d27a0a13e..892473b9baf 100644
--- a/lispref/loading.texi
+++ b/lispref/loading.texi
@@ -21,8 +21,8 @@ in an Emacs buffer.
 
 @cindex top-level form
   The loaded file must contain Lisp expressions, either as source code
-or, optionally, as byte-compiled code.  Each form in the file is called
-a @dfn{top-level form}.  There is no special format for the forms in a
+or as byte-compiled code.  Each form in the file is called a
+@dfn{top-level form}.  There is no special format for the forms in a
 loadable file; any form in a file may equally well be typed directly
 into a buffer and evaluated there.  (Indeed, most code is tested this
 way.)  Most often, the forms are function definitions and variable
@@ -61,7 +61,7 @@ To find the file, @code{load} first looks for a file named
 @file{@var{filename}.elc}, that is, for a file whose name is
 @var{filename} with @samp{.elc} appended.  If such a file exists, it is
 loaded.  If there is no file by that name, then @code{load} looks for a
-file names @file{@var{filename}.el}.  If that file exists, it is loaded.
+file named @file{@var{filename}.el}.  If that file exists, it is loaded.
 Finally, if neither of those names is found, @code{load} looks for a
 file named @var{filename} with nothing appended, and loads it if it
 exists.  (The @code{load} function is not clever about looking at
@@ -92,8 +92,8 @@ non-@code{nil}.
 
 @cindex load errors
 Any unhandled errors while loading a file terminate loading.  If the
-load was done for the sake of @code{autoload}, certain kinds of
-top-level forms, those which define functions, are undone.
+load was done for the sake of @code{autoload}, any function definitions
+made during the loading are undone.
 
 @kindex file-error
 If @code{load} can't find the file to load, then normally it signals the
@@ -166,11 +166,12 @@ followed then by the @file{/user/bil/emacs} directory and then by
 the @file{/usr/local/lisplib} directory,
 which are then followed by the standard directories for Lisp code.
 
-The command line options @samp{-l} or @samp{-load} specify Lispa library
-to load.  Since this file might be in the current directory, Emacs 18
-temporarily adds the current directory to the front of @code{load-path}
-so the file can be found there.  Newer Emacs versions also find such
-files in the current directory, but without altering @code{load-path}.
+The command line options @samp{-l} or @samp{-load} specify a Lisp
+library to load as part of Emacs startup.  Since this file might be in
+the current directory, Emacs 18 temporarily adds the current directory
+to the front of @code{load-path} so the file can be found there.  Newer
+Emacs versions also find such files in the current directory, but
+without altering @code{load-path}.
 @end defopt
 
 @defvar load-in-progress
@@ -202,8 +203,8 @@ for the command @code{update-file-autoloads}, which constructs calls to
 comments are the most convenient way to make a function autoload, but
 only for packages installed along with Emacs.
 
-@defun autoload symbol filename &optional docstring interactive type
-This function defines the function (or macro) named @var{symbol} so as
+@defun autoload function filename &optional docstring interactive type
+This function defines the function (or macro) named @var{function} so as
 to load automatically from @var{filename}.  The string @var{filename}
 specifies the file to load to get the real definition of @var{function}.
 
@@ -227,9 +228,9 @@ keymap.  Various parts of Emacs need to know this information without
 loading the real definition.
 
 @cindex function cell in autoload
-If @var{symbol} already has a non-void function definition that is not
+If @var{function} already has a non-void function definition that is not
 an autoload object, @code{autoload} does nothing and returns @code{nil}.
-If the function cell of @var{symbol} is void, or is already an autoload
+If the function cell of @var{function} is void, or is already an autoload
 object, then it is defined as an autoload object like this:
 
 @example
@@ -278,11 +279,11 @@ autoloads for all files in the current directory.
   The same magic comment can copy any kind of form into
 @file{loaddefs.el}.  If the form following the magic comment is not a
 function definition, it is copied verbatim.  You can also use a magic
-comment to execute a form at build time executing it when the file
-itself is loaded.  To do this, write the form @dfn{on the same line} as
-the magic comment.  Since it is in a comment, it does nothing when you
-load the source file; but @code{update-file-autoloads} copies it to
-@file{loaddefs.el}, where it is executed while building Emacs.
+comment to execute a form at build time @emph{without} executing it when
+the file itself is loaded.  To do this, write the form @dfn{on the same
+line} as the magic comment.  Since it is in a comment, it does nothing
+when you load the source file; but @code{update-file-autoloads} copies
+it to @file{loaddefs.el}, where it is executed while building Emacs.
 
   The following example shows how @code{doctor} is prepared for
 autoloading with a magic comment:
@@ -367,7 +368,9 @@ has been loaded before:
 @noindent
 If the library uses @code{provide} to provide a named feature, you can
 use @code{featurep} to test whether the library has been loaded.
+@ifinfo
 @xref{Features}.
+@end ifinfo
 
 @node Features
 @section Features
@@ -391,7 +394,7 @@ hasn't been loaded already.
 feature name as argument.  @code{require} looks in the global variable
 @code{features} to see whether the desired feature has been provided
 already.  If not, it loads the feature from the appropriate file.  This
-file should call @code{provide} at the top-level to add the feature to
+file should call @code{provide} at the top level to add the feature to
 @code{features}; if it fails to do so, @code{require} signals an error.
 @cindex load error with require
 
@@ -427,7 +430,7 @@ This adds @code{comint} to the global @code{features} list, so that
 done.
 
 @cindex byte-compiling @code{require}
-  When @code{require} is used at top-level in a file, it takes effect
+  When @code{require} is used at top level in a file, it takes effect
 when you byte-compile that file (@pxref{Byte Compilation}) as well as
 when you load it.  This is in case the required package contains macros
 that the byte compiler must know about.
@@ -446,6 +449,12 @@ feature, as in the following example.
 @end group
 @end smallexample
 
+@noindent
+The compiler ignores the @code{provide}, then processes the
+@code{require} by loading the file in question.  Loading the file does
+execute the @code{provide} call, so the subsequent @code{require} call
+does nothing while loading.
+
 @defun provide feature
 This function announces that @var{feature} is now loaded, or being
 loaded, into the current Emacs session.  This means that the facilities
@@ -508,10 +517,10 @@ reclaim memory for other Lisp objects.  To do this, use the function
 
 @deffn Command unload-feature feature
 This command unloads the library that provided feature @var{feature}.
-It undefines all functions and variables defined with @code{defvar},
-@code{defmacro}, @code{defconst}, @code{defsubst} and @code{defalias} by
-that library.  It then restores any autoloads associated with those
-symbols.
+It undefines all functions, macros, and variables defined in that
+library with @code{defconst}, @code{defvar}, @code{defun},
+@code{defmacro}, @code{defsubst} and @code{defalias}.  It then restores
+any autoloads formerly associated with those symbols.
 @end deffn
 
   The @code{unload-feature} function is written in Lisp; its actions are
@@ -528,7 +537,7 @@ composed of these kinds of objects:
 
 @itemize @bullet
 @item
-Symbols, which were defined as functions or variables.
+Symbols that were defined by this library.
 @item
 Lists of the form @code{(require . @var{feature})} indicating
 features that were required.