[nongnu] elpa/with-simulated-input 703fc3c9ec 118/134: Update the docstring for "with-simulated-input"

[ELPA Syncer]

branch: elpa/with-simulated-input
commit 703fc3c9ec73792576203be32bcc030e54b31d59
Author: Ryan C. Thompson <rct@thompsonclan.org>
Commit: Ryan C. Thompson <rct@thompsonclan.org>

    Update the docstring for "with-simulated-input"
    
    It now reflects the currently supported, non-deprecated uses only.
---
 with-simulated-input.el | 45 ++++++++++++++++++++++++++++++++++-----------
 1 file changed, 34 insertions(+), 11 deletions(-)

diff --git a/with-simulated-input.el b/with-simulated-input.el
index 1f849157bf..25e0bf0c99 100644
--- a/with-simulated-input.el
+++ b/with-simulated-input.el
@@ -250,28 +250,51 @@ keys after initiating evaluation of BODY.
 KEYS should be a string representing a sequence of key presses,
 in the format understood by `kbd'. In the most common case of
 typing in some text and pressing RET, KEYS would be something
-like `\"hello RET\"'. Note that spaced must be indicated
+like `\"hello RET\"'. Note that spaces must be indicated
 explicitly using `SPC', e.g. `\"hello SPC world RET\"'.
 
-KEYS can also be a list. In this case, each element should either
-be a key sequence as described above or an arbitrary Lisp form
-that will be evaluated at that point in the input sequence. For
-example, `\"hello RET\"' could also be written as:
+KEYS can also be a list of strings, which will be used as
+consecutive inputs. (This list should not be quoted, since
+`with-simulated-input' is a macro.) Elements of the list can also
+be function calls, which will be evaluated at that point in the
+input sequence. This can be used as an alternative to writing out
+a full key sequence. For example, `\"hello SPC world RET\"' could
+also be written as:
 
-    `((insert \"hello\") \"RET\")'
+    `((insert \"hello world\") \"RET\")'
+
+It can also be used to implement more complex logic, such as
+conditionally inserting a string. Note that the return value of
+any function call in KEYS is ignored, so the function should
+actually perform some kind of action, or else it will have no
+effect.
+
+Lastly, KEYS can also be the name of a variable whose value is a
+string. The variable's value will be used as described above.
 
 If BODY tries to read more input events than KEYS provides, an
-error is signalled. This is to ensure that BODY will never block
-waiting for input, since this macro is intended for
+error is signaled. This is to ensure that BODY will never get
+stuck waiting for input, since this macro is intended for
 non-interactive use. If BODY does not consume all the input
 events in KEYS, the remaining input events in KEYS are discarded,
-and any remaining Lisp forms in KEYS are never evaluated.
+and any remaining function calls in KEYS are never evaluated. In
+particular, if KEYS is nil, then an error will be signaled if
+BODY attempts to read any input, and if BODY is nil, a constant
+expression, or an expression that does not read any input, then
+KEYS will be ignored completely.
 
 Any errors generated by any means during the evaluation of BODY
-are propagated normally.
+or the evaluation of function calls in KEYS are propagated
+normally.
 
 The return value is the last form in BODY, as if it was wrapped
-in `progn'."
+in `progn'.
+
+(Note: KEYS supports some additional semantics for
+backward-compatibilty reasons. These semantics are considered
+deprecated and are left intentionally undocumented. They should
+not be used in newly written code, since they will stop working
+in a future release.)"
   (declare
    (indent 1)
    (debug ([&or ("quote" (&rest &or stringp form)) ; quoted list of 
string-or-form