[elpa] externals/mct 8a444a6b13 4/5: Rewrite manual for mct-region-mode

[ELPA Syncer]

branch: externals/mct
commit 8a444a6b13d5e02a04f18153231b51d0400168fa
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Rewrite manual for mct-region-mode
---
 README.org | 154 +++++++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 100 insertions(+), 54 deletions(-)

diff --git a/README.org b/README.org
index 3ebd4cef48..be2b4755c8 100644
--- a/README.org
+++ b/README.org
@@ -165,31 +165,35 @@ Emacs draws a distinction between two types of completion 
sessions:
 
 + Completion where the minibuffer is involved (such as to switch buffers
   or find a file).
+
 + Completion in a regular buffer to expand the text before point.  The
   minibuffer is not active.  We call this "in-buffer completion" or
   allude to the underlying function: ~completion-in-region~.
 
 The former scenario is what MCT has supported since its inception.
-Starting with version =0.4.0= it also covers the latter case, thoughly
-only experimentally (please report any bugs or point towards areas of
+Starting with version =0.4.0= it also covers the latter case, though only
+experimentally (please report any bugs or point towards areas of
 possible improvement).
 
+#+findex: mct-minibuffer-mode
+#+vindex: mct-minibuffer-mode
+#+findex: mct-region-mode
+#+vindex: mct-region-mode
 To let users fine-tune their setup, MCT provides the ~mct-minibuffer-mode~
-(formerly ~mct-mode~) as well as local and global variants of
-~mct-region-mode~ (~mct-region-global-mode~).
+(formerly ~mct-mode~) as well as the global ~mct-region-mode~.
 
 The decoupling between the two modes makes it possible to configure
 interchangeable components in a variety of combinations, such as MCT for
 the minibuffer and the Corfu package for completion-in-region
 ([[#h:03227254-d467-4147-b8cf-2fe05a2e279b][Extensions]]).  Or the Vertico 
package for the minibuffer and MCT for
-in-buffer completion 
([[#h:c9ddedea-e279-4233-94dc-f8d32367a954][Alternatives]]).  Same principle 
for the local
-variant of MCT's in-buffer completion mode: Corfu has the same
-capability, so the two can be used as part of a single setup.
+in-buffer completion 
([[#h:c9ddedea-e279-4233-94dc-f8d32367a954][Alternatives]]).
 
 We jokingly say that since the introduction of ~mct-region-mode~ the
 acronym "MCT" now stands for "Minibuffer Confines Transcended"---the
 original was "Minibuffer and Completions in Tandem".
 
+[[#h:97eb5898-1e52-4338-bd55-8c52f9d8ccd3][Interaction model of 
mct-region-mode]].
+
 * Usage
 :PROPERTIES:
 :CUSTOM_ID: h:884d6702-8666-4d89-87a2-7d74843653f3
@@ -199,8 +203,11 @@ This section outlines the various patterns of interaction 
that MCT
 establishes.  Note that completion covers two distinct cases, which are
 reflected in the design of MCT: (i) in the minibuffer and (ii) for
 in-buffer completion ([[#h:8109fe09-fcce-4212-88eb-943cc72f2c75][MCT in the 
minibuffer and in regular buffers]]).
+Most of this section is about the former scenario, which uses the
+~mct-minibuffer-mode~.  The ~mct-region-mode~ is less featureful by
+comparison.
 
-** Cyclic behaviour in the minibuffer
+** Cyclic behaviour for mct-minibuffer-mode
 :PROPERTIES:
 :CUSTOM_ID: h:68c61a76-1d64-4f62-a77a-52e7b66a68fe
 :END:
@@ -212,13 +219,13 @@ completions.  Suppose the following standard layout:
 
 #+begin_example
 -----------------
-|               |
-|               |
-|               |
-|  Buffer       |
-|               |
-|               |
-|               |
+|        |      |
+| Buffers| Buf  |
+|        |      |
+-----------------
+|        |      |
+| Buf    | Buf  |
+|        |      |
 -----------------
 -----------------
 |               |
@@ -263,41 +270,14 @@ of the frame.  Users can change its placement by 
configuring the
 variable ~mct-display-buffer-action~ (its doc string explains how and
 provides sample code).
 
-** Cyclic behaviour for in-buffer completion
-:PROPERTIES:
-:CUSTOM_ID: h:97eb5898-1e52-4338-bd55-8c52f9d8ccd3
-:END:
-#+cindex: Cyclic behaviour for completion in region
-
-When ~mct-region-mode~ (or ~mct-region-global-mode~) is enabled, MCT is used
-for in-buffer completion.  In this scenario, the cyclic behaviour is
-simpler than when the minibuffer is active, so we will mostly cover the
-differences ([[#h:68c61a76-1d64-4f62-a77a-52e7b66a68fe][Cyclic behaviour in 
the minibuffer]]).
-
-Once ~completion-in-region~ is triggered (such as by typing =C-M-i= in Elisp
-buffers to expand the text before point), the key bindings =C-n= and =C-p=
-switch focus to the =*Completions*= buffer: =C-n= moves to the top, while
-=C-p= goes to the bottom.  This only happens while the in-buffer
-completion session is active: it becomes inactive if, say, one switches
-to another window other than the one with the completions.
+This is not the same for in-buffer completion performed by
+~mct-region-mode~ ([[#h:97eb5898-1e52-4338-bd55-8c52f9d8ccd3][Interaction 
model of mct-region-mode]]).
 
-While inside the Completions' buffer, =C-n= and =C-p= move to the next and
-previous line, respectively.  When they reach the top/bottom boundaries
-of the Completions' buffer, they switch focus back to the buffer that
-started the completion.  However, and unlike ~mct-minibuffer-mode~, they
-do not keep the =*Completions*= window around.  This is because we cannot
-tell whether the user wanted to continue with a new completion upon
-returning to the buffer of origin or perform some other motion/command
-(in the minibuffer we can make that assumption because the minibuffer is
-purpose-specific, so for as long as it is active, the completion session
-goes on).  As such, ~completion-in-region~ must be restarted after cycling
-out of the =*Completions*=.
-
-** Selecting candidates
+** Selecting candidates with mct-minibuffer-mode
 :PROPERTIES:
 :CUSTOM_ID: h:bb445062-2e39-4082-a868-2123bfb793cc
 :END:
-#+cindex: Candidate selection
+#+cindex: Candidate selection for minibuffer completion
 
 There are several ways to select a completion candidate.  These pertain
 to ~mct-minibuffer-mode~, as ~mct-region-mode~ only has the meaningful
@@ -390,11 +370,11 @@ Completions' buffer 
([[#h:97eb5898-1e52-4338-bd55-8c52f9d8ccd3][Cyclic behaviour
    immediately exit the minibuffer with the completed candidate as the
    selected one.
 
-** Other commands
+** Other commands for mct-minibuffer-mode
 :PROPERTIES:
 :CUSTOM_ID: h:b46a3366-6a7a-49ed-8caa-693d6ee437e9
 :END:
-#+cindex: Miscellaneous commands
+#+cindex: Miscellaneous commands for minibuffer completion
 
   #+findex: mct-next-completion-group
   #+findex: mct-previous-completion-group
@@ -416,6 +396,67 @@ Completions' buffer 
([[#h:97eb5898-1e52-4338-bd55-8c52f9d8ccd3][Cyclic behaviour
   it deletes a single character backwards.  The command's symbol is
   ~mct-backward-updir~.
 
+** Interaction model of mct-region-mode
+:PROPERTIES:
+:CUSTOM_ID: h:97eb5898-1e52-4338-bd55-8c52f9d8ccd3
+:END:
+#+cindex: Interactions for in-buffer completion
+
+When ~mct-region-mode~ is enabled, MCT is used for in-buffer completion.
+In this scenario, the cyclic behaviour is less featureful than when the
+minibuffer is active (due to the specifics of the underlying commands),
+so we cover the differences ([[#h:68c61a76-1d64-4f62-a77a-52e7b66a68fe][Cyclic 
behaviour in the minibuffer]]).
+
+In terms of its interaction model, ~mct-region-mode~ only gets enabled
+manually either by pressing =TAB= or =C-M-i= (~complete-symbol~) in supporting
+major modes.  The =*Completions*= buffer pops up and is narrowed live to
+match any subsequent user input.  While the buffer is visible, we are
+performing ~completion-in-region~, which means that the Completions can be
+narrowed live by typing further.  Furthermore, =C-n= or =C-p= will move the
+point to the top/bottom of the Completions' buffer from where the user
+can select a candidate with =RET=.
+
+In-buffer completion is always invoked manually.  There is no minimum
+input threshold and no delay between updates while live-updating of the
+=*Completions*= buffer is performed.  If the Completions are not visible,
+then no ~completion-in-region~ takes place and thus ~mct-region-mode~ should
+have no effect.
+
+By default, the placement of the Completions for this type of
+interaction is below the current buffer (as opposed to the bottom of the
+frame for ~mct-minibuffer-mode~).  It looks like this:
+
+#+begin_example
+------------------------
+|               |      |
+| Current buffer| Buf  |
+|               |      |
+------------------------
+|               |      |
+|  Completions  | Buf  |
+|               |      |
+------------------------
+|        |      |      |
+|  Buf   | Buf  | Buf  |
+|        |      |      |
+------------------------
+#+end_example
+
+While inside the Completions' buffer, =C-n= and =C-p= move to the next and
+previous line, respectively.  When they reach the top/bottom boundaries
+of the Completions' buffer, they switch focus back to the buffer that
+started the completion.  However, and unlike ~mct-minibuffer-mode~, they
+do not keep the =*Completions*= window around.  This is because we cannot
+tell whether the user wanted to continue with a new completion upon
+returning to the buffer of origin or perform some other motion/command
+(in the minibuffer we can make that assumption because the minibuffer is
+purpose-specific, so for as long as it is active, the completion session
+goes on).  As such, ~completion-in-region~ must be restarted after cycling
+out of the =*Completions*=.
+
+To cancel in-buffer completion, type =C-g= either before switching to the
+Completions' buffer or while inside of it.
+
 * Installation
 :PROPERTIES:
 :CUSTOM_ID: h:1b501ed4-f16c-4118-9a4a-7a5e29143077
@@ -471,11 +512,12 @@ Everything is in place to set up the package.
 :END:
 #+cindex: Sample configuration
 
-Minimal setup:
+Minimal setup for the minibuffer and in-buffer completion:
 
 #+begin_src emacs-lisp
 (require 'mct)
 (mct-minibuffer-mode 1)
+(mct-region-mode 1)
 #+end_src
 
 And with more options:
@@ -524,9 +566,9 @@ And with more options:
 
 (mct-minibuffer-mode 1)
 
-;; Optionally add `mct-region-mode' to the major mode hooks you want it
-;; to be active in, or just use `mct-region-global-mode'.
-(mct-region-global-mode 1)
+;; Optionally use MCT for in-buffer completion (though `corfu' is a
+;; better option).
+(mct-region-mode 1)
 #+end_src
 
 Other useful extras from the Emacs source code (read their doc strings):
@@ -570,14 +612,18 @@ Other useful extras from the Emacs source code (read 
their doc strings):
 (setq savehist-save-minibuffer-history t)
 (add-hook 'after-init-hook #'savehist-mode)
 
+;;; Indentation and the TAB key
+(setq-default tab-always-indent 'complete) ; useful for `mct-region-mode'
+(setq-default tab-first-completion 'word-or-paren-or-punct) ; Emacs 27
+
 ;;; Extensions
 
 ;;;; Enable Consult previews in the Completions buffer.
-;; Requires the Consult package.
+;; Requires the `consult' package.
 (add-hook 'completion-list-mode-hook #'consult-preview-at-point-mode)
 
 ;;;; Setup for Orderless
-;; Requires the Orderless package
+;; Requires the `orderless' package
 
 ;; We make the SPC key insert a literal space and the same for the
 ;; question mark.  Spaces are used to delimit orderless groups, while