#+TITLE: Change log of the Minibuffer and Completions in Tandem (mct)
#+AUTHOR: Protesilaos Stavrou
#+EMAIL: info@protesilaos.com
#+OPTIONS: ':nil toc:nil num:nil author:nil email:nil

This document contains the release notes that are included in each
tagged commit on the project's main git repository:
<https://gitlab.com/protesilaos/mct>.

The newest release is at the top.  For further details, please consult
the manual: <https://protesilaos.com/emacs/mct>.

* Version 0.4.0 on 2022-01-19
:PROPERTIES:
:CUSTOM_ID: h:1f8fc960-4e4b-4bb1-a1c4-5083f287a28c
:END:

This entry outlines the changes to the "Minibuffer and Completions in
Tandem" (=mct= package) since the release of [[#h:902574cf-edf0-4182-9d34-5e8e28730193][version 0.3.0 on 2021-11-19]].
There have been more than 120 commits in the meantime.

For further details, please consult the manual online:
<https://protesilaos.com/emacs/mct>.  Or evaluate the following
expression if you already have =mct= installed:

#+begin_src emacs-lisp
(info "(mct) Top")
#+end_src

As most changes pertain to optimisations in the code base, we limit this
log to what is of interest to the end-user.

** Minibuffer Confines Transcended (aka mct-region-mode)

Emacs distinguishes between two types of completion: one that involves
the minibuffer and another for text expansion inside regular buffers.
MCT has supported the former case since its inception, as hinted by its
original name ("Minibuffer and Completions in Tandem"), but would not
work as intended for in-buffer completion.

This changes with the introduction of a new global minor mode:
~mct-region-mode~.  What once was ~mct-mode~ is now defined as
~mct-minibuffer-mode~ to better denote the scope of the given
functionality.

With ~mct-region-mode~ enabled, users get a simplified subset of the
familiar MCT functionality when typing =TAB= or =C-M-i= to complete the
text-at-point in any major-mode that supports
~completion-at-point-functions~ (e.g. programming modes or Org).

~mct-region-mode~ is considered experimental and unstable.  Users are
encouraged to report any bugs as well as recommend ways to improve its
functionality or interaction model.  The manual has been updated to
cover all the relevant details.

Daniel Mendler, who is the developer of the =vertico= and =corfu= packages
(alternatives to ~mct-minibuffer-mode~ and ~mct-region-mode~, respectively),
was intstrumental in making ~mct-region-mode~ happen.  Daniel's patches
helped with everything from (i) the proper functioning of
~mct-region-mode~, (ii) the separation between ~mct-minibuffer-mode~ and
~mct-region-mode~, (iii) the overall setup of the minor modes, and (iv)
lots of other crucial details of the overall design of MCT.  In short:
there would be no ~mct-region-mode~ without Daniel's contributions.  Any
remaining errors or omissions are my own.

Given this new functionality, we can now joke that "MCT" stands for
"Minibuffer Confines Transcended".

* Version 0.3.0 on 2021-11-19
:PROPERTIES:
:CUSTOM_ID: h:902574cf-edf0-4182-9d34-5e8e28730193
:END:

