3 files changed, 18 insertions, 27 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 6bd601bef5d..62308037fec 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -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  <rgm@gnu.org>
 
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 1b1a3f9836f..e182c2600f9 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -2874,21 +2874,17 @@ string is used as a prefix instead of @samp{G}.  Uninterned symbols
 are used in macro expansions for temporary variables, to ensure that
 their names will not conflict with ``real'' variables in the user's
 code.
-@end defun
 
-@c FIXME texinfo renders this as as cl-gensym-counter in info.
-@c 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
-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.)
-@end defvar
+@end defun
 
 @defun cl-gentemp &optional x
 This function is like @code{cl-gensym}, except that it produces a new
@@ -3051,22 +3047,14 @@ This function returns a random nonnegative number less than
 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
-@var{state} is omitted, it defaults to the variable
+@var{state} is omitted, it defaults to the internal variable
 @code{cl--random-state}, which contains a pre-initialized
-@code{random-state} 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
 
-@c FIXME texinfo renders this as cl-random-state in info.
-@c 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
-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.
-@end 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
diff --git a/etc/NEWS b/etc/NEWS
index 9ece829217f..4f8b56cb363 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -302,6 +302,7 @@ Customize `cal-html-holidays' to change this.
 
 ** 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 @@ under the name `cl-foo' instead, with the exceptions of the few definitions
 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).