[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110778: Further small cl.texi changes

[Glenn Morris]

------------------------------------------------------------
revno: 110778
fixes bug: http://debbugs.gnu.org/12788
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Sat 2012-11-03 11:55:29 -0700
message:
  Further small cl.texi changes
  
  * doc/misc/cl.texi (Creating Symbols, Random Numbers):
  De-emphasize internal variables cl--gensym-counter and cl--random-state. 
  
  * etc/NEWS: Related edits.
modified:
  doc/misc/ChangeLog
  doc/misc/cl.texi
  etc/NEWS

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-11-03 17:56:30 +0000
+++ b/doc/misc/ChangeLog        2012-11-03 18:55:29 +0000
@@ -4,6 +4,8 @@
        (List Functions): Remove copy-tree, standard elisp for some time.
        (Efficiency Concerns): Comment out examples that no longer apply.
        (Compiler Optimizations): Rename from "Optimizing Compiler"; reword.
+       (Creating Symbols, Random Numbers): De-emphasize internal
+       variables cl--gensym-counter and cl--random-state.  (Bug#12788)
 
 2012-11-02  Glenn Morris  <address@hidden>
 

=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi  2012-11-03 18:23:38 +0000
+++ b/doc/misc/cl.texi  2012-11-03 18:55:29 +0000
@@ -2874,21 +2874,17 @@
 are used in macro expansions for temporary variables, to ensure that
 their names will not conflict with ``real'' variables in the user's
 code.
address@hidden 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.
address@hidden 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
-this is initialized with 0, but this package initializes it with a
-random (time-dependent) value to avoid trouble when two files that
+(Internally, the variable @code{cl--gensym-counter} holds the counter
+used to generate names.  It is incremented after each use.  In Common
+Lisp this is initialized with 0, but this package initializes it with
+a random time-dependent value to avoid trouble when two files that
 each used @code{cl-gensym} in their compilation are loaded together.
-(Uninterned symbols become interned when the compiler writes them
-out to a file and the Emacs loader loads them, so their names have to
-be treated a bit more carefully than in Common Lisp where uninterned
+Uninterned symbols become interned when the compiler writes them out
+to a file and the Emacs loader loads them, so their names have to be
+treated a bit more carefully than in Common Lisp where uninterned
 symbols remain uninterned after loading.)
address@hidden defvar
address@hidden defun
 
 @defun cl-gentemp &optional x
 This function is like @code{cl-gensym}, except that it produces a new
@@ -3051,22 +3047,14 @@
 The @var{state} argument should be a @code{random-state} object
 that holds the state of the random number generator.  The
 function modifies this state object as a side effect.  If
address@hidden is omitted, it defaults to the variable
address@hidden is omitted, it defaults to the internal variable
 @code{cl--random-state}, which contains a pre-initialized
address@hidden object.
+default @code{random-state} object.  (Since any number of programs in
+the Emacs process may be accessing @code{cl--random-state} in
+interleaved fashion, the sequence generated from this will be
+irreproducible for all intents and purposes.)
 @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.
address@hidden 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
-alternative state object.  Since any number of programs in the
-Emacs process may be accessing @code{cl--random-state} in interleaved
-fashion, the sequence generated from this variable will be
-irreproducible for all intents and purposes.
address@hidden defvar
-
 @defun cl-make-random-state &optional state
 This function creates or copies a @code{random-state} object.
 If @var{state} is omitted or @code{nil}, it returns a new copy of

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-11-03 10:47:03 +0000
+++ b/etc/NEWS  2012-11-03 18:55:29 +0000
@@ -302,6 +302,7 @@
 
 ** CL
 
++++
 *** CL's main entry is now (require 'cl-lib).
 `cl-lib' is like the old `cl' except that it uses the namespace cleanly,
 i.e. all its definitions have the "cl-" prefix (and internal definitions use
@@ -312,8 +313,8 @@
 that had to use `foo*' to avoid conflicts with pre-existing Elisp entities,
 which have not been renamed to `cl-foo*' but just `cl-foo'.
 
-The old `cl' is now deprecated and is just a bunch of aliases that
-provide the old non-prefixed names.
+The old `cl' is now deprecated and is mainly just a bunch of aliases that
+provide the old non-prefixed names.  Some exceptions are listed below.
 
 +++
 *** `cl-flet' is not like `flet' (which is deprecated).