Kristoffer Balintona — #Emacs

Surprisingly, Emacs on Android is pretty good

Thu, 29 May 2025 19:38:00 GMT

The good and bad: what to expect on Android
Installation
- Option 1
- Option 2 (recommended)
Configuring an Android-specific Emacs
Conclusion
- Bonus: My wish list

Recently I got around to making steps toward a better mobile-PC workflow. Until now, I’ve pretty much exclusively been using the community-developed orgzly-revived app on Android. My intention was to use orgzly-revived for simple todo management and another app for more note-taking purposes—but I could never find another app I was happy with on Android. But I happened to remember reading good things about the native Emacs app on Android a few months ago. So I tried it out… and was immediately sold!

The good and bad: what to expect on Android §

First, let’s make sure our expectations are tempered: Emacs on Android won’t be as pleasant as the full desktop experience.^[1] Of course. A phone’s screen is tiny, and unless you have a physical keyboard connected, you’ll have to manage with a virtual one (see Use a Special virtual keyboard). On top of that:

Tooling: To have non-Emacs programs available, you have to install Emacs in a particular way with Termux to expose Termux’s binaries to Emacs. (See the recommended way to install Emacs.) The initial set up is longer, but it’s worth it.
File paths: Android “sandboxes” each app. You can think of each app having their own “section” of the file system that they can read or write to (unless they are given explicit access to that outside directory; see info "(emacs) Android Document Providers"). As such, one finds themselves fiddling with the obnoxiously long Android file paths if they want to, for instance, access their notes directory that is outside the Emacs app sandbox.^[2] This is a minor inconvenience though.
Writing to the file system: Relatively speaking, writing to the file system can be long sometimes. Not too long, but long nonetheless, As far as I’ve experienced, this has only been the case when saving files that are outside the Emacs sandbox.

So, really, the situation is pretty good!

And finally: YMMV on other Android devices. My current phone is the OnePlus 7 Pro running Android version 12.

Installation §

Option 1 §

The first option is as easy as it can get, but you won’t have a way to access other CLI tools:

Download the F-droid app store. For the layperson who doesn’t know what it is: it’s basically an alternative to the Play Store. Some apps that can’t be on the Play Store (fact check, maybe link tk) are there.
Download the Emacs app.
Open Emacs! The version of Emacs as I write this that is available is Emacs 30.1.

Using Emacs this way is totally possible if all you need is elisp. But if you need other tools, like git, I recommend the second way to install Emacs.

Option 2 (recommended) §

This option makes other CLI tools accessible to the Emacs Android application container. It is a little bit more of a hassle.

The method is outlined in this SourceForge repository. In essence, inside the termux/ directory of this SourceForge repository are modified Emacs .apk files. These .apk files allow the Emacs app container to access the Termux (explain what Termux is tk) app container, meaning the CLI tools installed with Termux will become accessible to Emacs. But the installation is specific; read the instructions detailed inside that repository. I will outline them briefly below, but be careful if you are reading this in the future, for the instructions could have changed relevantly.

In short,

Delete any existing Emacs or Termux apps.
Ensure you have enabled the setting that allows you to install third-party apps (i.e., non-Play Store apps) on your phone.
Install Termux. Don’t open Termux yet.
Select the .apk file appropriate to your phone. There are various .apk files for different versions of Emacs and devices.
Install Emacs through this .apk. (If your phone refuses to install the .apk, you might have selected the wrong type of .apk file for your device. So try different .apk files for the same Emacs version.)
In Termux, run pkg update && pkg upgrade. Say “yes” to each of the prompts.
Open Emacs.

Create a ~/.emacs.d/early-init.el and place the following inside of it:

(setenv "PATH" (format "%s:%s" "/data/data/com.termux/files/usr/bin"
                       (getenv "PATH")))
(push "/data/data/com.termux/files/usr/bin" exec-path)

And you’re done! Programs installed through Termux will be made accessible to Emacs.

Configuring an Android-specific Emacs §

Necessary reading: the manual §

Chances are that you don’t know that the Emacs manual has its own section for the Android system: (info "(emacs) Android"). Before anything, I highly recommend you peruse this section, returning to and reading more deeply specific parts as you see fit. In particular, I found the following Info nodes essential:

(info "(emacs) Android File System") (This one is particularly important if you wan to understand what the ~/ path means for Emacs.)
(info "(emacs) Android Document Providers")
(info "(emacs) Android Fonts")
(info "(emacs) Android Windowing")

A lot of the information here is found directly inside these Info pages.

Additionally, I also think reading about Emacs’ facilities for touchscreens and virtual keyboards (bet you didn’t know this was in the manual either!) is essential: (info "(emacs) Other Input").

Moments like these are truly a testament to Emacs’ dedication to an accessible editor.

How to configure your `init.el` on a mobile device? §

Later I’ll explain how you make typing code on a touchscreen device easier by installing a handy virtual keyboard. But I highly recommend that until you’ve settled on a configuration you’re willing to type out that you heavily utilize the customize interface. This means accessing the Customize interfaces via the tool-bar^[3] buttons then using your touchscreen to tap the buttons available in customize-mode buffers. (Then, if you prefer, after setting many options with Customize, you can refactor the options Customize put in your init.el into e.g. use-package forms.)

If you haven’t used Customize much before, you can check out the available Customize commands via C-h a (apropos-command), search for “customize.” The most useful commands are:

customize-group,
customize-option,
customize-face,

First step: A Better UI for touchscreens §

The very first thing I did when I opened Emacs was enable these minor modes:

modifier-bar-mode
tool-bar-mode

and set tool-bar-position to ‘bottom, placing it closer to where my fingers and the virtual keyboard are.

Desktop users might have disabled these years ago in favor of keyboard-centric workflow, but they are awesome for touchscreens in my opinion.

Android-specific Commands and Options §

There are a few built-in Android commands and options you should be aware of. (Pro tip: one can M-x Info-index or press i in the Emacs Info manual, itself accessible via C-h r, or M-x info-emacs-manual, then search for the string “android” to find all the specific mentions off “Android.”)

Commands:
- android-request-directory-access to request access to file paths of other apps^[4]
- and its inverse, android-relinquish-directory-access.
Options:
- android-pass-multimedia-buttons-to-system,
- android-intercept-control-space,
- touch-screen-display-keyboard,
- (and more not useful to me).

Also, don’t forget to let Emacs display over other apps. This is a device setting, not an Emacs one.

Use a Special virtual keyboard §

Unless you have a physical keyboard connected to your mobile device, typing will be a pain. For that, we install a virtual keyword that gives us easier access to modifier keys, function keys, arrow keys, and symbols. As far as I know, there are currently two main options:

Hacker’s Keyboard, available in F-Droid.
Unexpected Keyboard, available in the Play Store.

Having briefly tried both, I personally prefer the latter. Though the former works just fine if you like it.

Fonts §

You might want a set of fonts not already installed on your Android system. If that’s the case, you should read the (info "(emacs) Android Fonts") manual page.

That page explains that if you want to install fonts for your user (in the Emacs app container), you should place them in ~/fonts/.^[5] Getting those fonts was somewhat cumbersome for me: I had to manually download them, unzip them with Termux, place them inside a directory Emacs had access to (see Android-specific Commands and Options), then copy them to ~/fonts/.

Note: in my experience, fonts are not recursively checked inside this directory. That is, you should place your e.g. .ttf files inside that folder, not any subdirectories.

Tip: You can remap the volume buttons §

Volume buttons are un-mapped by default (see android-pass-multimedia-buttons-to-system). That’s find with me, but if you feel inclined, you can rebind them to something else after setting android-pass-multimedia-buttons-to-system appropriately. Some possibilities would be for navigation between headings, tk list more.

Conclusion §

In conclusion,

Make heavy use of the Customize interface. (At least initially—after you’re comfy in Emacs, you can refactor it into a form more familiar to a desktop init.el.)
Enable minor modes and options specific to touchscreen-driven usage.
Install a virtual keyboard to get access to modifiers, function keys, and more.

Right now I’ve achieved a set up I’m happy with. I migrated the portions of my configuration relevant to org, org-capture, and org-node, but in the future if I need more from Emacs-on-mobile, I’ll look to expand my config as necessary. (This includes version-controlling my init.el.)

And finally: YMMV on other Android devices. My current phone is the OnePlus 7 Pro running Android version 12.

Bonus: My wish list §

Touchscreen gestures: There is the built-in strokes.el, but strokes.el, as far as I can tell, does not work for touchscreens. Additionally, significant changes would be required to its code base to make it compatible for touchscreens. So, for now, we have to settle with virtual keyboards…
Automatic keyboard/IME switching: Ideally, I’d have my special virtual keyboard be automatically selected using Emacs and deselected when not using Emacs. Right now, I have to manually switch to it. As far as I know, there is no easy way to accomplish this.
Larger tool bar and menu bar: The tool bar and menu bar are useful, but they’re also small. I wish they were larger and easier to tap.

Keeping a tidy .emacs.d/ with no-littering.el

Mon, 21 Apr 2025 00:34:00 GMT

No-littering.el keeps your .emacs.d clean. I’ve been using it for years—in fact it’s one of the only third-party packages I first installed several years ago when I started using Emacs that I still have in my config today.

It establishes conventions for keeping files created from packages:

The no-littering-etc-directory. The directory where packages place their configuration files.
The no-littering-var-directory. The directory where packages place their persistent data files.

If every package followed this convention, then no files should litter (pun intended) your emacs configuration directory. Unfortunately, not every package does… fortunately, no-littering already sets the relevant option of dozens of packages to use these directories. But if you use a package that isn’t already set, you can easily use no-littering-expand-var-file-name and no-littering-expand-etc-file-name to change that. For example: (setopt cursory-latest-state-file (no-littering-expand-var-file-name "cursory/cursory-latest-state")) sets cursory-latest-state-file to ~/.emacs.d/var/cursory/cursory-latest-state.

Here’s a look at my own directories.

My no-littering-etc-directory, located at ~/.emacs.d/etc/:

$ tree -L 1
.
├── abbrev.el
├── custom.el
├── gnus
└── transient

3 directories, 2 files

My no-littering-var-directory, located at ~/.emacs.d/var/:

$ tree -L 1
.
├── abbrev-mode
├── amx-save.el
├── anaconda-mode
├── annotations.el
├── auto-save
├── backup
├── bookmark-default.el
├── citre
├── company
├── cursory
├── dap
├── dape-adapters
├── desktop
├── devdocs
├── diary
├── eaf
├── eafpdf
├── eglot-java
├── elfeed
├── emacs-gc-stats.eld.gz
├── emms
├── emojify
├── erc
├── eshell
├── eww
├── flycheck
├── fontaine
├── fontaine-latest-state.eld
├── forge
├── gamegrid-user-score
├── gdb-bp-session
├── .gitignore
├── .gitmodules
├── gnus
├── helm
├── ielm-history.eld
├── image-dired
├── irony
├── ispell
├── keyfreq.el
├── languagetool
├── ledger
├── logview-cache
├── lsp
├── mc-list.el
├── multisession
├── newsticker
├── nov-save-place.el
├── nsm-settings.el
├── org
├── org-remark
├── persist
├── popweb
├── prescient-save.el
├── projectile
├── project-list.el
├── project-x
├── psession
├── racket-mode
├── recentf-save.el
├── request
├── savehist.el
├── save-place.el
├── semantic
├── shadow
├── speed-type
├── spell-fu
├── srecode-map.el
├── svg-lib
├── tempel-templates
├── tramp
├── transient
├── trash
├── treemacs
├── treesit
├── tree-sitter
├── type-break.el
├── undohist
├── url
├── vimish-fold
└── wombag

60 directories, 22 files

Without no-littering, I would either (i) have a ton of directories in my .emacs.d or (ii) have to define my own variables whose values are directories and manually, whenever I install a new package, set their options to write their files into these directories—basically what no-littering already does but without no-littering’s existing integrations. This way, my Emacs directory is neater.

Bonus: `(no-littering-theme-backups)` §

No-littering also provides the little-known no-littering-theme-backups. The TL;DR is this: this function makes Emacs’s built-in auto-saving and backing up functions create files within no-littering’s directories so that sensitive data is not written to disk in unsecured locations. Calling this function sets the value of three variables:

auto-save-file-name-transforms: Transforms to apply to buffer file name before making auto-save file name.
backup-directory-alist: Similar to auto-save-file-name-transforms but for backup files.
undo-tree-history-directory-alist (from undo-tree): Similar to auto-save-file-name-transforms but for backup files.

Its docstring elaborates the mechanism and purpose of this function in greater depth:

no-littering-theme-backups is an autoloaded native-comp-function in
no-littering.el.

(no-littering-theme-backups)

Theme locations where backups of various sorts are created.

The purpose of this package is to store data files of various
sorts in a handful of central locations, instead of spreading
them all over the place.  When doing that for temporary files,
which contain backups of some sort, that increases the odds that
sensitive data is written to disk in clear text and/or that such
clear text files persist longer, if they would be created anyway.

