From: Eshel Yaron <me@eshelyaron.com>
Date: Sat, 14 Jan 2023 09:07:19 +0000 (+0200)
Subject: DOC: improve listings in the "Editing Prolog Code" section
X-Git-Tag: V9.1.3-sweep-0.11.3~7
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=471fc1aada9e9c96636d79cf62d05138ebb2a04b;p=sweep.git

DOC: improve listings in the "Editing Prolog Code" section
---

diff --git a/README.org b/README.org
index 7fae727..4bc658e 100644
--- a/README.org
+++ b/README.org
@@ -360,18 +360,27 @@ function without any arguments.
 :END:
 
 #+CINDEX: sweeprolog-mode
-#+FINDEX: sweeprolog-mode
-#+VINDEX: sweeprolog-mode
 Sweep includes a dedicated major mode for reading and editing Prolog
-code, called =sweeprolog-mode=.  To activate this mode in a buffer, type =M-x
-sweeprolog-mode=.  To instruct Emacs to always open Prolog files in
-=sweeprolog-mode=, modify the Emacs variable =auto-mode-alist= like so:
+code, called =sweeprolog-mode=:
+
+- Command: sweeprolog-mode :: Enable Sweep major mode for reading and
+  editing SWI-Prolog code in the current buffer.
+- Variable: sweeprolog-mode-hook :: Hook run after entering
+  ~sweeprolog-mode~.  For more information about major mode hooks in
+  Emacs see [[info:emacs#Hooks][Hooks]] in the Emacs manual.
+
+To activate this mode in a buffer, type =M-x sweeprolog-mode=.  To
+instruct Emacs to always open Prolog files in =sweeprolog-mode=, modify
+the Emacs variable ~auto-mode-alist~ accordingly:
 
 #+begin_src emacs-lisp
   (add-to-list 'auto-mode-alist '("\\.pl\\'"   . sweeprolog-mode))
   (add-to-list 'auto-mode-alist '("\\.plt\\'"  . sweeprolog-mode))
 #+end_src
 
+For more information about how Emacs chooses a major mode to use when
+you visit a file, see [[info:emacs#Choosing Modes][Choosing Modes]] in the Emacs manual.
+
 ** Indentation
 :PROPERTIES:
 :CUSTOM_ID: indentation
@@ -385,7 +394,17 @@ determined by a bespoke /indentation engine/.  The indentation engine
 analyses the syntactic context of a given line and determines the
 appropriate indentation to apply based on a set of rules.
 
-#+FINDEX: sweeprolog-indent-line
+#+KINDEX: C-i
+- Key: TAB (indent-for-tab-command) :: Indent the current line.  If
+  the region is active, indent all the lines within it.  Calls the
+  mode-dependent function specified by the variable
+  ~indent-line-function~ to do the work.
+- Function: sweeprolog-indent-line :: Indent the current line
+  according to SWI-Prolog conventions.  This function is used as an
+  ~indent-line-function~ in ~sweeprolog-mode~ buffers.
+- Command: sweeprolog-infer-indent-style :: Infer indentation style
+  for the current buffer from its contents.
+
 The entry point of the indentation engine is the function
 =sweeprolog-indent-line= which takes no arguments and indents that line
 at point.  =sweeprolog-mode= supports the standard Emacs interface for
@@ -394,8 +413,6 @@ whenever a line should be indented, notably after pressing =TAB=.  For a
 full description of the available commands and options that pertain to
 indentation, see [[info:emacs#Indentation][Indentation]] in the Emacs manual.
 
-#+FINDEX: sweeprolog-infer-indent-style
-#+KINDEX: C-c C-I
 #+CINDEX: indentation style
 #+VINDEX: indent-tabs-mode
 #+VINDEX: sweeprolog-indent-offset
@@ -500,7 +517,7 @@ rules:
             predicate/3.
    #+end_src
 
-** Semantic highlighting
+** Semantic Highlighting
 :PROPERTIES:
 :CUSTOM_ID: semantic-highlighting
 :DESCRIPTION: Rich fontification for Prolog code
@@ -519,18 +536,24 @@ editing and moving around the buffer, a faster, local analysis is
 invoked to updated the semantic highlighting in response to changes in
 the buffer.
 
-#+KINDEX: C-c C-c (sweeprolog-mode)
-#+FINDEX: sweeprolog-analyze-buffer
+- Key: C-c C-c (sweeprolog-analyze-buffer) :: Analyze the current
+  buffer and update cross-references.
+- User Option: sweeprolog-analyze-buffer-on-idle :: If non-nil,
+  analyze ~sweeprolog-mode~ buffers on idle.  Defaults to ~t~.
+- User Option: sweeprolog-analyze-buffer-max-size :: Maximum number
+  characters in a ~sweeprolog-mode~ buffer to analyze on idle.  Larger
+  buffers are not analyzed on idle.  Defaults to 100,000 characters.
+- User Option: sweeprolog-analyze-buffer-min-interval :: Minimum
+  number of idle seconds to wait before analyzing a ~sweeprolog-mode~
+  buffer.  Defaults to 1.5.
+
 At any point in a =sweeprolog-mode= buffer, the command =C-c C-c= (or =M-x
 sweeprolog-analyze-buffer=) can be used to update the cross reference
-cache and highlight the buffer accordingly.  When ~flymake~ integration
+cache and highlight the buffer accordingly.  When Flymake integration
 is enabled, this command also updates the diagnostics for the current
-buffer (see [[*Examining diagnostics][Examining diagnostics]]).  This may be useful e.g. after
+buffer (see [[#diagnostics][Examining Diagnostics]]).  This may be useful e.g. after
 defining a new predicate.
 
-#+VINDEX: sweeprolog-analyze-buffer-on-idle
-#+VINDEX: sweeprolog-analyze-buffer-max-size
-#+VINDEX: sweeprolog-analyze-buffer-min-interval
 If the user option =sweeprolog-analyze-buffer-on-idle= is set to non-nil
 (as it is by default), =sweeprolog-mode= also updates semantic highlighting
 in the buffer whenever Emacs is idle for a reasonable amount of time,
@@ -550,7 +573,7 @@ Prolog code buffer.
 To view and customize all of the faces defined and used in Sweep, type
 =M-x customize-group RET sweeprolog-faces RET=.
 
-*** Available styles
+*** Available Styles
 :PROPERTIES:
 :CUSTOM_ID: highlighting-styles
 :DESCRIPTION: Available highlighting styles
@@ -559,14 +582,16 @@ To view and customize all of the faces defined and used in Sweep, type
 
 Sweep comes with three highlighting styles:
 
-- The =default= style includes faces that mostly inherit from standard
-  Emacs faces commonly used in programming modes.
-- The =light= style mimics the colors used in the SWI-Prolog built-in
-  editor.
-- The =dark= style mimics the colors used in the SWI-Prolog built-in
-  editor in dark mode.
+1. The default style includes faces that mostly inherit from standard
+   Emacs faces commonly used in programming modes.
+2. The =light= style mimics the colors used in the SWI-Prolog built-in
+   editor.
+3. The =dark= style mimics the colors used in the SWI-Prolog built-in
+   editor in dark mode.
+
+- User Option: sweeprolog-faces-style :: Style of faces to use for
+  semantic highlighting in ~sweeprolog-mode~ buffers.  Defaults to ~nil~.
 
-#+VINDEX: sweeprolog-faces-style
 To choose a style, customize the user option =sweeprolog-faces-style= with
 =M-x customize-option RET sweeprolog-faces-style RET=.  The new style will
 apply to all new =sweeprolog-mode= buffers.  To apply the new style to an
@@ -588,11 +613,17 @@ Emacs minor mode =cursor-sensor-mode= which allows for running hooks
 when the cursor enters or leaves certain text regions (see also [[info:elisp#Special
 Properties][Special Properties in the Elisp manual]]).
 
-#+VINDEX: sweeprolog-enable-cursor-sensor
+- Command: sweeprolog-highlight-variable :: Highlight occurrences of a
+  Prolog variable in the clause at point.  With a prefix argument,
+  clear variable highlighting in the clause at point instead.
+
+- User Option: sweeprolog-enable-cursor-sensor :: If non-nil, use
+  ~cursor-sensor-mode~ to highlight Prolog variables sharing with the
+  variable at point in ~sweeprolog-mode~ buffers.  Defaults to ~t~.
+
 To disable automatic variable highlighting based on the variable at
 point, customize the variable =sweeprolog-enable-cursor-sensor= to nil.
 
-#+FINDEX: sweeprolog-highlight-variable
 To manually highlight occurrences of a variable in the clause
 surrounding point, =sweeprolog-mode= provides the command =M-x
 sweeprolog-highlight-variable=.  This command prompts for variable to
@@ -610,7 +641,11 @@ clears all variable highlighting in the current clause instead.
 Quasi-quotations in =sweeprolog-mode= buffer are highlighted according
 to the Emacs mode corresponding to the quoted language by default.
 
-#+VINDEX: sweeprolog-qq-mode-alist
+- User Option: sweeprolog-qq-mode-alist :: Alist of (TYPE . MODE)
+  pairs, where TYPE is a Prolog quasi-quotation type, and MODE is a
+  symbol specifying a major mode to use for highlighting the
+  quasi-quoted text.
+
 The association between SWI-Prolog quasi-quotation types and Emacs
 major modes is determined by the user option =sweeprolog-qq-mode-alist=.
 To modify the default associations provided by =sweeprolog-mode=, type
@@ -660,8 +695,15 @@ Layout mode]]).
 :DESCRIPTION: Commands for adjusting whitespace according to Prolog conventions
 :ALT_TITLE: Aligning Spaces
 :END:
-#+FINDEX: sweeprolog-align-spaces
-#+FINDEX: cycle-spacing
+
+- Command: sweeprolog-align-spaces :: Insert or remove spaces around
+  point to such that the next Prolog token starts at a column
+  distanced from the beginning of the previous token by a multiple of
+  four columns.
+- User Option: sweeprolog-enable-cycle-spacing :: If non-nil, add
+  ~sweeprolog-align-spaces~ as the first element of
+  ~cycle-spacing-actions~ in ~sweeprolog-mode~ buffers.  Defaults to ~t~.
+
 To insert or update whitespace around point, use the command ~M-x
 sweeprolog-align-spaces~.  For example, consider a ~sweeprolog-mode~
 buffer with the following contents, where =^= designates the location of
@@ -684,12 +726,14 @@ the expected layout:
           ^
 #+end_src
 
+#+FINDEX: cycle-spacing
 In Emacs 29, the command ~M-x cycle-spacing~ is extensible via a list of
 callback functions stored in the variable ~cycle-spacing-actions~.
 Sweep leverages this facility and adds ~sweeprolog-align-spaces~ as the
 first action of ~cycle-spacing~.  To inhibit ~sweeprolog-mode~ from doing
 so, set the user option ~sweeprolog-enable-cycle-spacing~ to nil.
 
+#+KINDEX: M-SPC
 Moreover, in Emacs 29 ~cycle-spacing~ is bound by default to ~M-SPC~, thus
 aligning if-then-else and similar constructs only requires typing
 ~M-SPC~ after the first token.
@@ -711,12 +755,15 @@ lines to Emacs's initialization file (see [[info:emacs#Init File][The Emacs Init
 :END:
 
 #+CINDEX: electric layout
-#+FINDEX: sweeprolog-electric-layout-mode
-#+VINDEX: sweeprolog-mode-hook
 The minor mode ~sweeprolog-electric-layout-mode~ adjusts whitespace
-around point automatically as you type.  It works by examining the
-context of point whenever a character is inserted in the current
-buffer, and applying the following layout rules:
+around point automatically as you type:
+
+- Command: sweeprolog-electric-layout-mode :: Toggle automatic
+  whitespace adjustment according to SWI-Prolog conventions.
+
+It works by examining the context of point whenever a character is
+inserted in the current buffer, and applying the following layout
+rules:
 
 - =PlDoc= Comments :: Insert two consecutive spaces after the ~%!~ or ~%%~
   starting a =PlDoc= predicate documentation structured comment.
@@ -729,15 +776,12 @@ buffer, and applying the following layout rules:
 
 To enable this mode in a ~sweeprolog-mode~ buffer, type ~M-x
 sweeprolog-electric-layout-mode~.  This step can be automated by adding
-~sweeprolog-electric-layout-mode~ to ~sweeprolog-mode-hook~[fn:1]:
+~sweeprolog-electric-layout-mode~ to ~sweeprolog-mode-hook~:
 
 #+begin_src emacs-lisp
   (add-hook 'sweeprolog-mode-hook #'sweeprolog-electric-layout-mode)
 #+end_src
 
-[fn:1] For more information about major mode hooks in Emacs, which
-~sweeprolog-mode-hook~ is one of, see [[info:emacs#Hooks][Hooks]].
-
 ** Term-based editing and motion commands
 :PROPERTIES:
 :CUSTOM_ID: term-based-commands
@@ -753,15 +797,18 @@ with Lisp expressions, or "sexps".  =sweeprolog-mode= extends the Emacs's
 notion of syntactic expressions to accommodate for Prolog terms, which
 allows the standard sexp-based commands to operate on them seamlessly.
 
-#+KINDEX: C-M-^
-#+FINDEX: raise-sexp
-[[info:emacs#Expressions][Expressions in the Emacs manual]] covers the most important commands
-that operate on sexps, and by extension on Prolog terms.  Another
-useful command for Prolog programmers is =M-x kill-backward-up-list=,
-bound by default to =C-M-^= in =sweeprolog-mode= buffers.  This command
-replaces the parent term containing the term at point with the term
-itself.  To illustrate the utility of this command, consider the
-following clause:
+The [[info:emacs#Expressions][Expressions]] section in the Emacs manual covers the most important
+commands that operate on sexps, and by extension on Prolog terms.
+Another useful command for Prolog programmers is =M-x
+kill-backward-up-list=, bound by default to =C-M-^= in =sweeprolog-mode=
+buffers.
+
+- Key: C-M-^ (kill-backward-up-list) :: Kill the Prolog term
+  containing the current term, leaving the current term itself.
+
+This command replaces the parent term containing the term at
+point with the term itself.  To illustrate the utility of this
+command, consider the following clause:
 
 #+begin_src prolog
   head :-
@@ -803,9 +850,23 @@ Prolog parser.  Holes are written in the buffer as regular Prolog
 variables, but they are annotated with a special text property[fn:2]
 that allows Sweep to recognize them as holes needed to be filled.
 
-#+FINDEX: sweeprolog-insert-term-with-holes
 #+KINDEX: C-c C-m
-#+KINDEX: C-c RET
+- Key: C-c RET (sweeprolog-insert-term-with-holes) :: Insert a Prolog
+  term with a given functor and arity at point, using holes for
+  arguments.
+#+KINDEX: C-c C-i
+- Key: C-c TAB (sweeprolog-forward-hole) :: Move point to the next
+  hole in the buffer.
+#+KINDEX: C-c C-S-i
+- Key: C-c S-TAB (sweeprolog-backward-hole) :: Move point to the
+  previous hole in the buffer.
+- User Option: sweeprolog-highlight-holes :: If non-nil, highlight
+  holes in ~sweeprolog-mode~ buffers with a dedicated face.  Defaults to
+  ~t~.
+- Command: sweeprolog-forward-hole-on-tab-mode :: Toggle moving to the
+  next hole in the buffer with ~TAB~ if the current line is already
+  properly indented.
+
 The main command for inserting terms with holes is ~M-x
 sweeprolog-insert-term-with-holes~.  This command, bound by default to
 ~C-c C-m~ (or ~C-c RET~) in ~sweeprolog-mode~ buffers, prompts for a functor
@@ -834,19 +895,12 @@ including ~C-M-i~ (see [[#code-completion][Code Completion]]), ~C-M-m~ (see [[#i
 Insertion]]) and ~M-x sweeprolog-plunit-testset-skeleton~ (see [[#writing-tests][Writing
 Tests]]).
 
-#+VINDEX: sweeprolog-highlight-holes
 When the user option ~sweeprolog-highlight-holes~ is set to non-nil,
 holes in Prolog buffers are highlighted with a dedicated face, making
 them easily distinguishable from regular Prolog variables.  Hole
 highlighting is enabled by default, to disable it customize
 ~sweeprolog-highlight-holes~ to nil.
 
-#+FINDEX: sweeprolog-backward-hole
-#+FINDEX: sweeprolog-forward-hole
-#+KINDEX: C-c C-i
-#+KINDEX: C-c TAB
-#+KINDEX: C-- C-c C-i
-#+KINDEX: C-- C-c TAB
 To jump to the next hole in a ~sweeprolog-mode~ buffer, use the command
 ~M-x sweeprolog-forward-hole~, bound by default to ~C-c TAB~ (or ~C-c C-i~).
 This command sets up the region to cover the next hole after point
@@ -854,9 +908,6 @@ leaving the cursor at right after the hole.  To jump to the previous
 hole instead, use ~sweeprolog-backward-hole~ or call
 ~sweeprolog-forward-hole~ with a negative prefix argument (~C-- C-c TAB~).
 
-#+FINDEX: sweeprolog-forward-hole-on-tab-mode
-#+KINDEX: TAB (sweeprolog-forward-hole-on-tab-mode)
-#+KINDEX: C-i (sweeprolog-forward-hole-on-tab-mode)
 When the minor mode ~sweeprolog-forward-hole-on-tab-mode~ is enabled,
 the ~TAB~ key is bound to a command moves to the next hole when called
 in a properly indented line (otherwise it indents the line).  This
@@ -880,7 +931,7 @@ active (see also [[info:emacs#Using Region][Using Region in the Emacs manual]]).
 
 [fn:2] see [[info:elisp#Text Properties][Text Properties in the Elisp manual]]
 
-** Definitions and references
+** Definitions and References
 :PROPERTIES:
 :CUSTOM_ID: sweeprolog-xref
 :DESCRIPTION: Commands for finding cross-references for Prolog predicates
@@ -890,32 +941,32 @@ active (see also [[info:emacs#Using Region][Using Region in the Emacs manual]]).
 #+CINDEX: cross reference
 #+CINDEX: xref
 #+KINDEX: M-.
-=sweeprolog-mode= integrates with the Emacs =xref= API to facilitate quick
+~sweeprolog-mode~ integrates with the Emacs =xref= API to facilitate quick
 access to predicate definitions and references in Prolog code buffers.
 This enables the many commands that the =xref= interface provides, like
-=M-.= for jumping to the definition of the predicate at point.  Refer to
-[[info:emacs#Find Identifiers][Find Identifiers in the Emacs manual]] for an overview of the available
-commands.
+~M-.~ (~xref-find-definitions~) for jumping to the definition of the
+predicate at point.  Refer to [[info:emacs#Find Identifiers][Find Identifiers]] in the Emacs manual for
+an overview of the available commands.
 
 #+CINDEX: imenu
 #+KINDEX: M-g i
-=sweeprolog-mode= also integrates with Emacs's =imenu=, which provides a simple
-facility for looking up and jumping to definitions in the current
-buffer.  To jump to a definition in the current buffer, type =M-x imenu=
-(bound by default to =M-g i= in Emacs version 29).  For information
-about customizing =imenu=, see [[info:emacs#Imenu][Imenu in the Emacs manual]].
+~sweeprolog-mode~ also integrates with Emacs's =imenu=, which provides a
+simple facility for looking up and jumping to definitions in the
+current buffer.  To jump to a definition in the current buffer, type
+~M-x imenu~ (bound by default to ~M-g i~ in Emacs version 29).  For
+information about customizing =imenu=, see [[info:emacs#Imenu][Imenu]] in the Emacs manual.
 
 #+FINDEX: sweeprolog-xref-project-source-files
 #+KINDEX: M-?
 The command ~M-x sweeprolog-xref-project-source-files~ can be used to
 update Sweep's cross reference data for all Prolog source files in the
 current project, as determined by the function ~project-current~ (see
-[[info:emacs#Projects][Projects in the Emacs manual]]).  When searching for references to
+[[info:emacs#Projects][Projects]] in the Emacs manual).  When searching for references to
 Prolog predicates with ~M-?~ (~xref-find-references~), this command is
 invoked implicitly to ensure up to date references are found
 throughout the current project.
 
-** Predicate definition boundaries
+** Predicate Definition Boundaries
 :PROPERTIES:
 :CUSTOM_ID: predicate-boundaries
 :DESCRIPTION: Commands operating on a Prolog predicate definition as a single unit
@@ -923,37 +974,49 @@ throughout the current project.
 :END:
 
 #+CINDEX: predicate-based motion
-#+FINDEX: sweeprolog-forward-predicate
-#+FINDEX: sweeprolog-backward-predicate
-#+KINDEX: M-n
-#+KINDEX: M-p
+The following commands act on entire Prolog predicate definitions as a
+single unit:
+
+- Key: M-n (sweeprolog-forward-predicate) :: Move forward from point
+  to the next predicate definition in the current buffer.
+- Key: M-p (sweeprolog-backward-predicate) :: Move backward from point
+  to the previous predicate definition.
+- Key: M-h (sweeprolog-mark-predicate) :: Select the current predicate
+  as the active region, put point at the its beginning, and the mark
+  at the end.
+
 In ~sweeprolog-mode~, the commands ~M-n~ (~sweeprolog-forward-predicate~)
 and ~M-p~ (~sweeprolog-backward-predicate~) are available for quickly
 jumping to the first line of the next or previous predicate
 definition in the current buffer.
 
-#+KINDEX: M-h
 The command ~M-h~ (~sweeprolog-mark-predicate~) marks the entire predicate
 definition at point, along with its =PlDoc= comments if there are any.
 This can be followed, for example, with killing the marked region to
 relocate the defined predicate by typing ~M-h C-w~.
 
-** Following file specifications
+** Following File Specifications
 :PROPERTIES:
 :CUSTOM_ID: following-file-specs
 :DESCRIPTION: Commands for jumping to files that appear in Prolog code
 :ALT_TITLE: File Specifications
 :END:
 
-#+KINDEX: C-c C-o
-#+FINDEX: sweeprolog-find-file-at-point
-File specifications that occur in =sweeprolog-mode= buffers can be followed
-with =C-c C-o= (or =M-x sweeprolog-find-file-at-point=) whenever point is over
-a valid file specification.  For example, consider a Prolog file buffer with the common
-directive =use_module/1=:
+In SWI-Prolog, one often refers to source file paths using /file
+specifications/, special Prolog terms that act as path aliases, such
+as ~library(lists)~ which refers to a file ~lists.pl~ in any of the Prolog
+library directories.
+
+- Key: C-c C-o (sweeprolog-find-file-at-point) :: Resolve file
+  specification at point and visit the specified file.
+
+You can follow file specifications that occur in =sweeprolog-mode=
+buffers with =C-c C-o= (or =M-x sweeprolog-find-file-at-point=) whenever
+point is over a valid file specification.  For example, consider a
+Prolog file buffer with the common directive =use_module/1=:
 
 #+begin_src prolog
-:- use_module(library(lists)).
+  :- use_module(library(lists)).
 #+end_src
 
 With point in any position inside =library(lists)=, typing =C-c C-o= will
@@ -962,28 +1025,29 @@ open the =lists.pl= file in the Prolog library.
 For more information about file specifications in SWI-Prolog, see
 [[https://www.swi-prolog.org/pldoc/doc_for?object=absolute_file_name/3][absolute_file_name/3]] in the SWI-Prolog manual.
 
-** Loading buffers
+** Loading Buffers
 :PROPERTIES:
 :CUSTOM_ID: loading-buffers
 :DESCRIPTION: Commands for loading Prolog predicates from the current buffer
 :ALT_TITLE: Loading Buffers
 :END:
 
-#+KINDEX: C-c C-l
-#+KINDEX: C-u C-c C-l
 #+CINDEX: loading
-#+FINDEX: sweeprolog-load-buffer
-The command =M-x sweeprolog-load-buffer= can be used to load the
-contents of a =sweeprolog-mode= buffer into the embedded SWI-Prolog
-runtime.  After a buffer is loaded, the predicates it defines can be
-queried from Elisp (see [[Querying Prolog]]) and from the Sweep top-level
-(see [[The Prolog Top-Level]]).  In =sweeprolog-mode= buffers,
-=sweeprolog-load-buffer= is bound by default to =C-c C-l=.  By default
-this command loads the current buffer if its major mode is
-=sweeprolog-mode=, and prompts for an appropriate buffer otherwise.  To
-choose a different buffer to load while visiting a =sweeprolog-mode=
-buffer, invoke =sweeprolog-load-buffer= with a prefix argument (=C-u C-c
-C-l=).
+You can load a buffer of SWI-Prolog code with the following command:
+
+- Key: C-c C-l (sweeprolog-load-buffer) :: Load the current buffer
+  into the embedded SWI-Prolog runtime.
+
+Use the command ~M-x sweeprolog-load-buffer~ to load the contents of a
+~sweeprolog-mode~ buffer into the embedded SWI-Prolog runtime.  After a
+buffer is loaded, the predicates it defines can be queried from Elisp
+(see [[Querying Prolog]]) and from the Sweep top-level (see [[The Prolog
+Top-Level]]).  In ~sweeprolog-mode~ buffers, ~sweeprolog-load-buffer~ is
+bound to ~C-c C-l~.  By default this command loads the current buffer if
+its major mode is ~sweeprolog-mode~, and prompts for an appropriate
+buffer otherwise.  To choose a different buffer to load while visiting
+a ~sweeprolog-mode~ buffer, invoke ~sweeprolog-load-buffer~ with a prefix
+argument (~C-u C-c C-l~).
 
 More relevant information about loading code in SWI-Prolog can be
 found in [[https://www.swi-prolog.org/pldoc/man?section=consulting][Loading Prolog source files]] in the SWI-Prolog manual.
@@ -1000,10 +1064,13 @@ Sweep integrates with the Emacs =auto-insert= facility to simplify
 creation of new SWI-Prolog modules.  =auto-insert= allows for populating
 newly created files with templates defined by the relevant major mode.
 
-Sweep associates a Prolog module skeleton with =sweeprolog-mode=, the
+- User Option: sweeprolog-module-header-comment-skeleton :: Additional
+  content to put in the topmost comment in Prolog module headers.
+
+Sweep associates a Prolog module skeleton with ~sweeprolog-mode~, the
 skeleton begins with a "file header" multi-line comment which includes
 the name and email address of the user based on the values of
-=user-full-name= and =user-mail-address= respectively.  A =module/2=
+~user-full-name~ and ~user-mail-address~ respectively.  A ~module/2~
 directive is placed after the file header, with the module name set to
 the base name of the file.  Lastly the skeleton inserts a =PlDoc= module
 comment to be filled with the module's documentation (see [[https://www.swi-prolog.org/pldoc/man?section=sectioncomments][File
@@ -1027,22 +1094,22 @@ As an example, after inserting the module skeleton, a new Prolog file
 
 #+end_src
 
-#+VINDEX: sweeprolog-module-header-comment-skeleton
-The multi-line comment included above the =module/2= directive can be
+The multi-line comment included above the ~module/2~ directive can be
 extended by customizing the user option
-=sweeprolog-module-header-comment-skeleton=, which see.  This can be
+~sweeprolog-module-header-comment-skeleton~, which see.  This can be
 useful for including e.g. copyright text in the file header.
 
-To open a new Prolog file, use the standard =C-x C-f= (=find-file=) and
-select a location for the new file.  In the new =sweeprolog-mode=
-buffer, type =M-x auto-insert= to insert the Prolog module skeleton.
+To open a new Prolog file, use the standard ~C-x C-f~ (~find-file~)
+command and select a location for the new file.  In the new
+~sweeprolog-mode~ buffer, type ~M-x auto-insert~ to insert the Prolog
+module skeleton.
 
 To automatically insert the module skeleton when opening new files in
-=sweeprolog-mode=, enable the minor mode =auto-insert-mode=.  For detailed
+~sweeprolog-mode~, enable the minor mode ~auto-insert-mode~.  For detailed
 information about =auto-insert= and its customization options, see
 [[info:autotype#Autoinserting][Autoinserting in the Autotyping manual]].
 
-** Documenting predicates
+** Documenting Predicates
 :PROPERTIES:
 :CUSTOM_ID: sweeprolog-pldoc
 :DESCRIPTION: Commands for adding documentation to Prolog predicate definitions
@@ -1060,15 +1127,22 @@ programming languages, which apply also to writing =PlDoc= comments for
 Prolog predicates.  For an overview of the relevant standard Emacs
 commands, see [[info:emacs#Comment Commands][Comment Commands in the Emacs manual]].
 
-#+KINDEX: C-c C-d
-#+FINDEX: sweeprolog-document-predicate-at-point
-#+FINDEX: sweeprolog-document-predicate-default-function
-#+FINDEX: sweeprolog-document-predicate-with-holes
-#+VINDEX: sweeprolog-document-predicate-function
+- Key: C-c C-d (sweeprolog-document-predicate-at-point) :: Insert
+  =PlDoc= documentation comment for the predicate at or above point.
+- User Option: sweeprolog-read-predicate-documentation-function :: Function
+  to use for determining the initial contents of documentation
+  comments inserted with ~sweeprolog-document-predicate-at-point~.
+- Function: sweeprolog-read-predicate-documentation-default-function functor arity :: Prompt
+  and read from the minibuffer the arguments modes, determinism
+  specification and initial summary for the documentation of the
+  predicate FUNCTOR/ARITY.
+- Function: sweeprolog-read-predicate-documentation-with-holes functor arity :: Use
+  holes for the initial documentation of the predicate FUNCTOR/ARITY.
+
 Sweep also includes a dedicated command called
-=sweeprolog-document-predicate-at-point= for interactively creating
-=PlDoc= comments for predicates in =sweeprolog-mode= buffers.  This
-command, bound by default to =C-c C-d=, finds the beginning of the
+~sweeprolog-document-predicate-at-point~ for interactively creating
+=PlDoc= comments for predicates in ~sweeprolog-mode~ buffers.  This
+command, bound by default to ~C-c C-d~, finds the beginning of the
 predicate definition under or right above the current cursor location,
 and inserts a formatted =PlDoc= comment.  This command fills in initial
 argument modes, determinism specification, and optionally a summary
@@ -1089,8 +1163,8 @@ argument modes and determinism specifiers by setting this option to
 
 ~sweeprolog-document-predicate-at-point~ leaves the cursor at the end of
 the newly inserted documentation comment for the user to extend or
-edit it if needed.  To add another comment line, use =M-j=
-(=default-indent-new-line=) which starts a new line with the comment
+edit it if needed.  To add another comment line, use ~M-j~
+(~default-indent-new-line~) which starts a new line with the comment
 prefix filled in.  Emacs also has other powerful built-in features for
 working with comments in code buffers that you can leverage to edit
 =PlDoc= comments.  For full details, see [[info:emacs#Comments][Manipulating Comments]].
@@ -1103,24 +1177,29 @@ documented in [[info:emacs#Text][Commands for Human Languages]], which see.
 For more information about =PlDoc= and source documentation in
 SWI-Prolog, see [[https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/pldoc.html%27)][the PlDoc manual]].
 
-** Displaying predicate documentation
+** Displaying Predicate Documentation
 :PROPERTIES:
 :CUSTOM_ID: eldoc-integration
 :DESCRIPTION: Commands for showing documentation for Prolog predicates
 :ALT_TITLE: Showing Prolog Docs
 :END:
 
-Sweep integrates with the Emacs minor mode =ElDoc=, which automatically
+Sweep integrates with the Emacs minor mode ElDoc, which automatically
 displays documentation for the predicate at point.  Whenever the
 cursor enters a predicate definition or invocation, the signature and
 summary of that predicate are displayed in the echo area at the bottom
 of the frame.
 
-#+VINDEX: sweeprolog-enable-eldoc
-To disable the =ElDoc= integration in =sweeprolog-mode= buffers, customize
-the user option =sweeprolog-enable-eldoc= to nil.
+- User Option: sweeprolog-enable-eldoc :: If non-nil, enable ElDoc
+  support in ~sweeprolog-mode~ buffers.  Defaults to ~t~.
+
+To disable the ElDoc integration in ~sweeprolog-mode~ buffers, customize
+the user option ~sweeprolog-enable-eldoc~ to ~nil~.
+
+For more information about ElDoc and its customization options, see [[info:emacs#Programming Language
+Doc][Programming Language Doc]] in the Emacs manual.
 
-** Examining diagnostics
+** Examining Diagnostics
 :PROPERTIES:
 :CUSTOM_ID: diagnostics
 :DESCRIPTION: Commands for finding errors in Prolog code
@@ -1130,35 +1209,36 @@ the user option =sweeprolog-enable-eldoc= to nil.
 #+CINDEX: flymake
 #+CINDEX: diagnostics
 ~sweeprolog-mode~ can diagnose problems in Prolog code and report them
-to the user by integrating with ~flymake~, a powerful interface for
+to the user by integrating with Flymake, a powerful interface for
 on-the-fly diagnostics built into Emacs.
 
-#+FINDEX: sweeprolog-enable-flymake
-~flymake~ integration is enabled by default, to disable it customize the
+- User Option: sweeprolog-enable-flymake :: If non-nil, enable Flymake
+  support in ~sweeprolog-mode~ buffers.  Defaults to ~t~.
+- Key: C-c C-` (sweeprolog-show-diagnostics) :: List diagnostics for
+  the current buffer or project in a dedicated buffer.
+
+Flymake integration is enabled by default, to disable it customize the
 user option ~sweeprolog-enable-flymake~ to nil.
 
 #+FINDEX: next-error
 #+KINDEX: M-g n
 #+KINDEX: M-g p
-When this integration is enabled, several ~flymake~ commands are
+When this integration is enabled, several Flymake commands are
 available for listing and jumping between found errors.  For a full
-description of these commands, see [[info:flymake#Finding diagnostics][Finding diagnostics in the Flymake
-manual]].  Additionally, ~sweeprolog-mode~ configures the standard
-command ~M-x next-error~ to operate on ~flymake~ diagnostics.  This allows
-for moving to the next (or previous) error location with the common
-~M-g n~ (or ~M-g p~) keybinding.  For more information about these
-commands, see [[info:emacs#Compilation Mode][Compilation Mode in the Emacs manual]].
-
-#+FINDEX: sweeprolog-show-diagnostics
-#+KINDEX: C-c C-`
-#+KINDEX: C-u C-c C-`
-The command ~sweeprolog-show-diagnostics~ shows a list of ~flymake~
+description of these commands, see [[info:flymake#Finding diagnostics][Finding diagnostics]] in the Flymake
+manual.  Additionally, ~sweeprolog-mode~ configures the standard command
+~M-x next-error~ to operate on Flymake diagnostics.  This allows for
+moving to the next (or previous) error location with the common ~M-g n~
+(or ~M-g p~) keybinding.  For more information about these commands, see
+[[info:emacs#Compilation Mode][Compilation Mode]] in the Emacs manual.
+
+The command ~sweeprolog-show-diagnostics~ shows a list of Flymake
 diagnostics for the current buffer.  It is bound by default to ~C-c C-`~
-in ~sweeprolog-mode~ buffers with ~flymake~ integration enabled.  When
+in ~sweeprolog-mode~ buffers with Flymake integration enabled.  When
 called with a prefix argument (~C-u C-c C-`~), shows a list of
 diagnostics for all buffers in the current project.
 
-** Exporting predicates
+** Exporting Predicates
 :PROPERTIES:
 :CUSTOM_ID: exporting-predicates
 :DESCRIPTION: Commands for adding Prolog predicates to their module's export list
@@ -1171,9 +1251,9 @@ dependent modules unless they it is /exported/, by including it in the
 export list of the defining module (i.e. the second argument of the
 ~module/2~ directive).
 
-#+FINDEX: sweeprolog-export-predicate
-#+KINDEX: C-c C-e
-#+KINDEX: C-u C-c C-e
+- Key: C-c C-e (sweeprolog-export-predicate) :: Add the predicate
+  predicate at point to the export list of the current Prolog module.
+
 Sweep provides a convenient command for exporting predicates defined
 in ~sweeprolog-mode~ buffer.  To add the predicate near point to the
 export list of the current module, use the command ~C-c C-e~
@@ -1195,6 +1275,8 @@ prefix argument (~C-u C-c C-e~).
 
 #+CINDEX: code completion
 #+CINDEX: completion-at-point
+#+FINDEX: complete-symbol
+#+FINDEX: completion-at-point
 #+KINDEX: C-M-i
 #+KINDEX: M-TAB
 ~sweeprolog-mode~ empowers Emacs's standard ~completion-at-point~ command,
@@ -1226,9 +1308,6 @@ In ~sweeprolog-mode~ buffers, the following enhancements are provided:
 
 #+CINDEX: context-based term insertion
 #+CINDEX: term insertion at-point
-#+FINDEX: sweeprolog-insert-term-dwim
-#+KINDEX: M-RET
-#+KINDEX: C-M-m
 As a means of automating common Prolog code editing tasks, such as
 adding new clauses to an existing predicate, ~sweeprolog-mode~ provides
 the "do what I mean" command ~M-x sweeprolog-insert-term-dwim~, bound by
@@ -1236,7 +1315,13 @@ default to ~C-M-m~ (or equivalently, ~M-RET~).  This command inserts a new
 term at or after point according to the context in which
 ~sweeprolog-insert-term-dwim~ is invoked.
 
-#+VINDEX: sweeprolog-insert-term-functions
+#+KINDEX: C-M-m
+- Key: M-RET (sweeprolog-insert-term-dwim) :: Insert an appropriate
+  Prolog term in the current buffer, based on the context at point.
+- Variable: sweeprolog-insert-term-functions :: List of functions for
+  ~sweeprolog-insert-term-dwim~ to try for inserting a Prolog term based
+  on the current context.
+
 To determine which term to insert and exactly where, this command
 calls the functions in the list held by the variable
 ~sweeprolog-insert-term-functions~ one after the other until one of the
@@ -1245,13 +1330,11 @@ functions signal success by returning non-nil.
 By default, ~sweeprolog-insert-term-dwim~ tries the following insertion
 functions, in order:
 
-#+FINDEX: sweeprolog-maybe-insert-next-clause
-#+FINDEX: sweeprolog-maybe-define-predicate
 #+VINDEX: sweeprolog-new-predicate-location-function
-- ~sweeprolog-maybe-insert-next-clause~ :: If the last token before
+- Function: sweeprolog-maybe-insert-next-clause :: If the last token before
   point is a fullstop ending a predicate clause, insert a new clause
   below it.
-- ~sweeprolog-maybe-define-predicate~ :: If point is over a call to an
+- Function: sweeprolog-maybe-define-predicate :: If point is over a call to an
   undefined predicate, insert a definition for that predicate.  By
   default, the new predicate definition is inserted right below the
   last clause of the current predicate definition.  The user option
@@ -1268,16 +1351,19 @@ head's arguments, if any.  See also [[#holes][Holes]].
 :ALT_TITLE: Writing Tests
 :END:
 
-#+FINDEX: sweeprolog-plunit-testset-skeleton
 #+CINDEX: plunit
 #+CINDEX: testing
 SWI-Prolog includes the =PlUnit= unit testing framework[fn:3], in which
 unit tests are written in special blocks of Prolog code enclosed
 within the directives ~begin_tests/1~ and ~end_tests/1~.  To insert a new
 block of unit tests (also known as a /test-set/) in a Prolog buffer, use
-the command ~M-x sweeprolog-plunit-testset-skeleton~.  This command
-prompts for a name to give the new test-set and inserts a template
-such as the following:
+the command ~M-x sweeprolog-plunit-testset-skeleton~.
+
+- Command: sweeprolog-plunit-testset-skeleton :: Insert a =PlUnit=
+  test-set skeleton at point.
+
+This command prompts for a name to give the new test-set and inserts a
+template such as the following:
 
 #+begin_src prolog
 :- begin_tests(foo_regression_tests).
@@ -1302,8 +1388,6 @@ another unit test, place point after a complete test case and type
 :ALT_TITLE: Code Dependencies
 :END:
 
-#+FINDEX: sweeprolog-update-dependencies
-#+KINDEX: C-c C-u
 #+CINDEX: dependencies
 #+CINDEX: autoload
 It is considered good practice for SWI-Prolog source files to
@@ -1311,14 +1395,21 @@ explicitly list their dependencies on predicates defined in other
 files by using ~autoload/2~ and ~use_module/2~ directives.  To find all
 implicitly autoloaded predicates in the current ~sweeprolog-mode~ buffer
 and make the dependencies on them explicit, use the command ~M-x
-sweeprolog-update-dependencies~ bound to ~C-c C-u~.  This command
-analyzes the current buffer and adds or updates ~autoload/2~ and
-~use_module/2~ as needed.
+sweeprolog-update-dependencies~ bound to ~C-c C-u~.
+
+- Key: C-c C-u (sweeprolog-update-dependencies) :: Add explicit
+  dependencies for implicitly autoloaded predicates in the current
+  buffer.
+- User Option: sweeprolog-note-implicit-autoloads :: If non-nil, have
+  Flymake complain about implicitly autoloaded predicates in
+  ~sweeprolog-mode~ buffers.
 
-#+VINDEX: sweeprolog-note-implicit-autoloads
-By default, when ~flymake~ integration is enabled (see [[#diagnostics][Examining
+This command analyzes the current buffer and adds or updates
+~autoload/2~ and ~use_module/2~ as needed.
+
+By default, when Flymake integration is enabled (see [[#diagnostics][Examining
 diagnostics]]), calls to implicitly autoloaded predicates are marked
-and reported as ~flymake~ diagnostics.  To inhibit ~flymake~ from
+and reported as Flymake diagnostics.  To inhibit Flymake from
 diagnosing implicit autoloads, customize the user option
 ~sweeprolog-note-implicit-autoloads~ to nil.
 
@@ -1329,18 +1420,24 @@ diagnosing implicit autoloads, customize the user option
 :ALT_TITLE: Term Search
 :END:
 
-#+FINDEX: sweeprolog-term-search
-#+KINDEX: C-c C-s
 #+CINDEX: term search
 #+CINDEX: search term
 You can search for Prolog terms matching a given search term with the
-command ~M-x sweeprolog-term-search~.  This command, bound by default to
-~C-c C-s~ in ~sweeprolog-mode~ buffers, prompts for a Prolog term to
-search for and finds terms in the current buffer that the search term
-subsumes.  It highlights all matching terms in the buffer and moves
-the cursor to the beginning of the next match after point.  For
-example, to find if-then-else constructs in the current buffer do ~C-c
-C-s _ -> _ ; _ RET~.
+command ~M-x sweeprolog-term-search~.
+
+- Key: C-c C-s (sweeprolog-term-search) :: Search for Prolog terms
+  matching a given search term in the current buffer.
+- Command: sweeprolog-term-search-repeat-forward :: Repeat the last
+  Term Search, searching forward from point.
+- Command: sweeprolog-term-search-repeat-backward :: Repeat the last
+  Term Search, searching backward from point.
+
+This command, bound by default to ~C-c C-s~ in ~sweeprolog-mode~ buffers,
+prompts for a Prolog term to search for and finds terms in the current
+buffer that the search term subsumes.  It highlights all matching
+terms in the buffer and moves the cursor to the beginning of the next
+match after point.  For example, to find if-then-else constructs in
+the current buffer do ~C-c C-s _ -> _ ; _ RET~.
 
 While prompting for a search term in the minibuffer, this command
 populates the "future history" with the Prolog terms at point, with
@@ -1357,8 +1454,6 @@ arbitrary Prolog goal for filtering out search results that fail it.
 The given goal runs for each matching term, it may use variables from
 the search term to refer to subterms of the matching term.
 
-#+FINDEX: sweeprolog-term-search-repeat-forward
-#+FINDEX: sweeprolog-term-search-repeat-backward
 #+KINDEX: C-s (sweeprolog-term-search-map)
 #+KINDEX: C-r (sweeprolog-term-search-map)
 Typing ~C-s~ immediately after a successful search invokes the command
@@ -1381,14 +1476,17 @@ Emacs ~help~ user interface, akin to Emacs's built-in ~describe-function~
 Emacs ~help~ and its special major mode, ~help-mode~, see [[info:emacs#Help Mode][Help Mode in the
 Emacs manual]].
 
-#+FINDEX: sweeprolog-describe-module
+- Command: sweeprolog-describe-module :: Prompt for a Prolog module
+  and display its full documentation in a help buffer.
+- Command: sweeprolog-describe-predicate :: Prompt for a Prolog
+  predicate and display its full documentation in a help buffer.
+
 #+KINDEX: s (help-mode)
 The command ~M-x sweeprolog-describe-module~ prompts for the name of a
 Prolog module and displays its documentation in the =*Help*= buffer.  To
 jump to the source code from the documentation, press ~s~
 (~help-view-source~).
 
-#+FINDEX: sweeprolog-describe-predicate
 Similarly, ~M-x sweeprolog-describe-predicate~ can be used to display
 the documentation of a Prolog predicate.  This commands prompts for a
 predicate with completion.  When the cursor is over a predicate
@@ -1427,7 +1525,7 @@ bound to a random port to accept incoming connections from top-level
 buffers.  The TCP server only accepts connections from the local
 machine, but note that _other users on the same host_ may be able to
 connect to the TCP server socket and _get a Prolog top-level_.  This may
-pose a security problem when sharing a host with entrusted users,
+pose a security problem when sharing a host with untrusted users,
 hence ~sweeprolog-top-level~ _should not be used on shared machines_.
 This is the only Sweep feature that should be avoided in such cases.
 
@@ -1690,7 +1788,7 @@ manual]] for information about working with C code in Emacs).  These
 commands include:
 - ~M-x sweeprolog-find-predicate~,
 - ~M-.~ (~xref-find-definitions~) in ~sweeprolog-mode~ buffers (see
-  [[#sweeprolog-xref][Definitions and references]]), and
+  [[#sweeprolog-xref][Definitions and References]]), and
 - ~s~ (~help-view-source~) in the =*Help*= buffer produced by ~M-x
   sweeprolog-describe-predicate~ (see [[#prolog-help][Prolog Help]]).