branch: externals/mct
commit 8a444a6b13d5e02a04f18153231b51d0400168fa
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@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
