docs: Replace turtles-send-keys etc. with :keys etc. in the docs.

Author: szermatt

docs/source/reference.rst

@@ -271,64 +271,42 @@ Minibuffer
     - calls to :code:`turtles-with-grab-buffer` to test the content of
       the minibuffer or any other window.
 
-    - keys passed to the minibuffer, with :code:`turtles-input-keys`
+    - keys passed to the minibuffer, with :keys, see below.
 
     - commands that manipulate the minibuffer, either called directly
-      or using :code:`turtles-input-command`
+      or using :command, see below.
 
     At the end of BODY, the minibuffer is closed, if needed, and
     control returns to READ, which checks the result of running BODY.
 
-    See the :ref:`tut_minibuffer` and :ref:`tut_isearch` sections of
-    the tutorial for usage examples.
-
-.. _input:
-
-Input Events
-------------
-
-.. index::
-    pair: function; turtles-input-keys
-    pair: function; turtles-input-events
-    pair: function; turtles-input-command
+    Special forms are available within BODY to simulate the user inputing
+    events using the command loop. In contrast to :code:`execute-kbd-macro`,
+    :code:`ert-simulate-commands` and :code:`ert-simulate-keys`, these
+    function use the real event loop, triggered by real, external events
+    (terminal keys). This isn't as simulation.
 
-The following functions send events to the Emacs instance to be
-processed using the normal event loop.
+    :keys keys
+        This expression provides KEYS as user input to the minibuffer.
 
-In contrast to :code:`execute-kbd-macro`,
-:code:`ert-simulate-commands` and :code:`ert-simulate-keys`, these
-function use the real event loop, triggered by real, external events
-(terminal keys). This isn't as simulation. In most cases, the
-difference doesn't matter, of course.
+        KEYS is in the same format as passed to :code:`kbd`.
 
-These functions all use :code:`recursive-edit` to make it possible to
-handle events directly from ERT tests.
+    :events events
+        This expression provides a vector of events as the user input
+        to the minibuffer.
 
-(turtles-input-keys keys) : function
-    This function provides KEYS as user input to the current instance.
+        This is more general than the previous function as the events
+        can be any kind of UI events.
 
-    KEYS is in the same format as passed to :code:`kbd`.
+    :command command
+        This expression runs the given interactive command in the event
+        loop, triggered by a key stroke.
 
-(turtles-input-events events) : function
-    This function provides a vector of events as the user input to the
-    current instance.
+    :command-with-keybinding keybinding command
+        This expression works as above, but makes sure that the command
+        will find in :code:`(this-command-keys)`, if it asks.
 
-    This is more general than the previous function as the events can
-    be any kind of UI events.
-
-(turtles-input-command command &optional keybinding) : function
-    This function runs the given interactive command in the event
-    loop, triggered by a key stroke.
-
-    If provided, keybinding is what what the command will find in
-    :code:`(this-command-keys)`, if it asks.
-
-    This is implemented using a transient map, so the key binding is
-    only available for one call.
-
-    Note that in the majority of cases, calling the command directly,
-    outside of the event loop, works just fine in tests and is more
-    convenient.
+    See the :ref:`tut_minibuffer` and :ref:`tut_isearch` sections of
+    the tutorial for usage examples.
 
 .. _instances:
 

docs/source/tutorial.rst

@@ -178,11 +178,11 @@ This second example illustrates the use of
           (turtles-with-grab-buffer (:name "initial prompt" :point "<>")
             (should (equal "Choose: <>" (buffer-string))))
 
-          (turtles-input-keys "Ch TAB")
+          :keys "Ch TAB"
           (turtles-with-grab-buffer (:name "completion" :point "<>")
             (should (equal "Choose: Choice <>" (buffer-string))))
 
-          (turtles-input-keys "B")))))
+          :keys "B"))))
 
 
 :code:`turtles-with-minibuffer` takes as argument two separate sections, as shown below:
@@ -226,15 +226,16 @@ that manually; it's just convenient to see the content and the
 position of the point in the same string.
 
 This test interacts with :code:`completing-read` by simulating the
-user typing some text and pressing :kbd:`TAB`. It uses
-:ref:`turtles-input-keys <input>` for that, which simulates the user
-typing some keys.
+user typing some text and pressing :kbd:`TAB`. It uses :ref:`:keys
+<minibuffer>` for that, which instructs the macro
+:code:`turtles-with-minibuffer` to simulates the user typing some
+keys.
 
 The test could have called the command :kbd:`TAB` corresponds to directly:
 
 .. code-block:: elisp
 
-        (turtles-input-keys "Ch")
+        :keys "Ch"
         (minibuffer-complete)
         (turtles-with-grab-buffer (:name "completion" :point "<>")
           (should (equal "Choose: Choice <>" (buffer-string))))
@@ -244,13 +245,13 @@ clearer than going through key bindings, and in most cases, it works well.
 
 Some commands that rely on the specific environment provided by the
 command loop won't work if called directly.
-:ref:`turtles-input-command <input>` can help with such commands,
-though it's just overkill here:
+:ref:`:command <minibuffer>` can help with such commands,
+though it might be considered overkill here:
 
 .. code-block:: elisp
 
-        (turtles-input-keys "Ch")
-        (turtles-input-command #'minibuffer-complete)
+        :keys "Ch"
+        :command #'minibuffer-complete
         (turtles-with-grab-buffer (:name "completion" :point "<>")
           (should (equal "Choose: Choice <>" (buffer-string))))
 
@@ -277,16 +278,16 @@ isearch still works with :code:`turtles-with-minibuffer`.
         (goto-char (point-min))
 
         (turtles-with-minibuffer
-            (isearch-forward nil 'no-recursive-edit)
+            (isearch-forward)
 
-          (turtles-input-keys "baa")
+          :keys "baa"
           (turtles-with-grab-buffer (:minibuffer t)
             (should (equal "I-search: baa" (buffer-string))))
           (turtles-with-grab-buffer (:buf testbuf :name "match 1" :faces '((isearch "[]")))
             (should (equal "[Baa], baa, black sheep, have you any wool?"
                            (buffer-string))))
 
-          (turtles-input-keys "\C-s")
+          :keys "\C-s"
           (turtles-with-grab-buffer (:buf testbuf :name "match 2" :faces '((isearch "[]")))
             (should (equal "Baa, [baa], black sheep, have you any wool?"
                            (buffer-string))))