Because of that, simply loading ‘no-littering’ does not theme
certain, potentially unsafe variables.  Instead, this function is
provided, so that you can decide whether to take the risk or not.

Calling this function sets these variables:
- auto-save-file-name-transforms (built-in)
- backup-directory-alist (built-in)
- undo-tree-history-directory-alist (from ‘undo-tree’)

The default values of these variables cause additional files to
be created in the same directories as the files that are being
visited.  Calling this function changes the values of these
variables, so that this is only done for visited files located in
certain directories.  For all other visited files, the additional
files are created in files inside no-littering-var-directory.

Additional files are created in the same directory as the visited
file, for files located in:
- "/tmp/"
- "/dev/shm"
- temporary-file-directory

With these settings it is still possible that sensitive data is
written to additional files, but you are more likely to spot it,
and because these directories usually use a ‘tmpfs’ file-system,
the leaked secrets should not persist after a reboot.

If you do *not* call this function, then these additional files
are always created in the same directory as the visited files,
regardless of the location of the visited files.  In other words,
even when using the default values, there is a significant risk
of leaking sensitive data, and if you want to reduce that, then
you must turn of these features completely.

Complement corfu, vertico, and completion-preview with prescient.el sorting

Sat, 05 Apr 2025 14:23:00 GMT

Apr 7, 2025 With several commits made on April 6, 2025, vertico spun off its sorting functionality into an extension: vertico-sort. As explained in vertico-sort.el’s commentary section, it includes a new feature: when history-delete-duplicates is nil, all sorting functions defined in vertico-sort.el now rank recently selected candidates above frequently selected candidates. This approximates the sorting strategy of prescient.el. I think I’ll stick with prescient.el sorting because I like history-delete-duplicates set to non-nil, but try it out yourself!

Apr 22, 2025 Corfu now offers a similar functionality as vertic-sort does for vertico with the new corfu-sort extension. Like vertico-sort, corfu-sort requires history-delete-duplicates to be nil.

Prescient.el is a package that was popular during the era of ivy and helm. Nowadays, I don’t see it mentioned much because of the very popular corfu + vertico + marginalia + orderless combination which enhance built-in Emacs completion and overtaken ivy and helm in terms of popularity. (And it’s deserved! I use this combination, too.)^[1] But I’ve found prescient.el a noticeable convenience that complements this set of packages.

The reason is prescient.el’s sorting. Roughly, we can think of completion as having two halves: filtering and sorting. Filtering is what completion-styles does: among the generated completion candidates, which are shown to the user? Sorting is the order in which the filtered candidates are shown. One might think that orderless, which is filters candidates with its completion-style, also sorts candidates—but it doesn’t. As explained in the orderless README:

The prescient.el library also provides matching of space-separated components in any order. It offers a completion-style that can be used with Emacs’ default completion UI, Mct, Vertico or with Icomplete. Furthermore Ivy is supported. The components can be matched literally, as regexps, as initialisms or in the flex style (called “fuzzy” in prescient). Prescient does not offer the same flexibility as Orderless with its style dispatchers. However in addition to matching, Prescient supports sorting of candidates, while Orderless leaves that up to the candidate source and the completion UI.

As such, in the corfu + vertico + marginalia + orderless world, vertico (for minibuffer completions) and corfu (for in-inline completions) are responsible for sorting candidates.

The problem is this: although orderless brilliantly narrows down candidates, both vertico and corfu have somewhat naive sorting algorithms (see vertico-sort-function and corfu-sort-function). Vertico offers vertico-sort-history-alpha and vertico-sort-history-length-alpha, and corfu offers corfu-history-mode. In my limited experience, however, I give prescient.el’s sorting algorithm an edge to both. (YMMV—feel free to try them!) Oftentimes vertico and corfu will consistently show the candidate you have in mind later in the list. This tends to be the case when using certain common commands and certain completion-at-point-functions: I would common seek out certain candidates that orderless would place third or fourth in the list.

Prescient.el almost entirely solved this issue for me. Prescient.el offers a completion-style—this is its filtering functionality—but it also offers sorting functionality. The sorting functionality is what’s relevant here:

When sorting, the last few candidates you selected are displayed first, followed by the most frequently selected ones, and then the remaining candidates are sorted by length.

Prescient.el is the core package, and there are several auxiliary packages to integrate prescient with vertico, corfu, and others. We can enable prescient’s sorting for vertico and corfu (but not its filtering; I want to leave this to orderless) with something like the following:

