[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110766: * doc/misc/cl.texi: Further general copyedits.

[Glenn Morris]

------------------------------------------------------------
revno: 110766
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Fri 2012-11-02 21:19:40 -0400
message:
  * doc/misc/cl.texi: Further general copyedits.
  Eg, no longer distinguish between "the optimizing compiler" and "the
  non-optimizing compiler" like they were different entities.
modified:
  doc/misc/ChangeLog
  doc/misc/cl.texi

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-11-02 22:29:56 +0000
+++ b/doc/misc/ChangeLog        2012-11-03 01:19:40 +0000
@@ -1,3 +1,7 @@
+2012-11-03  Glenn Morris  <address@hidden>
+
+       * cl.texi: Further general copyedits.
+
 2012-11-02  Glenn Morris  <address@hidden>
 
        * cl.texi (Naming Conventions, Type Predicates, Macros)

=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi  2012-11-02 22:29:56 +0000
+++ b/doc/misc/cl.texi  2012-11-03 01:19:40 +0000
@@ -836,7 +836,7 @@
 * Conditionals::           @code{cl-case}, @code{cl-typecase}.
 * Blocks and Exits::       @code{cl-block}, @code{cl-return}, 
@code{cl-return-from}.
 * Iteration::              @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, 
@code{cl-do-symbols}.
-* Loop Facility::          The Common Lisp @code{cl-loop} macro.
+* Loop Facility::          The Common Lisp @code{loop} macro.
 * Multiple Values::        @code{cl-values}, @code{cl-multiple-value-bind}, 
etc.
 @end menu
 
@@ -1524,7 +1524,7 @@
 similar to @code{catch} and @code{throw}, with lexical scoping.
 This package actually implements @code{cl-block}
 in terms of @code{catch}; however, the lexical scoping allows the
-optimizing byte-compiler to omit the costly @code{catch} step if the
+byte-compiler to omit the costly @code{catch} step if the
 body of the block does not actually @code{cl-return-from} the block.
 
 @defmac cl-block name address@hidden
@@ -1561,7 +1561,7 @@
 Because they are implemented in terms of Emacs Lisp's @code{catch}
 and @code{throw}, blocks have the same overhead as actual
 @code{catch} constructs (roughly two function calls).  However,
-the optimizing byte compiler will optimize away the @code{catch}
+the byte compiler will optimize away the @code{catch}
 if the block does
 not in fact contain any @code{cl-return} or @code{cl-return-from} calls
 that jump to it.  This means that @code{cl-do} loops and @code{cl-defun}
@@ -1726,18 +1726,18 @@
 @section Loop Facility
 
 @noindent
-A common complaint with Lisp's traditional looping constructs is
-that they are either too simple and limited, such as Common Lisp's
address@hidden or Emacs Lisp's @code{while}, or too unreadable and
-obscure, like Common Lisp's @code{do} loop.
+A common complaint with Lisp's traditional looping constructs was
+that they were either too simple and limited, such as @code{dotimes}
+or @code{while}, or too unreadable and obscure, like Common Lisp's
address@hidden loop.
 
-To remedy this, recent versions of Common Lisp have added a new
-construct called the ``Loop Facility'' or address@hidden macro'',
-with an easy-to-use but very powerful and expressive syntax.
+To remedy this, Common Lisp added a construct called the ``Loop
+Facility'' or address@hidden macro'', with an easy-to-use but very
+powerful and expressive syntax.
 
 @menu
-* Loop Basics::           @code{cl-loop} macro, basic clause structure.
-* Loop Examples::         Working examples of @code{cl-loop} macro.
+* Loop Basics::           The @code{cl-loop} macro, basic clause structure.
+* Loop Examples::         Working examples of the @code{cl-loop} macro.
 * For Clauses::           Clauses introduced by @code{for} or @code{as}.
 * Iteration Clauses::     @code{repeat}, @code{while}, @code{thereis}, etc.
 * Accumulation Clauses::  @code{collect}, @code{sum}, @code{maximize}, etc.
@@ -1770,9 +1770,9 @@
 loop:
 
 @example
-(cl-loop @var{name-clause}
-         @address@hidden
-         @address@hidden)
+(loop @var{name-clause}
+      @address@hidden
+      @address@hidden)
 @end example
 
 The @var{name-clause} optionally gives a name to the implicit
@@ -1798,10 +1798,10 @@
 break out of the loop.)
 @end defmac
 
-The following sections give some examples of the Loop Macro in
+The following sections give some examples of the loop macro in
 action, and describe the particular loop clauses in great detail.
 Consult the second edition of Steele for additional discussion
