DOC: document the Prolog messages buffer

diff --git a/README.org b/README.org
index e9d9cea09ba373b113f38765237ac35d54a13d6c..7d98fd940a759f0600750ff45b1b687fea8a3aa2 100644 (file)
--- 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 1fa56f7970a21fc9e1a5127e1929b03abec58b6a..0c54a88c547a95d6273d53a094c68e5c6ca27403 100644 (file)
--- 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.")