;; Core package
(use-package prescient
  :custom
  ;; My settings for relevant user options:
  ;; (prescient-aggressive-file-save t)
  ;; (prescient-sort-length-enable nil)
  ;; (prescient-sort-full-matches-first t)
  ;; (prescient-history-length 200)
  ;; (prescient-frequency-decay 0.997)
  ;; (prescient-frequency-threshold 0.05)
  :config
  ;; Optional: persist prescient statistics to an on-disk cache
  ;; (`prescient-save-file')
  (prescient-persist-mode 1))

;; Integration with corfu
(use-package corfu-prescient
  ;; The :after keyword defers loading this package, meaning this package is
  ;; only loaded until something else wants something from it.  If we want
  ;; `corfu-prescient-mode' to be enabled in the :config block, we need to
  ;; prevent deferral with the :demand keyword. In combination with our :after
  ;; block, the package is immediately loaded only after both corfu and
  ;; prescient are loaded.
  :demand t
  :after corfu prescient
  :custom
  ;; Sorting.  These are the default values but I include them here to be
  ;; explicit.
  (corfu-prescient-enable-sorting t)
  (corfu-prescient-override-sorting nil) ; Don't override `display-sort-function'

  ;; Filtering
  (corfu-prescient-enable-filtering nil) ; We want orderless to do the filtering
  ;; See also `corfu-prescient-completion-styles',
  ;; `corfu-prescient-completion-category-overrides' and
  ;; `prescient--completion-recommended-overrides'.  Those options apply only
  ;; when `corfu-prescient-enable-filtering' is non-nil.
  :config
  (corfu-prescient-mode 1))

;; Integration with vertico
(use-package vertico-prescient
  ;; The :after keyword defers loading this package, meaning this package is
  ;; only loaded until something else wants something from it.  If we want
  ;; `vertico-prescient-mode' to be enabled in the :config block, we need to
  ;; prevent deferral with the :demand keyword. In combination with our :after
  ;; block, the package is immediately loaded only after both vertico and
  ;; prescient are loaded.
  :demand t
  :after vertico prescient
  :custom
  ;; Sorting.  These are the default values but I include them here to be
  ;; explicit.
  (vertico-prescient-enable-sorting t)
  (vertico-prescient-override-sorting nil) ; Don't override `display-sort-function'

  ;; Filtering
  (vertico-prescient-enable-filtering nil) ; We want orderless to do the filtering
  ;; See also `vertico-prescient-completion-styles',
  ;; `vertico-prescient-completion-category-overrides', and
  ;; `prescient--completion-recommended-overrides'.  Those options apply only
  ;; when when `vertico-prescient-enable-filtering' is non-nil.
  :config
  (vertico-prescient-mode 1))

The result is using orderless for completion filtering and prescient for completion sorting everywhere—for in-line completions with corfu and minibuffer completions with vertico. With this, among the candidates filtered by orderless, the most recent and common ones will be bumped up to the beginning. Try it out!

Bonus: integration with `completion-preview-mode` §

Emacs 30.1 ships with the new completion-preview-mode. You can read about it in this blog post but also in the Emacs 30.1 news (i.e., C-u 30 C-h n). Apparently, completion-preview-mode has its own sorting function—which makes sense, since it isn’t hooked into either corfu nor vertico (which we set up to use prescient above). The relevant user option to modify its sorting is completion-preview-sort-function. So we just have to make sure that function matches prescient’s. We can do that like this:

(with-eval-after-load 'prescient
  ;; Have `completion-preview-mode' use prescient's sorting algorithm
  (setopt completion-preview-sort-function #'prescient-completion-sort))

But, if you also use corfu on top of completion-preview-mode, you’ll still notice a discrepancy between corfu’s first candidate and completion-preview’s candidate. They should be the same with the same sorting algorithm but they’re not! I’m not 100%, but I’m fairly confident that corfu-prescient keeps track of corfu-specific completion usage, which is separate from non-corfu-specific use. Consequently, the statistics used to sort candidates ends up different between corfu and prescient-completion-sort.

In any case, below is a simple fix that gets corfu and completion-preview on the same page:

;; We set completion-preview's sorting function
;; (`completion-preview-sort-function') to corfu's sorting function
;; (`corfu-sort-function').
(with-eval-after-load 'corfu
  (setopt completion-preview-sort-function corfu-sort-function))

;; Alternative: for a solution that ensures `completion-preview-sort-function'
;; always matches `corfu-sort-function', we can use a variable watcher.  This is
;; my preference.
;;
;; The below accounts for cases in which (i) the user has buffer-local values
;; for `corfu-sort-function' or (ii) the user changes the global value of
;; `corfu-sort-function' (e.g., from minor modes that disable/enable
;; functionality).  It is a robust solution, and although I have not tested its
;; performance overhead, it should cause no problems.
(add-variable-watcher 'corfu-sort-function
                      (lambda (_symbol newval operation where)
                        "Match the value of `completion-preview-sort-function' to `corfu-sort-function'.
If `corfu-sort-function' is set buffer-locally, also set
`completion-preview-sort-function' buffer-locally.  Otherwise, change
the default value of `completion-preview-sort-function' accordingly.

This action only applies when the value of `corfu-sort-function' is
set (i.e., OPERATION is \\='set).  This excludes, e.g., let bindings."
                        (when (equal operation 'set)
                          (if where
                              (with-current-buffer where
                                (setq-local completion-preview-sort-function newval))
                            (setopt completion-preview-sort-function newval)))))

Changelog §

Apr 7, 2025
- Fixed several typos.
- Added clarity to several phrases.
- Added a note mentioning the new vertico-sort extension.
Apr 5, 2025
- Correction to explanation according to r/JDRiverRun’s comment.
Apr 22, 2025
- Added a note mentioning the new corfu-history extension.

A surprising upside to vc-dir marks over magit

Wed, 27 Nov 2024 04:40:00 GMT

Vc.el is Emacs’s built-in interface for version control CLI tools. With respect to Git, magit has for several years now been the most favored (with respect to popularity) Git^[1] interface. At least in the r/emacs subreddit, magit is frequently considered a killer-feature—an irreplaceable feature unique to Emacs.

For the most part I am inclined to agree. However, in the last few months, I’ve been regularly experimenting using vc. This is in part motivated by recent improvements to vc’s implementation of Git, and another part motivated by a curiosity to see whether I’d end up enjoying some parts of the vc-way of doing things over the magit-way of doing things.^[2]

On such insight has been the surprising benefits of calling vc-dir instead of magit-status.

The nicety of `vc-dir` marks §

In magit-status, I would typically stage various files and hunks and commit them when ready. vc does not use Git’s “staging” concept (because not all version control systems use such a concept). So instead, to achieve something analogous, a user might call vc-dir (or, much more commonly for me, project-vc-dir), mark edited files (or entire directories!) using vc-dir-mark (m), and check out (commit) those changes via vc-next-action (v) or see a diff of those changes with vc-diff (=) and commit the changes in that diff-mode buffer (v).^[3]

A problem for the magit interface, however, is visual clarity when it comes to focusing on changes in a certain subset of files. For example, sometimes I am working with changes in files within a single directory alongside many other uncommitted changes elsewhere in the repository. To make a commit with magit, I would need to navigate past or fold changed hunks/files I want to ignore. With many unstaged changes this means many files to ignore. This leads to a significant reduction in visual clarity since I end up having to ignore more files than I’m currently working on.

There is a subtle solution in vc.el. The secret lies in the fact that marks, which can be used to selectively create diff buffers and commit changes from those buffers, are preserved in vc-dir buffers after changes are committed. A mark is only removed once the corresponding line is removed via something like vc-dir-hide-up-to-date (x) or vc-dir-kill-line (C-k). Marks are magical because they let me focus on the files relevant to my current work: I can mark the files and directories I am focusing on then call vc-next-action in the vc-dir buffer to commit changes only in those files and directories (or, if I want to be selective about the hunks I commit: first call vc-diff to see the diff of just the marked files, kill/remove the hunks I don’t want to commit, then vc-next-action).Then I can write more changes and make more commits in the same way. (Furthermore, while this vc workflow might seem like it would necessarily involve many more keystrokes, I found this not to be the case under certain scenarios.)

In short, with vc.el, a really efficient workflow is

vc-diff or vc-root-diff → vc-next-action and
vc-dir (with persistent marks) → vc-diff → vc-next-action.

The latter is unique to vc.el, and a feature I don’t think the magit UI can replicate. So while magit can sometimes become visually cluttered, vc-dir marks let users focus on their current work by easily excluding from view files and directories one is not concerned with currently.

A caveat §

Historically, I’ve found this especially fruitful when working on my literate Emacs config^[4] (wherein any “single change” involves changes to the .org file as well as the resulting tangled file(s)) and Emacs packages. Still, I think I prefer magit in cases where the staging functionality of Git is crucial. For instance, I have a repository that houses all my org notes and org-agenda files. There are frequently many changes for this repository, so the convenience of staging/unstaging has been crucial for me. In cases like these, I haven’t found an equivalent for vc.el yet.

Changelog §

Mar 25, 2025
- Add clarifying prose to paragraph.
- Change formatting of “vc.el” and “magit.”

Neat behavior of M-x occur

Sat, 09 Nov 2024 06:00:00 GMT

Having used Emacs for several years now, I somehow hadn’t come across the prefix argument and active region behavior for one of the most well-known commands: occur.

Below is the docstring of occur reads, with the relevant portions preserved:

occur is an interactive native-comp-function in replace.el.

It is bound to M-s o.

(occur REGEXP &optional NLINES REGION)

Inferred type: (function (t &optional t t) t)

Show all lines in the current buffer containing a match for REGEXP.
If a match spreads across multiple lines, all those lines are shown.

[…]

Each line is displayed with NLINES lines before and after, or -NLINES
before if NLINES is negative.
NLINES defaults to list-matching-lines-default-context-lines.
Interactively it is the prefix arg.

Optional arg REGION, if non-nil, mean restrict search to the
specified region. Otherwise search the entire buffer.*
*REGION must be a list of (START . END) positions as returned by
region-bounds.

[…]

When NLINES is a string or when the function is called
interactively with prefix argument without a number (C-u alone
as prefix) the matching strings are collected into the ‘*Occur*’
buffer by using NLINES as a replacement regexp. NLINES may
contain \& and \N which convention follows replace-match.
For example, providing “defun\s +$\S +$” for REGEXP and
“\1” for NLINES collects all the function names in a lisp
program. When there is no parenthesized subexpressions in REGEXP
the entire match is collected. In any case the searched buffer
is not modified.

[…]

So:

When called on a region, on that region is searched.
When called with a numerical prefix argument, that many lines before and after every match is added to the search results. (This reminds me of next-screen-context-lines.) This functionality is particularly useful to me since added context is sometimes necessary.^[1]
When called with a universal argument, just the matching string (not the entire line) is inserted into a line in a read-only buffer.
If called from elisp and NLINES is provided (as a regexp string), then the behavior is like C-u but matches can be modified like replace-match. (See (elisp) Replacing Match for more information.)

Also, searching “NLINES” with apropos-documentation brings up a few other built-in commands that have similar functionality. isearch-occur, multi-occur, list-matching-lines, and occur-context-lines to name a few.

Pretty neat!

Citations in org-mode: Org-cite and Citar

Tue, 14 Jun 2022 23:52:00 GMT

Summary
Helpful sources
What are citation systems?
Org-cite
Citar
Other interesting packages
- Zotero
- Embark
- Org-roam-bibtex
- Citar-capf
- Org-ref
Changelog

Summary §

Jul 20, 2023 Readers should be aware that some package-specific information in this article may be outdated. Thus, readers are advised from outright copying code in this article without verifying (e.g. reading docstrings) the intended behavior. Nevertheless, the concepts related to org-cite and citation management should remain relevant and insightful.

First, I’ll outline the broadest components to producing files in org-mode with a citation system (e.g. org-cite, org-ref). Then I’ll introduce org-cite and the differences between its bibtex, csl, and basic export processors. Then, I will walk through my configuration for org-cite and citar (formerly bibtex-actions). You can see a gist/snippet of all the code present in this post here (alongside other additions of mine).

My goal is to plot the landscape, preparing you to understand other available sources which are more suited for a user already familiar with the landscape.

Helpful sources §

I recommend the following reading for more information regarding how org-cite works:

Citation handling (The Org Manual): The first source you should visit should almost always be the manual (available within Emacs via info, i.e. M-x info). It covers the fundamentals to understanding how to use org-cite. Isn’t well documented currently, but that will change in the future.
Org-cite guide by tecosaur: I’ll be referencing this frequently, for good reason.

What are citation systems? §

There are roughly three moving parts to citation management.

The tool that produces the bibliography file.
A bibliography file is where information regarding sources are stored. This almost always comes in the form of a .bib file; usually one is sufficient. There are various ways to create these files. Though you can manually create your own .bib files, the most common way is exporting a Zotero library (see Zotero).
The text processor.
This is the software the user (you) directly writes in. In our case, it’s Emacs!
The “layer” from text to product.
This is the code that lies in between your plain text writing and an output file (e.g. PDF). Sometimes this is identical to the text processor—in our case it isn’t. For instance, Microsoft Word is both a text editor and the producer of an output file, such as a PDF or a .docx.

org-cite lies closer to (3) because it is responsible for exporting citations, whereas citar is closer to (2) because it is an interface for inserting citations into the buffer. A software like Zotero is responsible for (1).

Org-cite §

In around July of 2021, org-cite was publicly released. org-cite a library packaged with org-mode that processes org citations (e.g. [cite:@wittgensteinTractatusLogicoPhilosophicus2021]). To those not familiar with another citation workflow (e.g. biblatex in LaTeX), it is quite daunting to leap into citations in Emacs. This was certainly the case for me: I leapt into org-mode citation integration with Zotero and LaTeX with no experience in org, Zotero, or LaTeX! Nonetheless, org-cite is quite simple once laid out. After reading this post or section, I recommend taking a look at tecosaur’s fabulous guide to using org-cite. His explanation of the citation styles of org-cite and their variants is particularly useful.

Understanding `org-cite` export processors §

The most crucial concept to org-cite are “export processors.” Take a look at the following passage from the documentation for org-cite-export-processors (as it is at the time of writing):

When non-nil, the value is an association list between export back-ends and
citation export processors:

(BACK-END . PROCESSOR)

where BACK-END is the name of an export back-end or t, and PROCESSOR is a
triplet following the pattern

(NAME BIBLIOGRAPHY-STYLE CITATION-STYLE)

There, NAME is the name of a registered citation processor providing export
functionality, as a symbol. BIBLIOGRAPHY-STYLE (respectively CITATION-STYLE)
is the desired default style to use when printing a bibliography (respectively
exporting a citation), as a string or nil. Both BIBLIOGRAPHY-STYLE and
CITATION-STYLE are optional. NAME is mandatory.

What this suggests is that different combinations of “processors,” “bibliography styles,” and “citation styles” can be configured to work with different org-export backends. Presently, there are three processors available: basic, csl, natbib, and bibtex. Though org-cite citations will always follow the same format, the output text that is exported will change depending on the processor used. I will go over these differences now, focusing primarily on the bibtex and csl backends^[1].

The bibtex processor can only be used with the latex backend. Using this processor exports citations using the BibLaTex LaTeX package. That means that [cite:@bradleyAppearanceRealityMetaphysical2011 82–5;] will export into a LaTeX command like \cite[82–5]{bradleyAppearanceRealityMetaphysical2011}. Compiling the org exported LaTeX file will in turn produce a PDF whose citations are handled by biblatex. The end citation style will be determined by the provided package options (e.g. style=mla-new). Read the biblatex documentation for more information (namely, section 3.1.1 in the February 2, 2022 version of the manual).

The natbib processor unsurprisingly uses the natbib LaTeX package. biblatex is slowly growing to replace the older natbib package, though some users may circumstantially be limited to natbib—you can read more about the differences between natbib and biblatex here. I have not personally used the natbib, but I suspect its usage is similar if not identical to the bibtex processor.

The csl processor will use CSL to export citations. Citation Style Language (CSL) is a language used to instruct the formatting of citations and bibliographies; citation styles are provided by .csl files. Most importantly, CSL is intended to be a universal standard for citation formatting. Accordingly, .csl supports essentially every output format.

In sum:

Which processor should I use? §

The most common confusion comes from realizing that CSL can also export to LaTeX. So, when exporting to LaTeX: should you use the csl or bibtex/natbib processor? The difference lies in whether or not you want to rely on the biblatex package to manage exports.

The important difference is that csl exports to rendered text. Rendered text is text whose end formatting will match that of org’s, e.g. italic text in org-mode will become wrapped in, say, \emph{} in LaTeX. So, for instance, if I export [cite:@bradleyAppearanceRealityMetaphysical2011 82–5;] into a LaTeX file using the csl processor using a CSL file for the Modern Language Association (MLA) citation style, I will see the following in-text citation in the LaTeX file as: (Bradley 82–85)—if anything needed to be bold, italicized, etc., then that would be wrapped in the appropriate LaTeX command. Contrast that with the LaTeX command in the paragraphs above.

So when it comes to exporting to LaTeX, when wouldn’t rendered text be enough? If you want the most basic functionality, i.e. “Seeing in-text citations and bibliographies in my documents is enough,” then CSL will always cover you. However, if you want access to the more complex or nuanced facilities of biblatex, use the bibtex processor instead. biblatex use cases include (i) using obscure or uncommon field and entry types and (ii) wanting “automation” in the citation variant. By (ii) I mean that biblatex handles the variant whereas you must manually list the variant in the org-cite citation when using CSL (see the above link to tecosaur’s guide).

I will give an example. Basic MLA in-text citations following a (AUTHOR PAGE) format. However, closely following MLA means that subsequent in-text citations from the same source should have a (PAGE) format. Using the csl processor, without specifying a style or variant in the org-cite citation, will always output the former formatting as rendered text; as r/bdarcus explains in his comment, CSL focuses on higher-level commands in order to be agnostic of output format. On the other hand, org-cite will, by default, leverage the \autocite command (see org-cite-biblatex-styles). This tells biblatex to change the variant when appropriate. This is an immensely powerful upside to using the bibtex processor—though it is minor in this particular case, this demonstrates the advantages of the biblatex package. You can read more about the differences between CSL and biblatex in this thorough StackExchange explanation. Of course, however, biblatex is only available when exporting to LaTeX, whereas CSL can be used to export into any format (e.g. HTML, Markdown, ODT, plain-text).

In sum, use the bibtex processor when you are exporting to LaTeX and only LaTeX and

want automatic selection of citation variants
or have rare field or entry types in your .bib file.

Otherwise, use the csl processor^[2] (assuming you have a .csl file for your desired citation style).

Finally, it should be noted that the csl and bibtex processors use different locators in citations. As explained in tecosaur’s guide, the csl processor uses locators like bk. and vol., so citations may look like [cite/noauthor:See@mollisonNietzscheContraStoicism2018 pp. 28–9;@priestWhyItIrrational2001 pp. 14;]—CSL processes these locators. On the other hand, a citation key’s suffix is directly passed as an option to BibLaTeX commands, so an equivalent to the above would be [cite/noauthor:See@mollisonNietzscheContraStoicism2018 28–9;@priestWhyItIrrational2001 14;], which doesn’t have CSL locators.

Configuration §

Luckily, the difficulty in org-cite is only conceptually: configuring it is incredibly straightforward. There are two main variables that affect functionality. The first is crucial, and the second is useful to be aware of:

org-cite-global-bibliography
org-cite-export-processors

org-cite-global-bibliography is the bare minimum to getting org-cite ready to work. This should be a list of bibliography file (.bib) paths. I have mine set to a list whose single element is a file that Zotero exports:

:custom
;; Actually, I set this value to `kb/bib-files', which is a list of file paths.
;; I set that as the value of any variable that requires bibliography files,
;; such as `citar', as you'll see below.
(org-cite-global-bibliography
 '("/home/krisbalintona/Documents/org-database/roam/references/master-lib.bib"))

Alternatively, you can use the org-mode #+BIBLIOGRAPHY: keyword to set this value per-file; it’s value should be a file path.

org-cite-export-processors is useful as a means to tweak how you’d like org-cite to export citations. You can also set a file-local value using the #+CITE_EXPORT file keyword (e.g. #+CITE_EXPORT: csl chicago-author-date.csl); see this section in tecosaur’s guide for an example of how to set the processor, bibliography style, and citation style with this keyword. For a given backend^[3], you can choose how org-cite exports it. For instance, here is mine:

:custom
(org-cite-export-processors
 '((md . (csl "chicago-fullnote-bibliography.csl"))   ; Footnote reliant
   (latex biblatex)                                   ; For humanities
   (odt . (csl "chicago-fullnote-bibliography.csl"))  ; Footnote reliant
   (t . (csl "modern-language-association.csl"))))      ; Fallback

As you can see, I have CSL be the default in every case aside from LaTeX. The styles can either be a file path or a file name in org-cite-csl-styles-dir—see Zotero for how to easily acquire CSL files.^[4] (I use LaTeX strictly for my academic papers, so I really enjoy biblatex’s features.)

I also choose to customize faces—I prefer the green faces that org-ref uses:^[5]

:custom-face
;; Have citation link faces look closer to as they were for `org-ref'
(org-cite ((t (:foreground "DarkSeaGreen4"))))
(org-cite-key ((t (:foreground "forest green" :slant italic))))

Usage §

Using org-cite is incredibly simple:

org-cite-insert to insert citations in org files, and
#+PRINT_BIBLIOGRAPHY: within a document to mark where the bibliography/references/works cited should be.^[6]

Citar §

Using org-cite is really simple. But many users will find the interface… too bare. Citar is, roughly, the foremost attempt to provide a pleasing frontend to org-cite. It adds the citar citation-insert processor. The following is the minimum to start using citar:

(use-package citar
  ;; The `:straight' keyword is not necessary. However, I do this to set a value
  ;; for the `:includes' keyword. This keyword tells use-package that those
  ;; package(s) are provided by this package, and not to search for them on
  ;; Melpa for download. Alternatively, you can set the `:straight' keyword to
  ;; nil in those package(s) use-package declaration.
  :straight (citar :type git :host github :repo "emacs-citar/citar" :includes (citar-org))
  :custom
  ;; A list of bib files. A good idea would be having its value be identical to
  ;; that of `org-cite-global-bibliography'. For me, I have all my bib file(s)
  ;; as a list of strings in `kb/bib-files'.
  (citar-bibliography kb/bib-files))

;; Use `citar' with `org-cite'
(use-package citar-org
  :after oc
  :custom
  (org-cite-insert-processor 'citar)
  (org-cite-follow-processor 'citar)
  (org-cite-activate-processor 'citar))

You can then set keybinds for common citar commands. For example, in the :general use-package keyword:^[7]

:general
(:keymaps 'org-mode-map
          :prefix "C-c b"
          "b" '(citar-insert-citation :wk "Insert citation")
          "r" '(citar-insert-reference :wk "Insert reference")
          "o" '(citar-open-notes :wk "Open note"))

If you use embark and org-roam you can also set these variables:

:custom
(citar-notes-paths (list kb/roam-dir)) ; List of directories for reference nodes
(citar-open-note-function 'orb-citar-edit-note) ; Open notes in `org-roam'
(citar-at-point-function 'embark-act)           ; Use `embark'

Capturing (Outdated) §

Aug 19, 2023 The citar-org-roam package provides all that is mentioned in this section and more. That package should be used instead in any instance of a desired integration between org-roam and citar.

If you use org-roam, then the following is how you select bibliographic source and create an org-roam node from it. All credit goes to Jethro Kuan, the creator of org-roam, though I’ve made a few of my own customizations:^[8]

;; Create a new node from a bibliographic source. taken from
;; https://jethrokuan.github.io/org-roam-guide/
(defun kb/org-roam-node-from-cite (keys-entries)
  (interactive (list (citar-select-ref :multiple nil :rebuild-cache t)))
  (let ((title (citar--format-entry-no-widths (cdr keys-entries)
                                              "${author editor}${date urldate} :: ${title}")))
    (org-roam-capture- :templates
                       '(("r" "reference" plain
                          "%?"
                          :if-new (file+head "references/${citekey}.org"
                                             ":properties:
:roam_refs: [cite:@${citekey}]
:end:
#+title: ${title}
#+filetags: %(kb/insert-lit-category)\n")
                          :immediate-finish t
                          :unnarrowed t))
                       :info (list :citekey (car keys-entries))
                       :node (org-roam-node-create :title title)
                       :props '(:finalize find-file))))

I add it to an accessible keybinding:^[9]

:general
(kb/note-keys                           ; global-map
 "C" '(kb/org-roam-node-from-cite :wk "Citar-capture"))

Advising `citar-org-update-pre-suffix` (Outdated) §

Jul 20, 2023 Upstream has recently merged changes to citar-org-update-pre-suffix, renaming it to citar-org-update-prefix-suffix and ensuring that a single space is left between citekeys and their suffixes. Therefore, the code directly below is now unnecessary.

A useful command is citar-org-update-pre-suffix. This command sets the prefix and suffix of a citation key (a single citation can have multiple keys). This is notable since a citation’s suffix is where you provide a locator (e.g. a page number). The command is bound to M-p when the point is on a citation key.

Before advising citar-org-update-pre-suffix, I first advise org-cite-insert such that citar-org-update-pre-suffix is run immediately after inserting a citation:

;; Run `citar-org-update-pre-suffix' after inserting a citation to immediately
;; set its prefix and suffix
(advice-add 'org-cite-insert :after #'(lambda (args)
                                        (save-excursion
                                          (left-char) ; First move point inside citation
                                          (citar-org-update-pre-suffix))))

A limitation with this code is that this only calls citar-org-update-pre-suffix on the last citation key, which is fine when only one key is inserted at once, and not when multiple are inserted. (Though, citar-org-update-pre-suffix can still be called manually on the other citation keys afterward.)

Additionally, I override citar-org-update-pre-suffix with my own version which adds the following functionality:

Temporarily enable typo-mode.^[10]
Avoid manually inserting a separating space in the suffix.

(defun kb/citar-org-update-pre-suffix ()
  "Change the pre/suffix text of the reference at point.

My version also adds a space in the suffix so I don't always have
to manually add one myself."
  (interactive)

  ;; Enable `typo' typographic character cycling in minibuffer. Particularly
  ;; useful in adding en- and em-dashes in citation suffixes (e.g. for page
  ;; ranges)
  (when (featurep 'typo)
    (add-hook 'minibuffer-mode-hook 'typo-mode)) ; Enable dashes

  (let* ((datum (org-element-context))
         (datum-type (org-element-type datum))
         (ref (if (eq datum-type 'citation-reference) datum
                (error "Not on a citation reference")))
         (key (org-element-property :key ref))
         ;; TODO handle space delimiter elegantly.
         (pre (read-string "Prefix text: " (org-element-property :prefix ref)))
         (post (read-string "Suffix text: " (org-element-property :suffix ref))))

    ;; Change post to automatically have one space prior to any user-inputted
    ;; suffix
    (setq post
          (if (string= (replace-regexp-in-string "\s-*" "" post) "")
              ""         ; If there is nothing of substance (e.g. an empty string)
            (replace-regexp-in-string "^[\s-]*" " " post))) ; Only begin with one space

    (setf (buffer-substring (org-element-property :begin ref)
                            (org-element-property :end ref))
          (org-element-interpret-data
           `(citation-reference
             (:key ,key :prefix ,pre :suffix ,post)))))

  ;; Remove hook if it was added earlier
  (remove-hook 'minibuffer-mode-hook 'typo-mode))
(advice-add 'citar-org-update-pre-suffix :override #'kb/citar-org-update-pre-suffix)

One can also add this command to citar-citation-map.^[11]

Aesthetics §

Finally, we can change the way the citar interface appears. The most relevant variables are citar-templates and citar-symbols. Below is my configuration for these variables. Notably, my definition for citar-symbols utilizes all-the-icons icons to fancify the candidates (all-the-icons must be installed in order to have the faces below available):

:custom
(citar-templates
 '((main . "${author editor:30}   ${date year issued:4}    ${title:110}")
   (suffix . "     ${=type=:20}    ${tags keywords keywords:*}")
   (preview . "${author editor} (${year issued date}) ${title}, ${journal journaltitle publisher container-title collection-title}.\n")
   (note . "#+title: Notes on ${author editor}, ${title}") ; For new notes
   ))
;; Configuring all-the-icons. From
;; https://github.com/bdarcus/citar#rich-ui
(citar-symbols
 `((file ,(all-the-icons-faicon "file-o" :face 'all-the-icons-green :v-adjust -0.1) .
         ,(all-the-icons-faicon "file-o" :face 'kb/citar-icon-dim :v-adjust -0.1) )
   (note ,(all-the-icons-material "speaker_notes" :face 'all-the-icons-blue :v-adjust -0.3) .
         ,(all-the-icons-material "speaker_notes" :face 'kb/citar-icon-dim :v-adjust -0.3))
   (link ,(all-the-icons-octicon "link" :face 'all-the-icons-orange :v-adjust 0.01) .
         ,(all-the-icons-octicon "link" :face 'kb/citar-icon-dim :v-adjust 0.01))))
(citar-symbol-separator "  ")
:init
;; Here we define a face to dim non 'active' icons, but preserve alignment.
;; Change to your own theme's background(s)
(defface kb/citar-icon-dim
  ;; Change these colors to match your theme. Using something like
  ;; `face-attribute' to get the value of a particular attribute of a face might
  ;; be more convenient.
  '((((background dark)) :foreground "#212428")
    (((background light)) :foreground "#f0f0f0"))
  "Face for having icons' color be identical to the theme
  background when \"not shown\".")

Here’s the end-result:

Visual improvements to citar’s minibuffer interface.

Other interesting packages §

Zotero §

Zotero isn’t an Emacs package, but it is crucial to most users’ workflow, so it deserves attention. Zotero makes gathering, storing, and exporting bibliographic data infinitely easier. For instance, an ISBN or DOI of a source is all that is necessary for an entry’s fields to be populated. There are two things to note about my setup:

I install the BetterBibLaTex add-on (see its features in the official documentation page. Its main benefits include unique citation key generation and exporting facilities),
and export my library using the BetterBibLaTeX format. I also tick the “Keep Updated” option; this continually updates the .bib file as I make changes to my library. I then point org-cite-global-bibliography and citar-bibliography to this file.

Additionally, for over a year now, I’ve been using Zotero’s own PDF viewer and annotator. Until recently, this feature had only been available in Zotero Beta, but it is now merged onto the main branch. Though it isn’t powerful, it gets the job done for me, and the convenience is what sells it.

Finally, a very handy tip is to use the CSL files that Zotero already provides (credit to this section of tecosaur’s guide). The CSL files (which provide citation styles) are located in ZOTERO_DIR/styles/. You can set org-cite-csl-styles-dir to this path:

:custom
(org-cite-csl-styles-dir
 (expand-file-name "~/Documents/Zotero/styles/"))

Embark §

Embark provides menus (essentially keymaps) based on “context,” that is, the type of thing the point is on. As a result, embark has immense potential. Citar is built to exploit embark without requiring it—for instance, see citar-citation-map.

Org-roam-bibtex §

Org-roam-bibtex integrates org-roam with citation systems, such as org-cite. This packages allows org-roam to recognize particular nodes as bibliographic (i.e. associated with a particular .bib entry).

Additionally, as as citar’s author, u/bdarcus, shares here, there is work being done on citar’s end to more tightly integrate org-roam with citar, in the form of citar-org-roam.

Citar-capf §

Citar-capf provides a complation-at-point-function^[12] for citations. However, if you’re reading this in the future, there’s a likely chance that this commit would have been merged. The commit merges citar-capf with citar.

Org-ref §

Org-ref has historically been the dominant citation system for org-mode. I elect to use org-cite instead because (i) it comes with org-mode, meaning there is one less conceptual- and configuration-layer to navigate, (ii) Moreover, org-ref uses a format that follows org conventions less closely, and (iii) I have read that is arguably more robust and future-proof. Nevertheless, some users still prefer it.

Changelog §

Jun 15, 2022
- Better clarity in Advising citar-org-update-pre-suffix (Outdated).
- Mention the merging of citar-capf into citar (see Citar-capf).
- Added Embark.
- Mention citar-org-roam in Org-roam-bibtex.
- Made comments clarifying kb/bib-files.
- Add screenshot that showcases visually improved citar interface (see Aesthetics).
Jun 19, 2022
- Added Helpful sources.
- Change processor explanations to include the natbib processor.
- Change processor explanations to recognize the difference between plain-text and rendered text.
Jul 20, 2023
- Noted that some package-specific information in this article may be outdated.
- Noted update to citar-org-update-pre-suffix
Aug 19, 2023
- Mentioned citar-org-roam as preferable to any desired integration between org-roam and citar.
Nov 20, 2023
- Updated GitLab Gist.

True Emacs Transparency

Tue, 07 Jun 2022 15:00:00 GMT

Transparency in Emacs isn’t that great. Every source I find regarding transparency of Emacs (as of writing this) points to setting the alpha frame parameter. For instance:

The issue with alpha is that it sets the transparency of the entire window; what this means is that text and background become transparent together. Clearly this is undesirable for some: the alpha parameter needs to be near 100, otherwise the text becomes illegible. Ideally, the text remains opaque while the background becomes transparent.^[1]

The solution came from a patched version of Emacs made by Håkon Flatval back in November 2021—his announcement that month on Reddit received some attention. The patch adds the alpha-background frame parameter which makes only the background of a frame transparent:

alpha-background set to 75.

You can set the alpha-background of a particular frame with the set-frame-parameter function, and the default value for frames by adding to default-frame-alist.^[2] For example:

(set-frame-parameter nil 'alpha-background 100) ; For current frame
(add-to-list 'default-frame-alist '(alpha-background . 100)) ; For all new frames henceforth

I’ve also defined my own command for toggling between a frame having alpha-background values of 100 and 72:^[3]

(defun kb/toggle-window-transparency ()
  "Toggle the value of `alpha-background'.

Toggles between 100 and 72 by default.  Can choose which value to change
to if called with ARG, or any prefix argument."
  (interactive "P")
  (let ((transparency (pcase arg
                        ((pred numberp) arg)
                        ((pred car) (read-number "Change the transparency to which value (0-100)? "))
                        (_
                         (pcase (frame-parameter nil 'alpha-background)
                           (72 100)
                           (100 72)
                           (t 100))))))
    (set-frame-parameter nil 'alpha-background transparency)))

Mar 8, 2025 Readers should be aware that the above code snippet may have potential incompatibilities with other versions of Emacs. Small modifications may be necessary in such cases.

In practice, this is what toggling transparency looks like:

Live-toggling of the alpha-background parameter.

I had been using Håkon’s patched version since becoming aware of it, and it’s been perfect for me. My only gripe was that without the expertise of patching future releases of Emacs (Håkon wasn’t updating his repository), I would inevitably be using an increasingly out-of-date version of Emacs.

However, I recently returned to check if there had been any updates to the repo. Though there were no new commits to the repository, I decided to check if there was work on mainline Emacs yet. I searched the repo for matches of alpha-background, and sure enough, I found a hit! On January 30, 2022, Po Lu silently announced the merging of the patch. Accordingly, this means that the alpha-background frame parameter is available to all builds after January 30, 2022. I’ll also note that do not know what went on behind-the-scenes to get this merged, so I’ll make it clear that I am not attributing the development of this feature to only Håkon and Po Lu.

Of course, transparency in Emacs (alongside any other application on your system) is only possible if you are using a compositor (e.g. Picom). Regarding build flags, Håkon’s patch supported transparency only with Emacs compiled with GTK3 and cairo support. I do not know for certain if this is still the case. If it is, then an Emacs built with the --with-cairo and --with-x-toolkit=gtk3 flags is necessary (meaning this feature is only available on machines using X Window). However, according to this Reddit comment thread, it seems like only cairo is necessary, while GTK3 is not necessary. That is, --with-x-toolkit=no works as well.

Changelog §

Jun 8, 2022
- Note that a compositor is necessary for transparency.
- Added statement about GTK3 perhaps not being necessary that links to a corresponding Reddit comment thread.
Mar 8, 2025
- Update code snippet for kb/toggle-window-transparency. Also add note about potential incompatibilities between this code snippet and other versions of Emacs.

Cape

Sun, 13 Mar 2022 07:02:00 GMT

What is cape?
Basic usage: keybinds
Adding backends to completion-at-point-functions
Cape-company-to-capf and cape-super-capf
pcomplete nicety
My completion-at-point-functions
Changelog

What is `cape`? §

I will be going over the basic usages of Cape, namely how to add completion functions to completion-at-point-functions and how to use cape's built-in completion utilities (e.g. cape-company-to-capf and cape-capf-buster) to create backends with desired behavior. (Also see u/JDRiverRun’s informative comment about the advantages of using completion-at-point-functions over company.)

Cape is to corfu as company-backends are to company:

Cape provides a bunch of Completion At Point Extensions which can be used in combination with my Corfu completion UI or the default completion UI. The completion backends used by completion-at-point are so called completion-at-point-functions (Capfs). In principle, the Capfs provided by Cape can also be used by Company.

Consequently, cape is only used if you utilize the built-in completion-at-point, which is best complemented by corfu text-completion ^[1].

You can also see the list of built-in completion-at-point-functions in the README. Several of these completion-at-point-functions are quite niche but others, such as cape-file and cape-symbol have common use cases.

Note: I use straight.el for package management and general.el to set my keybindings. Both of these packages have integration with use-package which come in the form of the :straight and :general keywords, respectively.

Basic usage: keybinds §

The most basic way to use cape is to bind its built-in completion-at-point-functions to their own keys. For instance:

(use-package cape
  :general (:prefix "M-c"              ; Choose a particular completion function
                    "p" 'completion-at-point
                    "t" 'complete-tag   ; etags
                    "d" 'cape-dabbrev   ; basically `dabbrev-completion'
                    "f" 'cape-file
                    "k" 'cape-keyword
                    "s" 'cape-symbol
                    "a" 'cape-abbrev
                    "i" 'cape-ispell
                    "l" 'cape-line
                    "w" 'cape-dict
                    "\\" 'cape-tex
                    "_" 'cape-tex
                    "^" 'cape-tex
                    "&" 'cape-sgml
                    "r" 'cape-rfc1345))

Additionally, if having completion-at-point-functions readily available through keybinds is desirable, then one can use cape-interactive-capf to turn an already existing completion-at-point-function into a command (i.e. interactive function) that can be bound.

Adding backends to `completion-at-point-functions` §

However, cape is powerful because these functions can be added to completion-at-point-functions, meaning you can configure when each functions is used and where. The simplest way to accomplish this is by adding backends to completion-at-point-functions in a hook. Here is a simple example:

(defun kb/cape-capf-setup-git-commit ()
  (let ((result))
    (dolist (element '(cape-symbol cape-dabbrev) result)
      (add-to-list 'completion-at-point-functions element))))

I then add this to the appropriate hook:

:hook (git-commit-mode . kb/cape-capf-setup-git-commit)

Consequently, when making commits to git, via magit, for instance, completion-at-point-functions looks like this^[2]:

'(cape-symbol
  cape-dabbrev
  tags-completion-at-point-function)

There are a few additional things to keep in mind when adding backends to completion-function-at-point:

add-to-list prepends elements to a list, that is, place an element at the front of a list^[3].
add-to-list is almost always preferable to push because push adds an element to a list even if it already in the list, whereas add-to-list will not.
Elements earlier in dolist will be added to the list before later elements. This means that elements which should be deeper within completion-at-point-functions should be placed first. (Notice how cape-dabbrev is added after cape-symbol.)

`Cape-company-to-capf` and `cape-super-capf` §

I think the killer feature of cape is cape-company-to-capf. This function is able to convert any company backend and convert it into a completion-at-point-function which corfu can use^[4]. For this reason, I regard cape as quite an underrated package since it achieves almost full feature parity with company. Here is an example with company-yasnippet:

(defun kb/cape-capf-setup-lsp ()
  "Replace the default `lsp-completion-at-point' with its
`cape-capf-buster' version. Also add `cape-file' and
`company-yasnippet' backends."
  (setf (elt (cl-member 'lsp-completion-at-point completion-at-point-functions) 0)
        (cape-capf-buster #'lsp-completion-at-point))
  (add-to-list 'completion-at-point-functions (cape-company-to-capf #'company-yasnippet))
  (add-to-list 'completion-at-point-functions #'cape-dabbrev t))

Another useful function is cape-super-capf. This function combines multiple completion-at-point-functions into a single function. Effectively, this means candidates from multiple backends can appear jointly. For instance, one can combine cape-ispell and cape-dabbrev:

(defun kb/cape-capf-setup-org ()
  (require 'org-roam)
  (if (org-roam-file-p)
      (org-roam--register-completion-functions-h)
    (let (result)
      (dolist (element (list
                        (cape-super-capf #'cape-ispell #'cape-dabbrev)
                        (cape-company-to-capf #'company-yasnippet))
                       result)
        (add-to-list 'completion-at-point-functions element)))
    ))

For other cape transformers, see the appropriate section of the README.

`pcomplete` nicety §

Finally, I have the following advice to make usage with pcomplete, what eshell uses for completion:

:config
;; For pcomplete. For now these two advices are strongly recommended to
;; achieve a sane Eshell experience. See
;; https://github.com/minad/corfu#completing-with-corfu-in-the-shell-or-eshell

;; Silence the pcomplete capf, no errors or messages!
(advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent)
;; Ensure that pcomplete does not write to the buffer and behaves as a pure
;; `completion-at-point-function'.
(advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify)

My `completion-at-point-functions` §

I have very hesitantly included my WIP code which leverages cape and completion-at-point utilities. I have not described in detail each of the following functions. I have, however, attempted to provide useful docstrings and comments.

I hesitate to publish this code because it was very haphazardly written and highly dependent on my configuration. The reason for this is the order in which the completion-at-point-functions are added: any peculiarities in another’s configuration may lead to undesirable results. As a result, do not directly copy-and-paste this code and expect proper functionality. Rather, I put it here as a reference for what can be done.

Here they are

Warning! This code may produce undesirable effects! Copy at your own risk.

(use-package cape
  :hook ((emacs-lisp-mode .  kb/cape-capf-setup-elisp)
         (lsp-completion-mode . kb/cape-capf-setup-lsp)
         (org-mode . kb/cape-capf-setup-org)
         (eshell-mode . kb/cape-capf-setup-eshell)
         (git-commit-mode . kb/cape-capf-setup-git-commit)
         (LaTeX-mode . kb/cape-capf-setup-latex)
         (sh-mode . kb/cape-capf-setup-sh)
         )
  :general (:prefix "M-c"               ; Particular completion function
                    "p" 'completion-at-point
                    "t" 'complete-tag           ; etags
                    "d" 'cape-dabbrev           ; or dabbrev-completion
                    "f" 'cape-file
                    "k" 'cape-keyword
                    "s" 'cape-symbol
                    "a" 'cape-abbrev
                    "i" 'cape-ispell
                    "l" 'cape-line
                    "w" 'cape-dict
                    "\\"' cape-tex
                    "_" 'cape-tex
                    "^" 'cape-tex
                    "&" 'cape-sgml
                    "r" 'cape-rfc1345
                    )
  :custom
  (cape-dabbrev-min-length 3)
  :init
  ;; Elisp
  (defun kb/cape-capf-ignore-keywords-elisp (cand)
    "Ignore keywords with forms that begin with \":\" (e.g.
:history)."
    (or (not (keywordp cand))
        (eq (char-after (car completion-in-region--data)) ?:)))
  (defun kb/cape-capf-setup-elisp ()
    "Replace the default `elisp-completion-at-point'
completion-at-point-function. Doing it this way will prevent
disrupting the addition of other capfs (e.g. merely setting the
variable entirely, or adding to list).

Additionally, add `cape-file' as early as possible to the list."
    (setf (elt (cl-member 'elisp-completion-at-point completion-at-point-functions) 0)
          #'elisp-completion-at-point)
    (add-to-list 'completion-at-point-functions #'cape-symbol)
    ;; I prefer this being early/first in the list
    (add-to-list 'completion-at-point-functions #'cape-file)
    (require 'company-yasnippet)
    (add-to-list 'completion-at-point-functions (cape-company-to-capf #'company-yasnippet)))

  ;; LSP
  (defun kb/cape-capf-setup-lsp ()
    "Replace the default `lsp-completion-at-point' with its
`cape-capf-buster' version. Also add `cape-file' and
`company-yasnippet' backends."
    (setf (elt (cl-member 'lsp-completion-at-point completion-at-point-functions) 0)
          (cape-capf-buster #'lsp-completion-at-point))
    ;; TODO 2022-02-28: Maybe use `cape-wrap-predicate' to have candidates
    ;; listed when I want?
    (add-to-list 'completion-at-point-functions (cape-company-to-capf #'company-yasnippet))
    (add-to-list 'completion-at-point-functions #'cape-dabbrev t))

  ;; Org
  (defun kb/cape-capf-setup-org ()
    (require 'org-roam)
    (if (org-roam-file-p)
        (org-roam--register-completion-functions-h)
      (let (result)
        (dolist (element (list
                          (cape-super-capf #'cape-ispell #'cape-dabbrev)
                          (cape-company-to-capf #'company-yasnippet))
                         result)
          (add-to-list 'completion-at-point-functions element)))
      ))

  ;; Eshell
  (defun kb/cape-capf-setup-eshell ()
    (let ((result))
      (dolist (element '(pcomplete-completions-at-point cape-file) result)
        (add-to-list 'completion-at-point-functions element))
      ))

  ;; Git-commit
  (defun kb/cape-capf-setup-git-commit ()
    (general-define-key
     :keymaps 'local
     :states 'insert
     "<tab>" 'completion-at-point)      ; Keybinding for `completion-at-point'
    (let ((result))
      (dolist (element '(cape-dabbrev cape-symbol) result)
        (add-to-list 'completion-at-point-functions element))))

  ;; LaTeX
  (defun kb/cape-capf-setup-latex ()
    (require 'company-auctex)
    (let ((result))
      (dolist (element (list
                        ;; First add `company-yasnippet'
                        (cape-company-to-capf #'company-yasnippet)
                        ;; Then add `cape-tex'
                        #'cape-tex
                        ;; Then add `company-auctex' in the order it adds its
                        ;; backends.
                        (cape-company-to-capf #'company-auctex-bibs)
                        (cape-company-to-capf #'company-auctex-labels)
                        (cape-company-to-capf
                         (apply-partially #'company--multi-backend-adapter
                                          '(company-auctex-macros company-auctex-symbols company-auctex-environments))))
                       result)
        (add-to-list 'completion-at-point-functions element))))


  ;; Sh
  (defun kb/cape-capf-setup-sh ()
    (require 'company-shell)
    (add-to-list 'completion-at-point-functions (cape-company-to-capf #'company-shell)))
  :config
  ;; For pcomplete. For now these two advices are strongly recommended to
  ;; achieve a sane Eshell experience. See
  ;; https://github.com/minad/corfu#completing-with-corfu-in-the-shell-or-eshell

  ;; Silence the pcomplete capf, no errors or messages!
  (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent)
  ;; Ensure that pcomplete does not write to the buffer and behaves as a pure
  ;; `completion-at-point-function'.
  (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify))

Changelog §

Mar 13, 2022
- Fixed typo. Added link to u/JDRiverRun’s informative Reddit comment.

Corfu, Kind-icon, and Corfu-doc

Sun, 27 Feb 2022 06:56:00 GMT

Synopsis
Corfu
Kind-icon
Corfu-doc
Changelog

Nov 28, 2022 As is noted in the corfu-doc repository, corfu-doc has been deprecated by the built-in corfu-popupinfo corfu extension. corfu-popupinfo’s functionality is roughly identical to corfu-doc’s, though its interface and code is naturally more idiomatic to corfu.

Synopsis §

I will be going over my personal Emacs’ text completion (e.g. company-mode and its accessories) configuration, which includes the following packages:

Corfu by Minad — simpler alternative to company-mode
Kind-icon by jdtsmith (u/JDRiverRun)— add icons to corfu popup (analog to company-box-icons)
Corfu-doc by Galeo — add documentation popup for corfu candidates (analog to company-box-doc)

Corfu §

What is `corfu`? How does it differ from `company`? §

The default corfu popup window. The GIF’s framerate is low, which makes corfu appear less performant here than in actuality.

Corfu is a text completion (e.g. completion-at-point, company-mode) package. In my opinion, since its release, corfu has not gotten the attention that it deserves. I prefer it to company for the following reasons:

It is easier to configure since corfu’s internals rely on the built-in completion-at-point. This also means that, unlike company,^[1]…
- any built-in invocation of completion-at-point or completion-in-region leverages corfu,
- and any completion-style (e.g. orderless) can be used for filtering candidates.
Corfu has been more performant (i.e. fewer stutters, smoother cycling of candidates) in my experience.
Corfu can support any company backend via cape-company-to-capf, provided by the complementary cape package. Thus, packages like company-yasnippet can be used with corfu easily (see the next post in my Text completion and minibuffer UI series for more details and examples.)

Basic §

The following is a basic corfu configuration with my preferred keybinds:

(use-package corfu
  :general
  (:keymaps 'corfu-map
            :states 'insert
            "C-n" #'corfu-next
            "C-p" #'corfu-previous
            "<escape>" #'corfu-quit
            "<return>" #'corfu-insert
            "M-d" #'corfu-show-documentation
            "M-l" #'corfu-show-location)
  :config
  (corfu-global-mode))

These keybinds have C-n and C-p move through the candidates popup, <return> choose the current candidate, and <escape> close the corfu popup. Moreover, I have corfu’s documentation command (corfu-show-documentation; shows the available documentation for the current candidate, if any) bound to M-d, and corfu’s location command (corfu-show-location) to go to the location of the current candidate to M-l.

Corfu offers a few variables to configure. You can take a look at each docstring to see its function. Here are my preferences:

:custom
(corfu-auto nil)        ; Only use `corfu' when calling `completion-at-point' or
                                        ; `indent-for-tab-command'
(corfu-auto-prefix 2)
(corfu-auto-delay 0.25)

(corfu-min-width 80)
(corfu-max-width corfu-min-width)       ; Always have the same width
(corfu-count 14)
(corfu-scroll-margin 4)
(corfu-cycle nil)

;; `nil' means to ignore `corfu-separator' behavior, that is, use the older
;; `corfu-quit-at-boundary' = nil behavior. Set this to separator if using
;; `corfu-auto' = `t' workflow (in that case, make sure you also set up
;; `corfu-separator' and a keybind for `corfu-insert-separator', which my
;; configuration already has pre-prepared). Necessary for manual corfu usage with
;; orderless, otherwise first component is ignored, unless `corfu-separator'
;; is inserted.
(corfu-quit-at-boundary nil)
(corfu-preselect-first t)        ; Preselect first candidate?

;; Other
;; NOTE 2022-02-05: In my actual configuration, I have this variable set to nil
;; since I use `corfu-doc', whose configuration comes later. But if you don't
;; use `corfu-doc', this might be helpful to you.
(corfu-echo-documentation t)            ; Show documentation in echo area?

Additionally, the following two variables not under corfu but related to completion-at-point will be useful to set:

;; Works with `indent-for-tab-command'. Make sure tab doesn't indent when you
;; want to perform completion
(tab-always-indent 'complete)
(completion-cycle-threshold nil)      ; Always show all candidates in popup menu

Working with the recent changes to `corfu` §

On February 7, 2022, corfu introduced an important change^[2], particularly the interaction between corfu and orderless. You can read more on their README, but, essentially, orderless now introduces the corfu-insert-separator command that inserts the corfu-separator character into the buffer. This character is what delimits orderless components (see this Reddit comment for a more lengthy description of this behavior.) A corfu workflow in which corfu-auto is set to t leverages this change, for without it users could not realistically use corfu with a multi-component completion-style like orderless.

I do not use this workflow^[3], but if this behavior is desirable, you can set corfu-separator to your orderless separator character to properly delimit orderless components. I personally use the regular space character. You can make the following modifications to your configuration:

:general
;; NOTE 2022-02-28: `general-override-mode-map' is necessary to override local
;; binds to SPC in evil-mode's insert mode. May not be necessary if you don't use `evil'
(:keymaps 'corfu-map
          :states 'insert
          "H-SPC" #'corfu-insert-separator ; I have a hyper key so this is an alternative keybind I use sometimes
          "SPC" #'corfu-insert-separator)
:custom
(corfu-quit-at-boundary 'separator)     ; a non-nil value is necessary
(corfu-separator ?\s)                   ; Use space
(corfu-quit-no-match 'separator) ; Don't quit if there is `corfu-separator' inserted
(corfu-preview-current 'insert)  ; Preview current candidate?
:config
;; NOTE 2022-03-01: This allows for a more evil-esque way to have
;; `corfu-insert-separator' work with space in insert mode without resorting to
;; overriding keybindings with `general-override-mode-map'. See
;; https://github.com/minad/corfu/issues/12#issuecomment-869037519
;; Alternatively, add advice without `general.el':
;; (advice-add 'corfu--setup :after 'evil-normalize-keymaps)
;; (advice-add 'corfu--teardown :after 'evil-normalize-keymaps)
(general-add-advice '(corfu--setup corfu--teardown) :after 'evil-normalize-keymaps)
(evil-make-overriding-map corfu-map)

Further configuration in minibuffers and with `lsp` §

Corfu’s README provides a way to be able to use corfu completion in the minibuffer:

;; Enable Corfu more generally for every minibuffer, as long as no other
;; completion UI is active. If you use Mct or Vertico as your main minibuffer
;; completion UI. From
;; https://github.com/minad/corfu#completing-with-corfu-in-the-minibuffer
(defun corfu-enable-always-in-minibuffer ()
  "Enable Corfu in the minibuffer if Vertico/Mct are not active."
  (unless (or (bound-and-true-p mct--active) ; Useful if I ever use MCT
              (bound-and-true-p vertico--input))
    (setq-local corfu-auto nil)       ; Ensure auto completion is disabled
    (corfu-mode 1)))
(add-hook 'minibuffer-setup-hook #'corfu-enable-always-in-minibuffer 1)

This means that in commands like eval-expression, corfu is able to be used (via <tab>) and provide completion.

Using corfu in the minibuffer prompt for eval-expression.

Additionally, for lsp-mode buffers, I have the following lines (this is entirely optional and preferential):

:hook (lsp-completion-mode . kb/corfu-setup-lsp) ; Use corfu for lsp completion
:custom
(lsp-completion-provider :none) ; Use corfu instead the default for lsp completions
:config
;; Setup lsp to use corfu for lsp completion
(defun kb/corfu-setup-lsp ()
  "Use orderless completion style with lsp-capf instead of the
  default lsp-passthrough."
  (setf (alist-get 'styles (alist-get 'lsp-capf completion-category-defaults))
        '(orderless)))

End product §

Putting it together, we end with my actual configuration:

(use-package corfu
  :hook (lsp-completion-mode . kb/corfu-setup-lsp) ; Use corfu for lsp completion
  :general
  (:keymaps 'corfu-map
            :states 'insert
            "C-n" #'corfu-next
            "C-p" #'corfu-previous
            "<escape>" #'corfu-quit
            "<return>" #'corfu-insert
            "H-SPC" #'corfu-insert-separator
            ;; "SPC" #'corfu-insert-separator ; Use when `corfu-quit-at-boundary' is non-nil
            "M-d" #'corfu-show-documentation
            "C-g" #'corfu-quit
            "M-l" #'corfu-show-location)
  :custom
  ;; Works with `indent-for-tab-command'. Make sure tab doesn't indent when you
  ;; want to perform completion
  (tab-always-indent 'complete)
  (completion-cycle-threshold nil)      ; Always show candidates in menu

  (corfu-auto nil)
  (corfu-auto-prefix 2)
  (corfu-auto-delay 0.25)

  (corfu-min-width 80)
  (corfu-max-width corfu-min-width)     ; Always have the same width
  (corfu-count 14)
  (corfu-scroll-margin 4)
  (corfu-cycle nil)

  ;; `nil' means to ignore `corfu-separator' behavior, that is, use the older
  ;; `corfu-quit-at-boundary' = nil behavior. Set this to separator if using
  ;; `corfu-auto' = `t' workflow (in that case, make sure you also set up
  ;; `corfu-separator' and a keybind for `corfu-insert-separator', which my
  ;; configuration already has pre-prepared). Necessary for manual corfu usage with
  ;; orderless, otherwise first component is ignored, unless `corfu-separator'
  ;; is inserted.
  (corfu-quit-at-boundary nil)
  (corfu-separator ?\s)            ; Use space
  (corfu-quit-no-match 'separator) ; Don't quit if there is `corfu-separator' inserted
  (corfu-preview-current 'insert)  ; Preview first candidate. Insert on input if only one
  (corfu-preselect-first t)        ; Preselect first candidate?

  ;; Other
  (corfu-echo-documentation nil)        ; Already use corfu-doc
  (lsp-completion-provider :none)       ; Use corfu instead for lsp completions
  :init
  (corfu-global-mode)
  :config
  ;; NOTE 2022-03-01: This allows for a more evil-esque way to have
  ;; `corfu-insert-separator' work with space in insert mode without resorting to
  ;; overriding keybindings with `general-override-mode-map'. See
  ;; https://github.com/minad/corfu/issues/12#issuecomment-869037519
  ;; Alternatively, add advice without `general.el':
  ;; (advice-add 'corfu--setup :after 'evil-normalize-keymaps)
  ;; (advice-add 'corfu--teardown :after 'evil-normalize-keymaps)
  (general-add-advice '(corfu--setup corfu--teardown) :after 'evil-normalize-keymaps)
  (evil-make-overriding-map corfu-map)

  ;; Enable Corfu more generally for every minibuffer, as long as no other
  ;; completion UI is active. If you use Mct or Vertico as your main minibuffer
  ;; completion UI. From
  ;; https://github.com/minad/corfu#completing-with-corfu-in-the-minibuffer
  (defun corfu-enable-always-in-minibuffer ()
    "Enable Corfu in the minibuffer if Vertico/Mct are not active."
    (unless (or (bound-and-true-p mct--active) ; Useful if I ever use MCT
                (bound-and-true-p vertico--input))
      (setq-local corfu-auto nil)       ; Ensure auto completion is disabled
      (corfu-mode 1)))
  (add-hook 'minibuffer-setup-hook #'corfu-enable-always-in-minibuffer 1)

  ;; Setup lsp to use corfu for lsp completion
  (defun kb/corfu-setup-lsp ()
    "Use orderless completion style with lsp-capf instead of the
default lsp-passthrough."
    (setf (alist-get 'styles (alist-get 'lsp-capf completion-category-defaults))
          '(orderless))))

Kind-icon §

Kind-icon is essentially company-box-icons for corfu. It adds icons to the left margin of the corfu popup that represent the ‘function’ (e.g. variable, method, file) of that candidate.

Using corfu-doc in java-mode with completion candidates provided by lsp-mode.

The following is my configuration:

(use-package kind-icon
  :after corfu
  :custom
  (kind-icon-use-icons t)
  (kind-icon-default-face 'corfu-default) ; Have background color be the same as `corfu' face background
  (kind-icon-blend-background nil)  ; Use midpoint color between foreground and background colors ("blended")?
  (kind-icon-blend-frac 0.08)

  ;; NOTE 2022-02-05: `kind-icon' depends `svg-lib' which creates a cache
  ;; directory that defaults to the `user-emacs-directory'. Here, I change that
  ;; directory to a location appropriate to `no-littering' conventions, a
  ;; package which moves directories of other packages to sane locations.
  (svg-lib-icons-dir (no-littering-expand-var-file-name "svg-lib/cache/")) ; Change cache dir
  :config
  (add-to-list 'corfu-margin-formatters #'kind-icon-margin-formatter) ; Enable `kind-icon'

  ;; Add hook to reset cache so the icon colors match my theme
  ;; NOTE 2022-02-05: This is a hook which resets the cache whenever I switch
  ;; the theme using my custom defined command for switching themes. If I don't
  ;; do this, then the backgound color will remain the same, meaning it will not
  ;; match the background color corresponding to the current theme. Important
  ;; since I have a light theme and dark theme I switch between. This has no
  ;; function unless you use something similar
  (add-hook 'kb/themes-hooks #'(lambda () (interactive) (kind-icon-reset-cache))))

Corfu-doc §

Corfu-doc is basically company-quickhelp for corfu. It shows the documentation of the selected candidate in an adjacent popup window.

Using corfu-doc in a corfu popup. Called from a java file with completion candidates provided by lsp-mode.

Here is a sample configuration^[4]:

(use-package corfu-doc
  ;; NOTE 2022-02-05: At the time of writing, `corfu-doc' is not yet on melpa
  :straight (corfu-doc :type git :host github :repo "galeo/corfu-doc")
  :after corfu
  :hook (corfu-mode . corfu-doc-mode)
  :general (:keymaps 'corfu-map
                     ;; This is a manual toggle for the documentation popup.
                     [remap corfu-show-documentation] #'corfu-doc-toggle ; Remap the default doc command
                     ;; Scroll in the documentation window
                     "M-n" #'corfu-doc-scroll-up
                     "M-p" #'corfu-doc-scroll-down)
  :custom
  (corfu-doc-delay 0.5)
  (corfu-doc-max-width 70)
  (corfu-doc-max-height 20)

  ;; NOTE 2022-02-05: I've also set this in the `corfu' use-package to be
  ;; extra-safe that this is set when corfu-doc is loaded. I do not want
  ;; documentation shown in both the echo area and in the `corfu-doc' popup.
  (corfu-echo-documentation nil))

From my experience, corfu-doc is perfect for most. However, it should be noted that for those who have a high repeat rate^[5], rapidly scrolling through candidates causes stuttering and/or lag. This is why I find setting a keybind for corfu-doc-toggle to be useful.

Changelog §

Feb 28, 2022
- Added link to Reddit comment in Working with the recent changes to corfu section. Also update description of new corfu behavior.
- Added configuration for using corfu in the minibuffer.
- Listed more benefits to corfu, provided by u/JDRiverRun.
Mar 1, 2022
- Added link to relevant corfu GitHub Issue.
- Changed corfu configuration to avoid setting keybinds in general-override-mode-map, suggested by a comment to this point.
- Added a note and GIF to corfu-doc section.
Mar 11, 2022
- Update to include new compatibility with corfu-insert-separator and corfu-quit-at-boundary functionality.

Vertico, Marginalia, All-the-icons-completion, and Orderless

Mon, 21 Feb 2022 21:46:00 GMT

Synopsis
Marginalia
All-the-icons-completion
Vertico
Orderless
Changelog

Synopsis §

Apr 5, 2025 Readers should be aware that some of the package-specific information in this article, including configuration options and lines of code, may be outdated. Since publication, those packages have developed significantly. Additionally, my tastes and recommendations as an Emacs user have changed–if I were to rewrite this package today, I would do so different. For those curious about my current in-line and minibuffer completion configuration, you can the relevant sections in my Emacs configuration.

I will be walking through my personal Emacs’ minibuffer UI (which means packages like Selectrum, Ido, Helm, Vertico, and Ivy) configuration, which includes the following packages:

Marginalia — minibuffer annotations, i.e., auxiliary candidate information
All-the-icons-completion — all-the-icons icons for minibuffer candidates
Vertico — vertical minibuffer interface
Orderless — a flexible completion-style with multi-component matching

Marginalia §

The following is vertico with marginalia annotations right-aligned in the minibuffer.

Using helpful-variable

Using find-file

Marginalia is painless to set up. Remember, I use general.el to set keybindings:

(use-package marginalia
  :general
  (:keymaps 'minibuffer-local-map
            "M-A" 'marginalia-cycle)
  :custom
  (marginalia-max-relative-age 0)
  (marginalia-align 'right)
  :init
  (marginalia-mode))

All-the-icons-completion §

Marginalia, Vertico, and Orderless have already received considerable exposure, but all-the-icons-completion has not.

Using find-file in a directory with subdirectories, python files, a .txt file, and an org file. You can see the icons in the far left.

All-the-icons-completion is also dead-simple to set up:

(use-package all-the-icons-completion
  :after (marginalia all-the-icons)
  :hook (marginalia-mode . all-the-icons-completion-marginalia-setup)
  :init
  (all-the-icons-completion-mode))

Note: All-the-icons-completion depends on an already installed all-the-icons.

Vertico §

Vertico is a minibuffer interface, that is, it changes the minibuffer looks and how you interact with it.

Basic §

This is a very basic Vertico configuration.

(use-package vertico
  :custom
  (vertico-count 13)                    ; Number of candidates to display
  (vertico-resize t)
  (vertico-cycle nil) ; Go from last to first candidate and first to last (cycle)?
  :config
  (vertico-mode))

Now we can add a few changes to the default keybindings (again, I use general.el to set keybindings):

(use-package vertico
  :custom
  (vertico-count 13)                    ; Number of candidates to display
  (vertico-resize t)
  (vertico-cycle nil) ; Go from last to first candidate and first to last (cycle)?
  :general
  (:keymaps 'vertico-map
            "<tab>" #'vertico-insert  ; Insert selected candidate into text area
            "<escape>" #'minibuffer-keyboard-quit ; Close minibuffer
            ;; NOTE 2022-02-05: Cycle through candidate groups
            "C-M-n" #'vertico-next-group
            "C-M-p" #'vertico-previous-group)
  :config
  (vertico-mode))

Extensions §

Vertico becomes much more interesting with its extensions. These extensions have to manually be cloned from the repo with a corresponding require invocation. However, with straight.el, we can do something like this to install and load them:

(use-package vertico
  ;; Special recipe to load extensions conveniently
  :straight (vertico :files (:defaults "extensions/*")
                     :includes (vertico-indexed
                                vertico-flat
                                vertico-grid
                                vertico-mouse
                                vertico-quick
                                vertico-buffer
                                vertico-repeat
                                vertico-reverse
                                vertico-directory
                                vertico-multiform
                                vertico-unobtrusive
                                ))
  :general
  (:keymaps 'vertico-map
            "<tab>" #'vertico-insert    ; Choose selected candidate
            "<escape>" #'minibuffer-keyboard-quit ; Close minibuffer
            ;; NOTE 2022-02-05: Cycle through candidate groups
            "C-M-n" #'vertico-next-group
            "C-M-p" #'vertico-previous-group)
  :custom
  (vertico-count 13)                    ; Number of candidates to display
  (vertico-resize t)
  (vertico-cycle nil) ; Go from last to first candidate and first to last (cycle)?
  :config
  (vertico-mode))

With the extensions installed, we have a lot of room to set their variables to our liking. In particular, vertico-multiform is the most interesting and, in my opinion, useful. You can choose how the minibuffer appears, which is provided by Vertico’s extensions (see more here). The current options are

buffer — minibuffer treated as a normal, separate buffer,

Vertico-buffer UI (minibuffer now a separate window)
flat — a flat format (like ido),

Vertico-flat minibuffer UI
grid — a grid format,

Vertico-grid UI
reverse — moves the area in which you type above the candidates, like selectrum,

Vertico-reverse UI. Notice the text area is below the candidates. Moreover, the candidates are in reverse order.
unobtrusive — like the vertico-flat format, but only showing the selected candidate,

Vertico-unobtrusive UI (there are multiple files in this directory, only the current candidate is shown)
indexed — allows you “to select indexed candidates with prefix arguments”

Vertico-indexed UI

These formats each have a separate minor-mode which can be activated if you want to use that format singly. However, with vertico-multiform-mode as well as configuration of vertico-multiform-categories, vertico-multiform-commands, and keybinds, you can enable/disable multiple of these formats simultaneously:

(vertico-multiform-mode)

Here are the extension variables I set in the :custom block of my use-package:

(vertico-grid-separator "       ")
(vertico-grid-lookahead 50)
(vertico-buffer-display-action '(display-buffer-reuse-window)) ; Default
(vertico-multiform-categories                                  ; Choose a multiform
 '((file reverse)
   (consult-grep buffer)
   (consult-location)
   (imenu buffer)
   (library reverse indexed)
   (org-roam-node reverse indexed)
   (t reverse)))
(vertico-multiform-commands
 '(("flyspell-correct-*" grid reverse)
   (org-refile grid reverse indexed)
   (consult-yank-pop indexed)
   (consult-flycheck)
   (consult-lsp-diagnostics)))

Here are the vertico-multiform related keybinds I have in my :general block:

(:keymaps 'vertico-map
          ;; Toggle Vertico multiforms in active minibuffer
          "C-i" #'vertico-quick-insert
          "C-o" #'vertico-quick-exit
          "M-G" #'vertico-multiform-grid
          "M-F" #'vertico-multiform-flat
          "M-R" #'vertico-multiform-reverse
          "M-U" #'vertico-multiform-unobtrusive)

These are rarely used, but can be handy.

Finally, the other Vertico extensions I configure are vertico-repeat and vertico-directory. I add the following keybinds:

(:keymaps '(normal insert visual motion)
          "M-." #'vertico-repeat) ; Perfectly return to the state of the last Vertico minibuffer usage
(:keymaps 'vertico-map
          ;; Vertico-directory which makes typing file paths in the minibuffer
          ;; more convenient. Use it to get a sense of what these do
          "<backspace>" #'vertico-directory-delete-char
          "C-w" #'vertico-directory-delete-word
          "C-<backspace>" #'vertico-directory-delete-word
          "RET" #'vertico-directory-enter)

Additionally, we need to add the following hook for vertico-repeat:

:hook (minibuffer-setup . vertico-repeat-save) ; Make sure vertico state is saved for `vertico-repeat'

Vertico extension commands §

If you’d like, you can set up a toggle between two multiforms in the minibuffer. For instance, the following function definition with a corresponding keybind in vertico-map toggles between vertico-flat-mode and vertico-reverse-mode:

(defun kb/vertico-multiform-flat-toggle ()
  "Toggle between flat and reverse."
  (interactive)
  (vertico-multiform--display-toggle 'vertico-flat-mode)
  (if vertico-flat-mode
      (vertico-multiform--temporary-mode 'vertico-reverse-mode -1)
    (vertico-multiform--temporary-mode 'vertico-reverse-mode 1)))

The following function uses vertico-quick-jump (like avy but for minibuffer candidates) to embark-act on a candidate without having to first hover over the candidate:

(defun kb/vertico-quick-embark (&optional arg)
  "Embark on candidate using quick keys."
  (interactive)
  (when (vertico-quick-jump)
    (embark-act arg)))

Niceties §

Finally, I add a few niceties.

The following prefixes (i.e. in the left fringe) and arrow character on the currently selected candidate^[1]:

;; Prefix the current candidate with “» ”. From
;; https://github.com/minad/vertico/wiki#prefix-current-candidate-with-arrow
(advice-add #'vertico--format-candidate :around
            (lambda (orig cand prefix suffix index _start)
              (setq cand (funcall orig cand prefix suffix index _start))
              (concat
               (if (= vertico--index index)
                   (propertize "» " 'face 'vertico-current)
                 "  ")
               cand)))

When using a command for selecting a file in the minibuffer, the following fixes the path so the path you select doesn’t have prepended junk left behind^[2]:

:hook (rfn-eshadow-update-overlay . vertico-directory-tidy) ; Correct file path when changed

Using find-file and going from a subdirectory in $HOME to the distant /tmp/ directory. Notice that the file-path is “cleaned up.”

Finally, the following makes working with remote files via tramp easier.

;; Workaround for problem with `tramp' hostname completions. This overrides
;; the completion style specifically for remote files! See
;; https://github.com/minad/vertico#tramp-hostname-completion
(defun kb/basic-remote-try-completion (string table pred point)
  (and (vertico--remote-p string)
       (completion-basic-try-completion string table pred point)))
(defun kb/basic-remote-all-completions (string table pred point)
  (and (vertico--remote-p string)
       (completion-basic-all-completions string table pred point)))
(add-to-list 'completion-styles-alist
             '(basic-remote           ; Name of `completion-style'
               kb/basic-remote-try-completion kb/basic-remote-all-completions nil))

End product §

In the end, we have this^[3]:

(use-package vertico
  :demand t                             ; Otherwise won't get loaded immediately
  :straight (vertico :files (:defaults "extensions/*") ; Special recipe to load extensions conveniently
                     :includes (vertico-indexed
                                vertico-flat
                                vertico-grid
                                vertico-mouse
                                vertico-quick
                                vertico-buffer
                                vertico-repeat
                                vertico-reverse
                                vertico-directory
                                vertico-multiform
                                vertico-unobtrusive))
  :general
  (:keymaps '(normal insert visual motion)
            "M-." #'vertico-repeat)
  (:keymaps 'vertico-map
            "<tab>" #'vertico-insert ; Set manually otherwise setting `vertico-quick-insert' overrides this
            "<escape>" #'minibuffer-keyboard-quit
            "?" #'minibuffer-completion-help
            "C-M-n" #'vertico-next-group
            "C-M-p" #'vertico-previous-group
            ;; Multiform toggles
            "<backspace>" #'vertico-directory-delete-char
            "C-w" #'vertico-directory-delete-word
            "C-<backspace>" #'vertico-directory-delete-word
            "RET" #'vertico-directory-enter
            "C-i" #'vertico-quick-insert
            "C-o" #'vertico-quick-exit
            "M-o" #'kb/vertico-quick-embark
            "M-G" #'vertico-multiform-grid
            "M-F" #'vertico-multiform-flat
            "M-R" #'vertico-multiform-reverse
            "M-U" #'vertico-multiform-unobtrusive
            "C-l" #'kb/vertico-multiform-flat-toggle)
  :hook ((rfn-eshadow-update-overlay . vertico-directory-tidy) ; Clean up file path when typing
         (minibuffer-setup . vertico-repeat-save)) ; Make sure vertico state is saved
  :custom
  (vertico-count 13)
  (vertico-resize t)
  (vertico-cycle nil)
  ;; Extensions
  (vertico-grid-separator "       ")
  (vertico-grid-lookahead 50)
  (vertico-buffer-display-action '(display-buffer-reuse-window))
  (vertico-multiform-categories
   '((file reverse)
     (consult-grep buffer)
     (consult-location)
     (imenu buffer)
     (library reverse indexed)
     (org-roam-node reverse indexed)
     (t reverse)))
  (vertico-multiform-commands
   '(("flyspell-correct-*" grid reverse)
     (org-refile grid reverse indexed)
     (consult-yank-pop indexed)
     (consult-flycheck)
     (consult-lsp-diagnostics)))
  :init
  (defun kb/vertico-multiform-flat-toggle ()
    "Toggle between flat and reverse."
    (interactive)
    (vertico-multiform--display-toggle 'vertico-flat-mode)
    (if vertico-flat-mode
        (vertico-multiform--temporary-mode 'vertico-reverse-mode -1)
      (vertico-multiform--temporary-mode 'vertico-reverse-mode 1)))
  (defun kb/vertico-quick-embark (&optional arg)
    "Embark on candidate using quick keys."
    (interactive)
    (when (vertico-quick-jump)
      (embark-act arg)))

  ;; Workaround for problem with `tramp' hostname completions. This overrides
  ;; the completion style specifically for remote files! See
  ;; https://github.com/minad/vertico#tramp-hostname-completion
  (defun kb/basic-remote-try-completion (string table pred point)
    (and (vertico--remote-p string)
         (completion-basic-try-completion string table pred point)))
  (defun kb/basic-remote-all-completions (string table pred point)
    (and (vertico--remote-p string)
         (completion-basic-all-completions string table pred point)))
  (add-to-list 'completion-styles-alist
               '(basic-remote           ; Name of `completion-style'
                 kb/basic-remote-try-completion kb/basic-remote-all-completions nil))
  :config
  (vertico-mode)
  ;; Extensions
  (vertico-multiform-mode)

  ;; Prefix the current candidate with “» ”. From
  ;; https://github.com/minad/vertico/wiki#prefix-current-candidate-with-arrow
  (advice-add #'vertico--format-candidate :around
              (lambda (orig cand prefix suffix index _start)
                (setq cand (funcall orig cand prefix suffix index _start))
                (concat
                 (if (= vertico--index index)
                     (propertize "» " 'face 'vertico-current)
                   "  ")
                 cand))))

Orderless §

Orderless is an alternative and powerful completion style, that is, it is an alternative to Emacs’s basic candidate-filtering capacities.

Basic §

To use orderless you simply need the following.

(use-package orderless
  :custom
  (completion-styles '(orderless))      ; Use orderless
  (completion-category-defaults nil)    ; I want to be in control!
  (completion-category-overrides
   '((file (styles basic-remote ; For `tramp' hostname completion with `vertico'
                   orderless)))))

However, we want to be more interesting! The following configures the matching styles that orderless uses. A matching style is a criterion for what is a valid candidate (a description of what each matching style does can be found in Orderless’s readme):

:custom
(orderless-matching-styles
 '(orderless-literal
   orderless-prefixes
   orderless-initialism
   orderless-regexp
   ;; orderless-flex                       ; Basically fuzzy finding
   ;; orderless-strict-leading-initialism
   ;; orderless-strict-initialism
   ;; orderless-strict-full-initialism
   ;; orderless-without-literal          ; Recommended for dispatches instead
   ))

Style dispatchers §

A first component of “lm” using the prot-orderless-strict-initialism-dispatcher style dispatcher, and a second component of “map” using the prot-orderless-literal-dispatcher.

Orderless becomes much more powerful when using its style dispatchers. A description of style dispatches can be found here. Essentially, you can choose which matching style is used for a particular orderless component. Thus, one component can use the orderless-initialism matching style while the next can use the orderless-literal matching style, and the result will be candidates which match both styles:

;; The following is taken directly from Protesilaos's Emacs configuration, with
;; very minor changes. See
;; https://gitlab.com/protesilaos/dotfiles/-/blob/master/emacs/.emacs.d/prot-emacs.el
:custom
(orderless-style-dispatchers
 '(prot-orderless-literal-dispatcher           ; = suffix for literal
   prot-orderless-strict-initialism-dispatcher ; , suffix for initialism
   prot-orderless-flex-dispatcher              ; . suffix for flex
   ))
:init
(defun orderless--strict-*-initialism (component &optional anchored)
  "Match a COMPONENT as a strict initialism, optionally ANCHORED.
The characters in COMPONENT must occur in the candidate in that
order at the beginning of subsequent words comprised of letters.
Only non-letters can be in between the words that start with the
initials.

If ANCHORED is `start' require that the first initial appear in
the first word of the candidate.  If ANCHORED is `both' require
that the first and last initials appear in the first and last
words of the candidate, respectively."
  (orderless--separated-by
      '(seq (zero-or-more alpha) word-end (zero-or-more (not alpha)))
    (cl-loop for char across component collect `(seq word-start ,char))
    (when anchored '(seq (group buffer-start) (zero-or-more (not alpha))))
    (when (eq anchored 'both)
      '(seq (zero-or-more alpha) word-end (zero-or-more (not alpha)) eol))))

(defun orderless-strict-initialism (component)
  "Match a COMPONENT as a strict initialism.
This means the characters in COMPONENT must occur in the
candidate in that order at the beginning of subsequent words
comprised of letters.  Only non-letters can be in between the
words that start with the initials."
  (orderless--strict-*-initialism component))

(defun prot-orderless-literal-dispatcher (pattern _index _total)
  "Literal style dispatcher using the equals sign as a suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
  (when (string-suffix-p "=" pattern)
    `(orderless-literal . ,(substring pattern 0 -1))))

(defun prot-orderless-strict-initialism-dispatcher (pattern _index _total)
  "Leading initialism  dispatcher using the comma suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
  (when (string-suffix-p "," pattern)
    `(orderless-strict-initialism . ,(substring pattern 0 -1))))

(defun prot-orderless-flex-dispatcher (pattern _index _total)
  "Flex  dispatcher using the tilde suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
  (when (string-suffix-p "." pattern)
    `(orderless-flex . ,(substring pattern 0 -1))))

Finally, rather than using the default “+ “ to separate components, I use a space instead:

:custom
(orderless-component-separator 'orderless-escapable-split-on-space) ; Use backslash for literal space

End product §

The end result is this^[4]:

(use-package orderless
  :custom
  (completion-styles '(orderless))
  (completion-category-defaults nil)    ; I want to be in control!
  (completion-category-overrides
   '((file (styles basic-remote ; For `tramp' hostname completion with `vertico'
                   orderless
                   ))
     ))

  (orderless-component-separator 'orderless-escapable-split-on-space)
  (orderless-matching-styles
   '(orderless-literal
     orderless-prefixes
     orderless-initialism
     orderless-regexp
     ;; orderless-flex
     ;; orderless-strict-leading-initialism
     ;; orderless-strict-initialism
     ;; orderless-strict-full-initialism
     ;; orderless-without-literal          ; Recommended for dispatches instead
     ))
  (orderless-style-dispatchers
   '(prot-orderless-literal-dispatcher
     prot-orderless-strict-initialism-dispatcher
     prot-orderless-flex-dispatcher))
  :init
  (defun orderless--strict-*-initialism (component &optional anchored)
    "Match a COMPONENT as a strict initialism, optionally ANCHORED.
The characters in COMPONENT must occur in the candidate in that
order at the beginning of subsequent words comprised of letters.
Only non-letters can be in between the words that start with the
initials.

If ANCHORED is `start' require that the first initial appear in
the first word of the candidate.  If ANCHORED is `both' require
that the first and last initials appear in the first and last
words of the candidate, respectively."
    (orderless--separated-by
        '(seq (zero-or-more alpha) word-end (zero-or-more (not alpha)))
      (cl-loop for char across component collect `(seq word-start ,char))
      (when anchored '(seq (group buffer-start) (zero-or-more (not alpha))))
      (when (eq anchored 'both)
        '(seq (zero-or-more alpha) word-end (zero-or-more (not alpha)) eol))))

  (defun orderless-strict-initialism (component)
    "Match a COMPONENT as a strict initialism.
This means the characters in COMPONENT must occur in the
candidate in that order at the beginning of subsequent words
comprised of letters.  Only non-letters can be in between the
words that start with the initials."
    (orderless--strict-*-initialism component))

  (defun prot-orderless-literal-dispatcher (pattern _index _total)
    "Literal style dispatcher using the equals sign as a suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
    (when (string-suffix-p "=" pattern)
      `(orderless-literal . ,(substring pattern 0 -1))))

  (defun prot-orderless-strict-initialism-dispatcher (pattern _index _total)
    "Leading initialism  dispatcher using the comma suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
    (when (string-suffix-p "," pattern)
      `(orderless-strict-initialism . ,(substring pattern 0 -1))))

  (defun prot-orderless-flex-dispatcher (pattern _index _total)
    "Flex  dispatcher using the tilde suffix.
It matches PATTERN _INDEX and _TOTAL according to how Orderless
parses its input."
    (when (string-suffix-p "." pattern)
      `(orderless-flex . ,(substring pattern 0 -1)))))

Changelog §

Apr 5, 2025
- Add a note at the beginning of the post alerting users of potentially outdated information as well as referencing my personal Emacs configuration.
- Minor updates to code formatting.
Feb 22, 2022 Added demonstrative images and a GIF. Added section on all-the-icons-completion.

Kristoffer Balintona — #Emacs

Surprisingly, Emacs on Android is pretty good

Table of Contents

The good and bad: what to expect on Android §

Installation §

Option 1 §

Option 2 (recommended) §

Configuring an Android-specific Emacs §

Necessary reading: the manual §

How to configure your init.el on a mobile device? §

First step: A Better UI for touchscreens §

Android-specific Commands and Options §

Use a Special virtual keyboard §

Fonts §

Tip: You can remap the volume buttons §

Conclusion §

Bonus: My wish list §

Keeping a tidy .emacs.d/ with no-littering.el

Bonus: (no-littering-theme-backups) §

Complement corfu, vertico, and completion-preview with prescient.el sorting

Bonus: integration with completion-preview-mode §

Changelog §

A surprising upside to vc-dir marks over magit

The nicety of vc-dir marks §

A caveat §

Changelog §

Neat behavior of M-x occur

Further Reading §

Citations in org-mode: Org-cite and Citar

Table of Contents

Summary §

Helpful sources §

What are citation systems? §

Org-cite §

Understanding org-cite export processors §

Which processor should I use? §

Configuration §

Usage §

Citar §

Capturing (Outdated) §

Advising citar-org-update-pre-suffix (Outdated) §

Aesthetics §

Other interesting packages §

Zotero §

Embark §

Org-roam-bibtex §

Citar-capf §

Org-ref §

Changelog §

True Emacs Transparency

Changelog §

Cape

Table of Contents

What is cape? §

Basic usage: keybinds §

Adding backends to completion-at-point-functions §

Cape-company-to-capf and cape-super-capf §

pcomplete nicety §

My completion-at-point-functions §

Changelog §

Corfu, Kind-icon, and Corfu-doc

Table of Contents

Synopsis §

Corfu §

What is corfu? How does it differ from company? §

Basic §

Working with the recent changes to corfu §

Further configuration in minibuffers and with lsp §

End product §

Kind-icon §

Corfu-doc §

Changelog §

Vertico, Marginalia, All-the-icons-completion, and Orderless

Table of Contents

Synopsis §

Marginalia §

All-the-icons-completion §

Vertico §

Basic §

Extensions §

How to configure your `init.el` on a mobile device? §

Bonus: `(no-littering-theme-backups)` §

Bonus: integration with `completion-preview-mode` §

The nicety of `vc-dir` marks §

Understanding `org-cite` export processors §

Advising `citar-org-update-pre-suffix` (Outdated) §

What is `cape`? §

Adding backends to `completion-at-point-functions` §

`Cape-company-to-capf` and `cape-super-capf` §

`pcomplete` nicety §

My `completion-at-point-functions` §

What is `corfu`? How does it differ from `company`? §

Working with the recent changes to `corfu` §

Further configuration in minibuffers and with `lsp` §