* cl.texi (For Clauses): @items for hash-values and key-bindings

to make them more visible when skimming.  Add examples of `using'
clause to them, examples being clearer than a description in
words.

Fixes: debbugs:6599

2 files changed, 29 insertions, 11 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 583bdb411bb..474b7a0efab 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,10 @@
+2011-07-03  Kevin Ryde  <user42@zip.com.au>
+
+        * cl.texi (For Clauses): @items for hash-values and key-bindings
+        to make them more visible when skimming.  Add examples of `using'
+        clause to them, examples being clearer than a description in
+        words (bug#6599).
+
 2011-07-01  Alan Mackenzie  <acm@muc.de>
 
         * cc-mode.texi (Guessing the Style): New page.
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index afe7c94f447..ab54b99138a 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -2449,22 +2449,33 @@ one of these types of clauses with other clauses like @code{for ... to}
 or @code{while}.
 
 @item for @var{var} being the hash-keys of @var{hash-table}
-This clause iterates over the entries in @var{hash-table}.  For each
-hash table entry, @var{var} is bound to the entry's key.  If you write
-@samp{the hash-values} instead, @var{var} is bound to the values
-of the entries.  The clause may be followed by the additional
-term @samp{using (hash-values @var{var2})} (where @code{hash-values}
-is the opposite word of the word following @code{the}) to cause
-@var{var} and @var{var2} to be bound to the two parts of each
-hash table entry.
+@itemx for @var{var} being the hash-values of @var{hash-table}
+This clause iterates over the entries in @var{hash-table} with
+@var{var} bound to each key, or value.  A @samp{using} clause can bind
+a second variable to the opposite part.
+
+@example
+(loop for k being the hash-keys of h
+            using (hash-values v)
+      do
+      (message "key %S -> value %S" k v))
+@end example
 
 @item for @var{var} being the key-codes of @var{keymap}
+@itemx for @var{var} being the key-bindings of @var{keymap}
 This clause iterates over the entries in @var{keymap}.
 The iteration does not enter nested keymaps but does enter inherited
 (parent) keymaps.
-You can use @samp{the key-bindings} to access the commands bound to
-the keys rather than the key codes, and you can add a @code{using}
-clause to access both the codes and the bindings together.
+A @code{using} clause can access both the codes and the bindings
+together.
+
+@example
+(loop for c being the key-codes of (current-local-map)
+            using (key-bindings b)
+      do
+      (message "key %S -> binding %S" c b))
+@end example
+
 
 @item for @var{var} being the key-seqs of @var{keymap}
 This clause iterates over all key sequences defined by @var{keymap}