DOC: describe the Top-level Menu and signaling in the manual

* README.org:
- The Top-level Menu buffer: new section.
- Sending signals to running top-levels: new section.

diff --git a/README.org b/README.org
index 9b2ea1d4bda353700c49827543b11bab434b3b56..aa12a4a551a52d4fbc6ea8bcc468b556d7e3b4ad 100644 (file)
--- a/README.org
+++ b/README.org
@@ -766,6 +766,82 @@ again.  This will change the name of the original top-level buffer to
 something like =*sweeprolog-top-level*<2>= and allow the new top-level to
 claim the buffer name =*sweeprolog-top-level*=.
 
+** The Top-level Menu buffer
+:PROPERTIES:
+:DESCRIPTION: A special buffer for operating on active top-levels
+:CUSTOM_ID: top-level-menu
+:END:
+
+#+CINDEX: Top-level Menu
+=sweep= provides a convenient interface for listing the active Prolog
+top-levels and operating on them, called the Top-level Menu buffer.
+This buffer shows the list of active =sweep= top-level buffers in a
+table that includes information and statistics for each top-level.
+
+#+FINDEX: sweeprolog-list-top-levels
+To open the Top-level Menu buffer, use the command ~M-x
+sweeprolog-list-top-levels~.  By default, the buffer is will be named
+=*sweep Top-levels*=.
+
+The Top-level Menu buffer uses a special major mode named
+~sweeprolog-top-level-menu-mode~.  This mode provides several commands
+that operate on the top-level corresponding to the table row at point.
+The available commands are:
+
+- ~RET~ (~sweeprolog-top-level-menu-go-to~) ::
+
+  #+FINDEX: sweeprolog-top-level-menu-go-to
+  Open the specified top-level buffer.
+
+- ~k~ (~sweeprolog-top-level-menu-kill~) ::
+
+  #+FINDEX: sweeprolog-top-level-menu-kill
+  Kill the specified top-level buffer.
+
+- ~s~ (~sweeprolog-top-level-menu-signal~) ::
+
+  #+FINDEX: sweeprolog-top-level-menu-signal
+  Signal the specified top-level buffer (see [[*Sending signals to running top-levels][Sending signals to
+  running top-levels]]).
+
+- ~t~ (~sweeprolog-top-level-menu-new~) ::
+
+  #+FINDEX: sweeprolog-top-level-menu-new
+  Create a new top-level buffer.
+
+- ~g~ (~revert-buffer~) ::
+
+  Update the Top-level Menu contents.
+
+** Sending signals to running top-levels
+:PROPERTIES:
+:CUSTOM_ID: top-level-signals
+:END:
+
+#+CINDEX: signaling Prolog threads
+#+FINDEX: sweeprolog-top-level-signal
+When executing long running Prolog queries in the top-level, there may
+arise a need to interrupt the query, either to inspect the state of
+the top-level or to free it for running other queries.  To signal a
+=sweep= top-level that it should stop executing the current query and do
+something else instead, use the command ~M-x
+sweeprolog-top-level-signal~.  This command prompts for an active =sweep=
+top-level buffer followed by a Prolog goal, and interrupts the
+top-level causing it to run the specified goal.
+
+#+FINDEX: sweeprolog-top-level-signal-current
+In ~sweeprolog-top-level-mode~ buffers, the command
+~sweeprolog-top-level-signal-current~ is available for signaling the
+current top-level.  It is bound by default to ~C-c C-c~.
+
+It is also possible to signal top-levels from the =sweep= Top-level Menu
+buffer with the command ~sweeprolog-top-level-menu-signal~ with point at
+the entry corresponding to the wanted top-level (see [[The Top-level
+Menu buffer]]).
+
+For more information about interrupting threads in SWI-Prolog, see
+[[https://www.swi-prolog.org/pldoc/man?section=thread-signal][Signaling threads in the SWI-Prolog manual]].
+
 ** Top-level history
 :PROPERTIES:
 :CUSTOM_ID: top-level-history

diff --git a/sweeprolog.el b/sweeprolog.el
index eece22b15e0be6cb854b55951c9cbe223b80aa0a..d7c15c5fc784cbaea3e9bd865d82bbbe5a4679e1 100644 (file)
--- a/sweeprolog.el
+++ b/sweeprolog.el
@@ -1577,9 +1577,7 @@ Interactively, a prefix arg means to prompt for BUFFER."
                         (let ((bb (or (and (consp b) (car b)) b)))
                           (with-current-buffer bb
                             (and (derived-mode-p 'sweeprolog-top-level-mode)
-                                 sweeprolog-top-level-thread-id)))
-                        (eq 'sweeprolog-top-level-mode
-                            (buffer-local-value 'major-mode b))))
+                                 sweeprolog-top-level-thread-id)))))
          (read-string "Signal goal: ?- ")))
   (sweeprolog-signal-thread (buffer-local-value 'sweeprolog-top-level-thread-id
                                                 (get-buffer buffer))
@@ -1752,7 +1750,6 @@ Interactively, a prefix arg means to prompt for BUFFER."
     [ "Load Prolog buffer"     sweeprolog-load-buffer     t ]
     [ "Find Prolog module"     sweeprolog-find-module     t ]
     [ "Find Prolog predicate"  sweeprolog-find-predicate  t ]
-    [ "Open top-level"         sweeprolog-top-level       t ]
     [ "Insert module template"
       auto-insert
       (eq major-mode 'sweeprolog-mode) ]
@@ -1761,8 +1758,17 @@ Interactively, a prefix arg means to prompt for BUFFER."
       (and (eq major-mode 'sweeprolog-mode)
            (sweeprolog-definition-at-point)) ]
     "--"
-    [ "Reset sweep"            sweeprolog-restart         t ]
+    [ "Open top-level"         sweeprolog-top-level       t ]
+    [ "Signal top-level"
+      sweeprolog-top-level-signal
+      (seq-filter (lambda (b)
+                    (with-current-buffer b
+                      (and (derived-mode-p 'sweeprolog-top-level-mode)
+                           sweeprolog-top-level-thread-id)))
+                  (buffer-list)) ]
     [ "Open Top-level Menu"    sweeprolog-list-top-levels t ]
+    "--"
+    [ "Reset sweep"            sweeprolog-restart         t ]
     [ "View sweep messages"    sweeprolog-view-messages   t ]))
 
 (defun sweeprolog-token-boundaries (&optional pos)