Document read-char-choice.

* doc/lispref/commands.texi (Reading One Event):
* doc/lispref/help.texi (Help Functions): Document read-char-choice.
* etc/NEWS: Markup.

4 files changed, 21 insertions, 5 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 5765b151b41..f95b53bc45f 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,8 @@
 2012-02-02  Glenn Morris  <rgm@gnu.org>
 
+        * commands.texi (Reading One Event):
+        * help.texi (Help Functions): Document read-char-choice.
+
         * hooks.texi (Standard Hooks):
         * modes.texi (Keymaps and Minor Modes):
         * text.texi (Commands for Insertion): Document post-self-insert-hook.
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 3d2b813b592..aff7a0c5f27 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2472,6 +2472,17 @@ The argument @var{prompt} is either a string to be displayed in the
 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
 @end defun
 
+@defun read-char-choice prompt chars &optional inhibit-quit
+This function uses @code{read-key} to read and return a single
+character.  It ignores any input that is not a member of @var{chars},
+a list of accepted characters.  Optionally, it will also ignore
+keyboard-quit events while it is waiting for valid input.  If you bind
+@code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value
+while calling @code{read-char-choice}, then pressing @code{help-char}
+causes it to evaluate @code{help-form} and display the result.  It
+then continues to wait for a valid input character, or keyboard-quit.
+@end defun
+
 @node Event Mod
 @subsection Modifying and Translating Input Events
 
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 678ea83465f..f6556639e98 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -582,11 +582,12 @@ If this variable is non-@code{nil}, its value is a form to evaluate
 whenever the character @code{help-char} is read.  If evaluating the form
 produces a string, that string is displayed.
 
-A command that calls @code{read-event} or @code{read-char} probably
-should bind @code{help-form} to a non-@code{nil} expression while it
-does input.  (The time when you should not do this is when @kbd{C-h} has
-some other meaning.)  Evaluating this expression should result in a
-string that explains what the input is for and how to enter it properly.
+A command that calls @code{read-event}, @code{read-char-choice}, or
+@code{read-char} probably should bind @code{help-form} to a
+non-@code{nil} expression while it does input.  (The time when you
+should not do this is when @kbd{C-h} has some other meaning.)
+Evaluating this expression should result in a string that explains
+what the input is for and how to enter it properly.
 
 Entry to the minibuffer binds this variable to the value of
 @code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
diff --git a/etc/NEWS b/etc/NEWS
index 0299572ca58..ec508771abc 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1253,6 +1253,7 @@ jumping all the way to the top-level.
 ** The function format-time-string now supports the %N directive, for
 higher-resolution time stamps.
 
++++
 ** New function `read-char-choice' reads a restricted set of characters,
 discarding any inputs not inside the set.