<p>Below are the release notes. If you have no idea what <code>mct</code> is, it is a very thin layer of interactivity on top of the default completion user interface. Watch the <a href="https://protesilaos.com/codelog/2021-10-22-emacs-mct-demo/">video demo of the initial release</a>.</p> <h2>Version 0.3.0 on 2021-11-19</h2> <p>This entry describes the changes to Minibuffer and Completions in Tandem (mct) since the release of <a href="https://protesilaos.com/codelog.xml#h:4fab7648-d672-4af3-90b5-74242292f633">version 0.2.0 on 2021-11-12</a>. There have been more than 40 commits since then. For further details, please consult the manual online: <a href="https://protesilaos.com/emacs/mct">https://protesilaos.com/emacs/mct</a>. Or evaluate the following expression if you have the <code>mct</code> package installed:</p> <pre><code>(info "(mct) Top") </code></pre> <p>As this release is a continuation of version <code>0.2.0</code>, the changelog for that version is also provided below (I released version <code>0.2.0</code> 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 <code>0.3.0</code>.</p> <h3>MCT on Emacs 27</h3> <ul> <li> <p>MCT now works on Emacs 27. This was not possible in the past because <code>mct-mode</code> was originally designed to operate with the <code>one-column</code> style of the <code>completions-format</code>, which was added in Emacs 28. To make everything behave intuitively, several parts of the code had to be abstracted and refactored (the changelog of version <code>0.2.0</code> (further below) covers everything not mentioned here).</p> </li> <li>The scenaria where the functionality was thoroughly tested involve all the available formats and cover commands that fulfil the following criteria: <ul> <li>Plain completion candidates, as in <code>switch-to-buffer</code>.</li> <li>Dynamic completion like that of <code>find-file</code>.</li> <li>Annotated candidates, as seen in <code>describe-symbol</code> for versions of Emacs 28 or higher.</li> <li>Commands where candidates are grouped by heading, as done by various extensions of the <code>consult</code> package, such as <code>consult-imenu</code>.</li> <li>Commands where no completion category is associated with them.</li> </ul> </li> <li> <p>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 <code>hl-line-mode</code>, though that does not work as intended with either the <code>vertical</code> or <code>horizontal</code> layouts of the <code>completions-format</code> as it covers the whole line instead of the candidate at point.</p> </li> <li> <p>The highlight extends to the edge of the window when the <code>one-column</code> format is used for the <code>completions-format</code> (Emacs 28 or higher). In the other views it stretches from the beginning to the end of the completion candidate.</p> </li> <li>Thanks to Case Duckworth for the initial request and subsequent testing in issue 1: <a href="https://gitlab.com/protesilaos/mct/-/issues/1">https://gitlab.com/protesilaos/mct/-/issues/1</a>.</li> </ul> <h3>Miscellaneous changes</h3> <ul> <li>There is a new command that is active in the minibuffer which allows to complete and exit immediately: <code>C-RET</code> (<code>mct-complete-and-exit</code>). 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 (<code>RET</code> in the <code>*Completions*</code> buffer completes and exits directly). <ul> <li>Thanks to José Antonio Ortega Ruiz for the contribution in merge requests 3 and 4 as discussed in issue 8: <ul> <li><a href="https://gitlab.com/protesilaos/mct/-/merge_requests/3">https://gitlab.com/protesilaos/mct/-/merge_requests/3</a></li> <li><a href="https://gitlab.com/protesilaos/mct/-/merge_requests/4">https://gitlab.com/protesilaos/mct/-/merge_requests/4</a></li> <li><a href="https://gitlab.com/protesilaos/mct/-/issues/8">https://gitlab.com/protesilaos/mct/-/issues/8</a></li> </ul> </li> <li>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”.</li> </ul> </li> <li> <p>The <code>mct-mode</code> does not get activated in contexts where (i) the minibuffer is involved but (ii) no completion takes place. For example, the <code>eval-expression</code> command (bound to <code>M-:</code> by default).</p> </li> <li> <p><code>mct-mode</code> no longer remaps the faces of the <code>display-line-numbers-mode</code>. This was a useful experiment from the early days of the code base, although it is bad practice for a user-facing package.</p> </li> <li> <p>Various tweaks and refinements to the manual.</p> </li> <li>Retroactive introduction of a CHANGELOG.org file and coverage of all noteworthy changes hitherto.</li> </ul> <p><a id="h:4fab7648-d672-4af3-90b5-74242292f633"></a></p> <h2>0.2.0 on 2021-11-12</h2> <p>This entry describes the changes to Minibuffer and Completions in Tandem (mct) since the release of version 0.1.0 on 2021-10-22. There have been 70 commits since then. For further details, please consult the manual online: <a href="https://protesilaos.com/emacs/mct">https://protesilaos.com/emacs/mct</a>. Or evaluate the following expression if you have the <code>mct</code> package installed:</p> <pre><code>(info "(mct) Top") </code></pre> <h3>Packaged version of MCT</h3> <p><code>mct</code> 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:</p> <pre><code>M-x package-refresh-contents M-x package-install RET mct </code></pre> <h3>Changes to the format and placement of the Completions</h3> <ul> <li> <p>The user option <code>mct-live-completion</code> 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:</p> <blockquote> <p>mct-live-completion is a variable defined in ‘mct.el’.</p> <p>Its value is t</p> <p>Control auto-display and live-update of Completions’ buffer.</p> <p>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.</p> <p>When set to the value <code>visible</code>, 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 <code>visible</code> style does not read the <code>mct-minimum-input</code>, meaning that it will always try to live update the visible completions, regardless of input length.</p> <p>When non-nil (the default), the Completions’ buffer is automatically displayed once the <code>mct-minimum-input</code> is met and is hidden if the input drops below that threshold. While visible, the buffer is updated live to match the user input.</p> <p>Note that every function in the <code>mct-completion-passlist</code> 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 <code>mct-completion-blocklist</code>, which will always disable both the automatic display and live updating of the Completions’ buffer.</p> </blockquote> <ul> <li>Thanks to Jonathan Irving for the feedback in issue 4: <a href="https://gitlab.com/protesilaos/mct/-/issues/4">https://gitlab.com/protesilaos/mct/-/issues/4</a>.</li> </ul> </li> <li>As with all buffers, the placement of the <code>*Completions*</code> can be controlled with the <code>display-buffer</code> 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 <code>mct-display-buffer-action</code> explains how to do so. <ul> <li> <p>Thanks to Philip Kaludercic for the initial implementation in commit <code>436b24e</code> (was sent via email as a patch).</p> </li> <li> <p>Thanks to Kostadin Ninev for reporting a bug where the Completions’ buffer would proliferate during completion: <a href="https://gitlab.com/protesilaos/mct/-/issues/3">https://gitlab.com/protesilaos/mct/-/issues/3</a>. It was fixed by Philip Kaludercic in commit <code>51c1e17</code>.</p> </li> </ul> </li> <li>MCT now supports all the available styles of the <code>completions-format</code>, whereas the original design was only meant to work with the value <code>one-column</code>, which was introduced in Emacs 28. The user option is <code>mct-completions-format</code>. If that variable is set with <code>setq</code>, the <code>mct-mode</code> has to be restarted manually for changes to take effect (setting the variable through <code>customize-set-variable</code> (and related) handles the mode reloading automatically). <ul> <li> <p>Thanks to Philip Kaludercic for the patch in commit <code>b392b0b</code>.</p> </li> <li> <p>Several changes were then made to ensure that the cyclic motions that move between the <code>*Completions*</code> and the minibuffer work intuitively in a grid view. In short: <code>C-n</code>, <code>C-p</code> or the down/up arrow keys, perform a vertical motion, while the left/right arrow keys move laterally. Prior to those changes, <code>C-n</code> or down arrow as well as <code>C-p</code> or up arrow, would perform a lateral motion as that is internally the meaning of the next/previous completion candidate.</p> </li> <li> <p>The command <code>mct-choose-completion-number</code> 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.)</p> </li> </ul> </li> <li>The <code>mct-mode</code> no longer sets the <code>completions-detailed</code> variable. That is a matter of user preference. It is not integral to the functionality of MCT.</li> </ul> <h3>Group motions</h3> <ul> <li>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 <code>mct-next-completion-group</code> and <code>mct-previous-completion-group</code> move between those headings. While in the <code>*Completions*</code> buffer, they are bound to <code>M-n</code> and <code>M-p</code>, respectively. Thanks to James Norman Vladimir Cash for the contribution in merge request 2: <a href="https://gitlab.com/protesilaos/mct/-/merge_requests/2">https://gitlab.com/protesilaos/mct/-/merge_requests/2</a>.</li> </ul> <h3>Miscellaneous changes</h3> <ul> <li> <p>The <code>TAB</code> key in the Completions’ buffer never exits the minibuffer (the command is <code>mct-choose-completion-no-exit</code>). Instead, it expands the current candidate in the minibuffer and switches focus to it. Before, this behaviour would only happen in <code>find-file</code> and related prompts, but consistency/predictability is better.</p> <p>[ By contrast, <code>RET</code> (<code>mct-choose-completion-exit</code>) in the Completions buffer always exits with the candidate at point. ]</p> <p>Note that in this context “exit” means to close the session and accept the current input.</p> </li> <li> <p>There is a new heuristic to deal with commands that <code>let</code> bind the <code>crm-separator</code> (e.g. <code>org-set-tags-command</code> sets the separator to <code>:</code>). This is used to make <code>M-RET</code> (<code>mct-choose-completion-dwim</code>) in the Completions buffer work in all <code>completing-read-multiple</code> contexts. Thanks to James Norman Vladimir Cash for contributing the heuristic in merge request 1: <a href="https://gitlab.com/protesilaos/mct/-/merge_requests/1">https://gitlab.com/protesilaos/mct/-/merge_requests/1</a>.</p> </li> <li> <p>The aforementioned <code>M-RET</code> command used to have the same effect as <code>RET</code> when not in a <code>completing-read-multiple</code> prompt (“CRM prompt”). This has now been revised to behave like <code>TAB</code> instead (as described further above), which is consistent with the ordinary behaviour of <code>M-RET</code> in CRM prompts where it appends the candidate at point to the minibuffer, without exiting.</p> </li> <li> <p>The check for <code>display-line-numbers-mode</code> tests whether it is bound, thus avoiding possible errors. Thanks to Philip Kaludercic for the patch in commit <code>6bd2457</code>.</p> </li> <li> <p>Made several improvements to doc strings and various snippets of code.</p> </li> </ul> <h3>Updates to the manual</h3> <ul> <li>All of the aforementioned were documented, where appropriate.</li> <li>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 <code>295bac0</code>.</li> <li>A sample setup is available for <code>mct</code> as well as several built-in options pertaining to the minibuffer.</li> <li>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: <a href="https://gitlab.com/protesilaos/mct/-/issues/5">https://gitlab.com/protesilaos/mct/-/issues/5</a>.</li> <li>The “Acknowledgements” section includes the names of people who have contributed to the project in one way or another (code, ideas, user feedback, …).</li> </ul>