This entry describes the changes to Minibuffer and Completions in Tandem
(mct) since the release of [[#h:4fab7648-d672-4af3-90b5-74242292f633][version 0.2.0 on 2021-11-12]].  There have been
more than 40 commits since then.  For further details, please consult
the manual online: <https://protesilaos.com/emacs/mct>.  Or evaluate
the following expression if you have the =mct= package installed:

#+begin_src emacs-lisp
(info "(mct) Top")
#+end_src

As this release is a continuation of version =0.2.0=, the changelog for
that version is also provided below (I released version =0.2.0= earlier
than anticipated so that users could get a stable package on GNU ELPA).
Here is a brief description of what has been achieved in =0.3.0=.

** MCT on Emacs 27
:PROPERTIES:
:CUSTOM_ID: h:c05100f7-a525-4d76-8f88-8de4cfe69e67
:END:

+ MCT now works on Emacs 27.  This was not possible in the past because
  ~mct-mode~ was originally designed to operate with the =one-column= style
  of the ~completions-format~, which was added in Emacs 28.  To make
  everything behave intuitively, several parts had to be abstracted and
  refactored (the changelog of version =0.2.0= (further below) covers
  everything not mentioned here).

+ The scenaria where the functionality was thoroughly tested involve all
  the available formats and cover commands that fulfil the following
  criteria:

  - Plain completion candidates, as in ~switch-to-buffer~.
  - Dynamic completion like that of ~find-file~.
  - Annotated candidates, as seen in ~describe-symbol~ for versions of
    Emacs 28 or higher.
  - Commands where candidates are grouped by heading, as done by various
    extensions of the =consult= package, such as ~consult-imenu~.
  - Commands where no completion category is associated with them.

+ The only change which is visible to the user is the implementation
  of a bespoke overlay to highlight the current candidate.  In
  previous versions, this was provided by the built-in ~hl-line-mode~,
  though that does not work as intended with either the =vertical= or
  =horizontal= layouts of the ~completions-format~ as it covers the whole
  line instead of the candidate at point.

+ The highlight extends to the edge of the window when the =one-column=
  format is used for the ~completions-format~ (Emacs 28 or higher).  In
  the other views it stretches from the beginning to the end of the
  completion candidate.

+ Thanks to Case Duckworth for the initial request and subsequent
  testing in issue 1: <https://gitlab.com/protesilaos/mct/-/issues/1>.

** Miscellaneous changes
:PROPERTIES:
:CUSTOM_ID: h:db448e8b-5416-4561-993a-4f5f3a8ad7e4
:END:

+ There is a new command that is active in the minibuffer which allows
  to complete and exit immediately: =C-RET= (~mct-complete-and-exit~).  This
  economises on key presses when all the user wants is to select the
  top-most candidate (or last highlighted one) without first switching
  to the Completions' buffer and then confirming it from there (=RET= in
  the =*Completions*= buffer completes and exits directly).

  - Thanks to José Antonio Ortega Ruiz for the contribution in merge
    requests 3 and 4 as discussed in issue 8:

    + <https://gitlab.com/protesilaos/mct/-/merge_requests/3>
    + <https://gitlab.com/protesilaos/mct/-/merge_requests/4>
    + <https://gitlab.com/protesilaos/mct/-/issues/8>

  - Note that "exit" in this context denotes the process of terminating
    the session while accepting the current input.  The term used to
    quit without accepting the input is "abort".

+ The ~mct-mode~ does not get activated in contexts where (i) the
  minibuffer is involved but (ii) no completion takes place.  For
  example, the ~eval-expression~ command (bound to =M-:= by default).

+ ~mct-mode~ no longer remaps the faces of the ~display-line-numbers-mode~.
  This was a useful experiment from the early days of the code base,
  although it is bad practice for a user-facing package.

+ Various tweaks and refinements to the manual.

+ Retroactive introduction of a CHANGELOG.org file and coverage of all
  noteworthy changes hitherto.

* Version 0.2.0 on 2021-11-12
:PROPERTIES:
:CUSTOM_ID: h:4fab7648-d672-4af3-90b5-74242292f633
:END:

This entry describes the changes to Minibuffer and Completions in Tandem
(mct) since the release of [[#h:a4b2152a-96e2-46fc-b9e0-ba223028118f][version 0.1.0 on 2021-10-22]].  There have been
70 commits since then.  For further details, please consult the manual
online: <https://protesilaos.com/emacs/mct>.  Or evaluate the following
expression if you have the =mct= package installed:

#+begin_src emacs-lisp
(info "(mct) Top")
#+end_src

** Packaged version of MCT
:PROPERTIES:
:CUSTOM_ID: h:0fb1fb23-636f-41f3-97bf-880d83ac42e0
:END:

=mct= is now available on the official GNU ELPA archive for users of Emacs
version 28 or higher.  One can install the package without any further
configuration.  The following commands shall suffice:

#+begin_src
M-x package-refresh-contents
M-x package-install RET mct
#+end_src

** Changes to the format and placement of the Completions
:PROPERTIES:
:CUSTOM_ID: h:97eba994-45ad-4f86-945f-a60772f764b5
:END:

+ The user option ~mct-live-completion~ controls how and when the
  Completions' buffer should be placed in a window and be updated live
  in response to user feedback.  Copying from the doc string:

  #+begin_quote
  mct-live-completion is a variable defined in ‘mct.el’.

  Its value is t

  Control auto-display and live-update of Completions' buffer.

  When nil, the user has to manually request completions, using the
  regular activating commands.  The Completions' buffer is never updated
  live to match user input.  Updating has to be handled manually.  This
  is like the out-of-the-box minibuffer completion experience.

  When set to the value =visible=, the Completions' buffer is live
  updated only if it is visible.  The actual display of the completions
  is still handled manually.  For this reason, the =visible= style does
  not read the =mct-minimum-input=, meaning that it will always try to
  live update the visible completions, regardless of input length.

  When non-nil (the default), the Completions' buffer is automatically
  displayed once the =mct-minimum-input= is met and is hidden if the
  input drops below that threshold.  While visible, the buffer is
  updated live to match the user input.

  Note that every function in the =mct-completion-passlist= ignores this
  option altogether.  This means that every such command will always
  show the Completions' buffer automatically and will always update its
  contents live.  Same principle for every function declared in the
  =mct-completion-blocklist=, which will always disable both the
  automatic display and live updating of the Completions' buffer.
  #+end_quote

  - Thanks to Jonathan Irving for the feedback in issue 4:
    <https://gitlab.com/protesilaos/mct/-/issues/4>.

+ As with all buffers, the placement of the =*Completions*= can be
  controlled with the ~display-buffer~ machinery.  The default is to show
  the completions at the bottom of the frame, though users can easily
  move it to, say, the left side window.  The doc string of the user
  option ~mct-display-buffer-action~ explains how to do so.

  - Thanks to Philip Kaludercic for the initial implementation in commit
    =436b24e= (was sent via email as a patch).

  - Thanks to Kostadin Ninev for reporting a bug where the Completions'
    buffer would proliferate during completion:
    <https://gitlab.com/protesilaos/mct/-/issues/3>.  It was fixed by
    Philip Kaludercic in commit =51c1e17=.

+ MCT now supports all the available styles of the ~completions-format~,
  whereas the original design was only meant to work with the value
  =one-column=, which was introduced in Emacs 28.  The user option is
  ~mct-completions-format~.  If that variable is set with ~setq~, the
  ~mct-mode~ has to be restarted manually for changes to take effect
  (setting the variable through ~customize-set-variable~ (and related)
  handles the mode reloading automatically).

  - Thanks to Philip Kaludercic for the patch in commit =b392b0b=.

  - Several changes were then made to ensure that the cyclic motions
    that move between the =*Completions*= and the minibuffer work
    intuitively in a grid view.  In short: =C-n=, =C-p= or the down/up arrow
    keys, perform a vertical motion, while the left/right arrow keys
    move laterally.  Prior to those changes, =C-n= or down arrow as well
    as =C-p= or up arrow, would perform a lateral motion as that is
    internally the meaning of the next/previous completion candidate.

  - The command ~mct-choose-completion-number~ was updated to throw a user
    error when a grid view is active.  That is because it is designed to
    jump to a given line number, which only works as intended when there
    is only one candidate per line. (Perhaps a future release should
    overlay characters over candidates in the grid view to select them
    directly.)

+ The ~mct-mode~ no longer sets the =completions-detailed= variable.  That
  is a matter of user preference.  It is not integral to the
  functionality of MCT.

** Group motions
:PROPERTIES:
:CUSTOM_ID: h:5f9027f9-fad0-4c03-8269-60eb670d0b38
:END:

+ Emacs 28 provides infrastructure for commands to group candidates
  based on their contents.  These groups can have their own heading in
  the Completions' buffer, as well as a separator.  Overall, it makes
  things look more organised.  The commands ~mct-next-completion-group~
  and ~mct-previous-completion-group~ move between those headings.  While
  in the =*Completions*= buffer, they are bound to =M-n= and =M-p=,
  respectively.  Thanks to James Norman Vladimir Cash for the
  contribution in merge request 2:
  <https://gitlab.com/protesilaos/mct/-/merge_requests/2>.

** Miscellaneous changes
:PROPERTIES:
:CUSTOM_ID: h:ed67abef-dad3-4620-bc70-1c3dc268db59
:END:

+ The =TAB= key in the Completions' buffer never exits the minibuffer (the
  command is ~mct-choose-completion-no-exit~).  Instead, it expands the
  current candidate in the minibuffer and switches focus to it.  Before,
  this behaviour would only happen in ~find-file~ and related prompts, but
  consistency/predictability is better.

  [ By contrast, =RET= (~mct-choose-completion-exit~) in the Completions
    buffer always exits with the candidate at point. ]

  Note that in this context "exit" means to close the session and accept
  the current input.

+ There is a new heuristic to deal with commands that ~let~ bind the
  ~crm-separator~ (e.g. ~org-set-tags-command~ sets the separator to =:=).
  This is used to make =M-RET= (~mct-choose-completion-dwim~) in the
  Completions buffer work in all ~completing-read-multiple~ contexts.
  Thanks to James Norman Vladimir Cash for contributing the heuristic in
  merge request 1:
  <https://gitlab.com/protesilaos/mct/-/merge_requests/1>.

+ The aforementioned =M-RET= command used to have the same effect as =RET=
  when not in a ~completing-read-multiple~ prompt ("CRM prompt").  This
  has now been revised to behave like =TAB= instead (as described further
  above), which is consistent with the ordinary behaviour of =M-RET= in
  CRM prompts where it appends the candidate at point to the minibuffer
  without exiting.

+ The check for ~display-line-numbers-mode~ tests whether it is bound,
  thus avoiding possible errors.  Thanks to Philip Kaludercic for the
  patch in commit =6bd2457=.

+ Made several improvements to doc strings and various snippets of code.

** Updates to the manual
:PROPERTIES:
:CUSTOM_ID: h:19c69838-c480-4b98-80e3-da25642a2c23
:END:

+ All of the aforementioned were documented, where appropriate.
+ A Makefile is now on offer, which is used to generate the mct.info and
  mct.texi files.  Thanks to Philip Kaludercic for the patch in commit
  =295bac0=.
+ A sample setup is available for =mct= as well as several built-in
  options pertaining to the minibuffer.
+ There are sections about third-party extensions as well as one that
  describes alternatives to MCT.  Thanks to Manuel Uberti for the
  feedback in issue 5: <https://gitlab.com/protesilaos/mct/-/issues/5>.
+ The "Acknowledgements" section includes the names of people who have
  contributed to the project in one way or another (code, ideas, user
  feedback, ...).

* Version 0.1.0 on 2021-10-22
:PROPERTIES:
:CUSTOM_ID: h:a4b2152a-96e2-46fc-b9e0-ba223028118f
:END:

Initial release.  The mct.el file derived from the now-deprecated
prot-minibuffer.el (part of [[https://gitlab.com/protesilaos/dotfiles][my dotfiles]]), which I had been using for
more than six months full time.