-and examples of the @code{loop} macro.
+and examples.
 
 @node Loop Examples
 @subsection Loop Examples
@@ -2165,8 +2165,9 @@
 based on the value of @code{x} left over from the previous time
 through the loop.
 
-Another feature of the @code{cl-loop} macro is @dfn{destructuring},
-similar in concept to the destructuring provided by @code{defmacro}.
+Another feature of the @code{cl-loop} macro is @emph{destructuring},
+similar in concept to the destructuring provided by @code{defmacro}
+(@pxref{Argument Lists}).
 The @var{var} part of any @code{for} clause can be given as a list
 of variables instead of a single variable.  The values produced
 during loop execution must be lists; the values in the lists are
@@ -2378,7 +2379,7 @@
 (setq funny-numbers '(6 13 -1))
      @result{} (6 13 -1)
 (cl-loop for x below 10
-         if (oddp x)
+         if (cl-oddp x)
            collect x into odds
            and if (memq x funny-numbers) return (cdr it) end
          else
@@ -2444,15 +2445,14 @@
 
 @item return @var{form}
 This clause causes the loop to return immediately.  The following
-Lisp form is evaluated to give the return value of the @code{loop}
+Lisp form is evaluated to give the return value of the loop
 form.  The @code{finally} clauses, if any, are not executed.
 Of course, @code{return} is generally used inside an @code{if} or
 @code{unless}, as its use in a top-level loop clause would mean
 the loop would never get to ``loop'' more than once.
 
 The clause @samp{return @var{form}} is equivalent to
address@hidden FIXME cl-do, cl-return?
address@hidden (return @var{form})} (or @code{return-from} if the loop
address@hidden (cl-return @var{form})} (or @code{cl-return-from} if the loop
 was named).  The @code{return} clause is implemented a bit more
 efficiently, though.
 @end table
@@ -2466,7 +2466,7 @@
 
 This package's @code{cl-loop} macro is compatible with that of Common
 Lisp, except that a few features are not implemented:  @code{loop-finish}
-and data-type specifiers.  Naturally, the @code{for} clauses which
+and data-type specifiers.  Naturally, the @code{for} clauses that
 iterate over keymaps, overlays, intervals, frames, windows, and
 buffers are Emacs-specific extensions.
 
@@ -2519,17 +2519,17 @@
 following macro:
 
 @defmac cl-destructuring-bind arglist expr address@hidden
-This macro expands to code which executes @var{forms}, with
+This macro expands to code that executes @var{forms}, with
 the variables in @var{arglist} bound to the list of values
 returned by @var{expr}.  The @var{arglist} can include all
-the features allowed for @code{defmacro} argument lists,
+the features allowed for @code{cl-defmacro} argument lists,
 including destructuring.  (The @code{&environment} keyword
 is not allowed.)  The macro expansion will signal an error
 if @var{expr} returns a list of the wrong number of arguments
 or with incorrect keyword arguments.
 @end defmac
 
-This package also includes the Common Lisp @code{cl-define-compiler-macro}
+This package also includes the Common Lisp @code{define-compiler-macro}
 facility, which allows you to define compile-time expansions and
 optimizations for your functions.
 
@@ -2592,16 +2592,19 @@
 about the types of data that will be stored in particular variables,
 and about the ways those variables and functions will be used.  This
 package defines versions of all the Common Lisp declaration forms:
address@hidden, @code{cl-locally}, @code{cl-proclaim}, @code{cl-declaim},
-and @code{cl-the}.
address@hidden, @code{locally}, @code{proclaim}, @code{declaim},
+and @code{the}.
 
-Most of the Common Lisp declarations are not currently useful in
-Emacs Lisp, as the byte-code system provides little opportunity
-to benefit from type information, and @code{special} declarations
-are redundant in a fully dynamically-scoped Lisp.  A few
-declarations are meaningful when the optimizing byte
-compiler is being used, however.  Under the earlier non-optimizing
-compiler, these declarations will effectively be ignored.
+Most of the Common Lisp declarations are not currently useful in Emacs
+Lisp.  For example, the byte-code system provides little
+opportunity to benefit from type information.
address@hidden
+and @code{special} declarations are redundant in a fully
+dynamically-scoped Lisp.
address@hidden ignore
+A few declarations are meaningful when byte compiler optimizations
+are enabled, as they are by the default.  Otherwise these
+declarations will effectively be ignored.
 
 @defun cl-proclaim decl-spec
 This function records a ``global'' declaration specified by
@@ -2612,7 +2615,7 @@
 @defmac cl-declaim address@hidden
 This macro is like @code{cl-proclaim}, except that it takes any number
 of @var{decl-spec} arguments, and the arguments are unevaluated and
-unquoted.  The @code{cl-declaim} macro also puts an @code{(cl-eval-when
+unquoted.  The @code{cl-declaim} macro also puts @code{(cl-eval-when
 (compile load eval) @dots{})} around the declarations so that they will
 be registered at compile-time as well as at run-time.  (This is vital,
 since normally the declarations are meant to influence the way the
@@ -2635,9 +2638,9 @@
 
 @defmac cl-the type form
 Type information provided by @code{cl-the} is ignored in this package;
-in other words, @code{(cl-the @var{type} @var{form})} is equivalent
-to @var{form}.  Future versions of the optimizing byte-compiler may
-make use of this information.
+in other words, @code{(cl-the @var{type} @var{form})} is equivalent to
address@hidden  Future byte-compiler optimizations may make use of this
+information.
 
 For example, @code{mapcar} can map over both lists and arrays.  It is
 hard for the compiler to expand @code{mapcar} into an in-line loop
@@ -2658,35 +2661,31 @@
 
 @table @code
 @item special
address@hidden FIXME ?
 Since all variables in Emacs Lisp are ``special'' (in the Common
 Lisp sense), @code{special} declarations are only advisory.  They
-simply tell the optimizing byte compiler that the specified
+simply tell the byte compiler that the specified
 variables are intentionally being referred to without being
 bound in the body of the function.  The compiler normally emits
 warnings for such references, since they could be typographical
 errors for references to local variables.
 
 The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
-equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
-optimizing compiler, or to nothing at all in older compilers (which
-do not warn for non-local references).
+equivalent to @code{(defvar @var{var1}) (defvar @var{var2})}.
 
 In top-level contexts, it is generally better to write
 @code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
-since @code{defvar} makes your intentions clearer.  But the older
-byte compilers can not handle @code{defvar}s appearing inside of
-functions, while @code{(cl-declare (special @var{var}))} takes care
-to work correctly with all compilers.
+since @code{defvar} makes your intentions clearer.
 
 @item inline
 The @code{inline} @var{decl-spec} lists one or more functions
 whose bodies should be expanded ``in-line'' into calling functions
 whenever the compiler is able to arrange for it.  For example,
-the Common Lisp function @code{cadr} is declared @code{inline}
-by this package so that the form @code{(cadr @var{x})} will
-expand directly into @code{(car (cdr @var{x}))} when it is called
-in user functions, for a savings of one (relatively expensive)
-function call.
+the function @code{cl-acons} is declared @code{inline}
+by this package so that the form @code{(cl-acons @var{key} @var{value}
address@hidden)} will
+expand directly into @code{(cons (cons @var{key} @var{value}) @var{alist})}
+when it is called in user functions, so as to save function calls.
 
 The following declarations are all equivalent.  Note that the
 @code{defsubst} form is a convenient way to define a function
@@ -2705,7 +2704,7 @@
 but it is impolite to use it to request inlining of an external
 function.
 
-In Common Lisp, it is possible to use @code{(cl-declare (inline @dots{}))}
+In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
 before a particular call to a function to cause just that call to
 be inlined; the current byte compilers provide no way to implement
 this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
@@ -2718,8 +2717,7 @@
 
 @item optimize
 This declaration controls how much optimization is performed by
-the compiler.  Naturally, it is ignored by the earlier non-optimizing
-compilers.
+the compiler.
 
 The word @code{optimize} is followed by any number of lists like
 @code{(speed 3)} or @code{(safety 2)}.  Common Lisp defines several
@@ -2728,8 +2726,7 @@
 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important''.
 The default level for both qualities is 1.
 
-In this package, with the optimizing compiler, the
address@hidden quality is tied to the @code{byte-optimize}
+In this package, the @code{speed} quality is tied to the @code{byte-optimize}
 flag, which is set to @code{nil} for @code{(speed 0)} and to
 @code{t} for higher settings; and the @code{safety} quality is
 tied to the @code{byte-compile-delete-errors} flag, which is
@@ -2748,22 +2745,22 @@
 
 The @code{optimize} declaration is normally used in a top-level
 @code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
-it to be used with @code{cl-declare} to set the level of optimization
+it to be used with @code{declare} to set the level of optimization
 locally for a given form, but this will not work correctly with the
-current version of the optimizing compiler.  (The @code{cl-declare}
+current byte-compiler.  (The @code{cl-declare}
 will set the new optimization level, but that level will not
 automatically be unset after the enclosing form is done.)
 
 @item warn
 This declaration controls what sorts of warnings are generated
-by the byte compiler.  Again, only the optimizing compiler
-generates warnings.  The word @code{warn} is followed by any
+by the byte compiler.  The word @code{warn} is followed by any
 number of ``warning qualities'', similar in form to optimization
 qualities.  The currently supported warning types are
 @code{redefine}, @code{callargs}, @code{unresolved}, and
 @code{free-vars}; in the current system, a value of 0 will
 disable these warnings and any higher value will enable them.
-See the documentation for the optimizing byte compiler for details.
+See the documentation of the variable @code{byte-compile-warnings}
+for more details.
 @end table
 
 @node Symbols
@@ -2878,6 +2875,8 @@
 code.
 @end defun
 
address@hidden FIXME texinfo renders this as as cl-gensym-counter in info.
address@hidden It looks fine in the index, and in the pdf version.
 @defvar cl--gensym-counter
 This variable holds the counter used to generate @code{cl-gensym} names.
 It is incremented after each use by @code{cl-gensym}.  In Common Lisp
@@ -2908,13 +2907,13 @@
 
 @noindent
 This section defines a few simple Common Lisp operations on numbers
-which were left out of Emacs Lisp.
+that were left out of Emacs Lisp.
 
 @menu
 * Predicates on Numbers::       @code{cl-plusp}, @code{cl-oddp}, etc.
-* Numerical Functions::         @code{abs}, @code{cl-floor}, etc.
+* Numerical Functions::         @code{cl-floor}, @code{cl-ceiling}, etc.
 * Random Numbers::              @code{cl-random}, @code{cl-make-random-state}.
-* Implementation Parameters::   @code{cl-most-positive-float}.
+* Implementation Parameters::   @code{cl-most-positive-float}, etc.
 @end menu
 
 @node Predicates on Numbers
@@ -3041,6 +3040,7 @@
 This package also provides an implementation of the Common Lisp
 random number generator.  It uses its own additive-congruential
 algorithm, which is much more likely to give statistically clean
address@hidden FIXME?  Still true?
 random numbers than the simple generators supplied by many
 operating systems.
 
@@ -3048,13 +3048,15 @@
 This function returns a random nonnegative number less than
 @var{number}, and of the same type (either integer or floating-point).
 The @var{state} argument should be a @code{random-state} object
-which holds the state of the random number generator.  The
+that holds the state of the random number generator.  The
 function modifies this state object as a side effect.  If
 @var{state} is omitted, it defaults to the variable
 @code{cl--random-state}, which contains a pre-initialized
 @code{random-state} object.
 @end defun
 
address@hidden FIXME texinfo renders this as cl-random-state in info.
address@hidden It looks fine in the index, and in the pdf version.
 @defvar cl--random-state
 This variable contains the system ``default'' @code{random-state}
 object, used for calls to @code{cl-random} that do not specify an
@@ -3099,10 +3101,10 @@
 @section Implementation Parameters
 
 @noindent
-This package defines several useful constants having to with numbers.
+This package defines several useful constants having to do with
+floating-point numbers.
 
-The following parameters have to do with floating-point numbers.
-This package determines their values by exercising the computer's
+It determines their values by exercising the computer's
 floating-point arithmetic in various ways.  Because this operation
 might be slow, the code for initializing them is kept in a separate
 function that must be called before the parameters can be used.
@@ -3110,12 +3112,13 @@
 @defun cl-float-limits
 This function makes sure that the Common Lisp floating-point parameters
 like @code{cl-most-positive-float} have been initialized.  Until it is
-called, these parameters will be @code{nil}.  If this version of Emacs
-does not support floats, the parameters will remain @code{nil}.  If the
-parameters have already been initialized, the function returns
+called, these parameters will be @code{nil}.
address@hidden If this version of Emacs does not support floats, the parameters 
will
address@hidden remain @code{nil}.
+If the parameters have already been initialized, the function returns
 immediately.
 
-The algorithm makes assumptions that will be valid for most modern
+The algorithm makes assumptions that will be valid for almost all
 machines, but will fail if the machine's arithmetic is extremely
 unusual, e.g., decimal.
 @end defun
@@ -3135,7 +3138,7 @@
 @end defvar
 
 @defvar cl-most-negative-float
-This constant equals the most-negative value a Lisp float can hold.
+This constant equals the most negative value a Lisp float can hold.
 (It is assumed to be equal to @code{(- cl-most-positive-float)}.)
 @end defvar
 
@@ -4482,7 +4485,7 @@
 code which can be improved by optimization.  In particular,
 @code{cl-block}s (whether explicit or implicit in constructs like
 @code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
-optimizing compiler removes @code{cl-block}s which are not actually
+byte-compiler removes @code{cl-block}s which are not actually
 referenced by @code{cl-return} or @code{cl-return-from} inside the block.
 
 @node Common Lisp Compatibility