From 031c07ac939348e3ec9403f3b2611e8e31278422 Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Tue, 6 Sep 2022 21:46:42 +0300
Subject: [PATCH] DOC: document the Prolog messages buffer

---
 README.org | 47 +++++++++++++++++++++++++++++++++++------------
 sweep.el   | 25 +++++++++++++++++++------
 2 files changed, 54 insertions(+), 18 deletions(-)

diff --git a/README.org b/README.org
index e9d9cea..7d98fd9 100644
--- a/README.org
+++ b/README.org
@@ -409,17 +409,6 @@ For example, typing =C-x C-f library(pldoc/doc_man)= will open the
 source of the =pldoc_man= module from the Prolog library, and likewise
 =C-x C-f pack(.)= will open the Prolog packages directory.
 
-* Installing Prolog packages
-:PROPERTIES:
-:CUSTOM_ID: prolog-packages
-:END:
-
-#+FINDEX: sweep-pack-install
-The command =M-x sweep-pack-install= can be used to install
-or upgrade a SWI-Prolog =pack=. When selecting a =pack= to install, the
-completion candidates are annotated with description and the version
-of each package.
-
 * Quick access to =sweep= commands
 :PROPERTIES:
 :CUSTOM_ID: quick-command-access
@@ -436,7 +425,41 @@ to a prefix key, e.g. =C-c p=, use:
 #+end_src
 
 As an example, with the above binding the =sweep= top-level can be
-access from anywhere with =C-c p t=.
+accessed from anywhere with =C-c p t=, which invokes the command
+=sweep-top-level=.
+
+* Examining Prolog messages
+
+#+CINDEX: messages
+#+VINDEX: sweep-messages-buffer-name
+Messages emitted by the embedded Prolog are redirected by =sweep= to a
+dedicated Emacs buffer.  By default, the =sweep= messages buffer is
+named =*sweep Messages*=.  To instruct =sweep= to use another buffer name
+instead, type =M-x customize-option RET sweep-messages-buffer-name RET=
+and set the option to a suitable value.
+
+The =sweep= messages buffer uses the minor mode =compilation-minor-mode=,
+which allows for jumping to source locations indicated in errors and
+warning directly from the corresponding message in the =sweep= messages
+buffer.  For more information about the features enabled by
+=compilation-minor-mode=, see [[info:emacs#Compilation Mode][Compilation Mode in the Emacs manual]].
+
+#+FINDEX: sweep-view-messages
+=sweep= includes the command =sweep-view-messages= for quickly switching
+to the =sweep= messages buffer.  This command is bound by default in
+=sweep-prefix-map= to the =e= key (see [[Quick access to =sweep= commands]]).
+
+* Installing Prolog packages
+:PROPERTIES:
+:CUSTOM_ID: prolog-packages
+:END:
+
+#+FINDEX: sweep-pack-install
+The command =M-x sweep-pack-install= can be used to install
+or upgrade a SWI-Prolog =pack=. When selecting a =pack= to install, the
+completion candidates are annotated with description and the version
+of each package.
+
 
 #+html: <!--
 
diff --git a/sweep.el b/sweep.el
index 1fa56f7..0c54a88 100644
--- a/sweep.el
+++ b/sweep.el
@@ -32,6 +32,12 @@
   "SWI-Prolog Embedded in Emacs."
   :group 'prolog)
 
+(defcustom sweep-messages-buffer-name "*sweep Messages*"
+  "The name of the buffer to use for logging Prolog messages."
+  :package-version '((sweep . "0.1.1"))
+  :type 'string
+  :group 'sweep)
+
 (defcustom sweep-read-module-prompt "Module: "
   "Prompt used for reading a Prolog module name from the minibuffer."
   :package-version '((sweep . "0.1.0"))
@@ -107,13 +113,19 @@
           (require 'sweep-module))
       (error "Sweep will not work until `sweep-module' is compiled!"))))
 
-
-(defvar sweep-messages-buffer nil)
+(defun sweep-view-messages ()
+  "View the log of recent Prolog messages."
+  (interactive)
+  (with-current-buffer (get-buffer-create sweep-messages-buffer-name)
+    (goto-char (point-max))
+    (let ((win (display-buffer (current-buffer))))
+      (set-window-point win (point))
+      win)))
 
 (defun sweep-setup-message-hook ()
-  (with-current-buffer
-      (setq sweep-messages-buffer (get-buffer-create "*sweep-messages*"))
-    (compilation-minor-mode))
+  (with-current-buffer (get-buffer-create sweep-messages-buffer-name)
+    (setq-local window-point-insertion-type t)
+    (compilation-minor-mode 1))
   (sweep-open-query "user"
                     "sweep"
                     "sweep_setup_message_hook"
@@ -123,7 +135,7 @@
     sol))
 
 (defun sweep-message (message)
-  (with-current-buffer sweep-messages-buffer
+  (with-current-buffer (get-buffer-create sweep-messages-buffer-name)
     (save-excursion
       (goto-char (point-max))
       (insert message)
@@ -807,6 +819,7 @@ Interactively, a prefix arg means to prompt for BUFFER."
     (define-key map "p" #'sweep-find-predicate)
     (define-key map "t" #'sweep-top-level)
     (define-key map "P" #'sweep-pack-install)
+    (define-key map "e" #'sweep-view-messages)
     map)
   "Keymap for `sweep' global commands.")
 
-- 
2.39.2