[Emacs-diffs] /srv/bzr/emacs/trunk r107058: Document read-char-choice.

[Glenn Morris]

------------------------------------------------------------
revno: 107058
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2012-02-01 23:06:37 -0800
message:
  Document read-char-choice.
  
  * doc/lispref/commands.texi (Reading One Event):
  * doc/lispref/help.texi (Help Functions): Document read-char-choice.
  * etc/NEWS: Markup.
modified:
  doc/lispref/ChangeLog
  doc/lispref/commands.texi
  doc/lispref/help.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-02 04:37:05 +0000
+++ b/doc/lispref/ChangeLog     2012-02-02 07:06:37 +0000
@@ -1,5 +1,8 @@
 2012-02-02  Glenn Morris  <address@hidden>
 
+       * 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.

=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2012-01-27 08:35:51 +0000
+++ b/doc/lispref/commands.texi 2012-02-02 07:06:37 +0000
@@ -2472,6 +2472,17 @@
 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
 @end defun
 
address@hidden 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
address@hidden (@pxref{Help Functions}) to a address@hidden 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.
address@hidden defun
+
 @node Event Mod
 @subsection Modifying and Translating Input Events
 

=== modified file 'doc/lispref/help.texi'
--- a/doc/lispref/help.texi     2012-01-19 07:21:25 +0000
+++ b/doc/lispref/help.texi     2012-02-02 07:06:37 +0000
@@ -582,11 +582,12 @@
 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 address@hidden 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
address@hidden probably should bind @code{help-form} to a
address@hidden 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}).

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-02-02 04:37:05 +0000
+++ b/etc/NEWS  2012-02-02 07:06:37 +0000
@@ -1253,6 +1253,7 @@
 ** 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.