yakshaving on Karthinks

Fringe Matters: Finding the Right Difference

Wed, 25 Dec 2024 22:11:00 -0800

Continuing my avocation of writing to increasingly niche audiences, today we have a matter at the intersection of several small Venn bubbles:

the group of Emacs users who code in Emacs,
who use Git (or version control) everywhere,
who work using offshoot or feature branches,
while using the diff-hl package to visually track changes in their buffers.

As minutiae go, this one is quite minute, a real fringe matter. It’s also not a paen to Emacs’ extensibility or composability, because as much as I enjoy beating that drum the feature we’re looking for is actually in plain sight for once.

It’s just really neat though, so I’m going to describe it to you. You’re here now. Settle in.

Rise and shine, Dr. Diffman. Rise and shine.

If you load a file that’s tracked via version control into your editor, most modern text or code editors will indicate in the buffer the bits that have been modified since the last commit, i.e. the last set of registered changes. Here’s the Zed editor showing this via yellow/red marks in the fringe to the left of the text:

In Emacs this is provided by Dmitry Gutov’s diff-hl or Shohei Yoshida’s git-gutter packages, with the former pictured here:

This inline-indication business usually goes much further, with editors annotating lines with when they were last changed, or whose fault it was. My relatively tiny code or prose projects with 2-4 participants (at most) have little need for these fancier features. Emacs makes it easy enough to generate them when required anyway vc-region-history (C-x v h) and vc-annotate (C-x v g), respectively – no Magit required. .

But diff-hl is mighty handy. Being able to identify changed regions at a glance is good, but you can also navigate and act on them. Jump between hunks with one key, see changes inline, mark or revert hunks and more:

[VIDEO: diff-hl demo]

Play by play

The keys being pressed are indicated in the header.

With diff-hl-mode enabled in the buffer,
Run diff-hl-next-hunk (C-x v n). This moves the cursor to the next hunk,
and it activates a repeat-map, making subsequent diff-hl commands accessible with just n, p and so on.
Press * (shortened from C-x v * by repeat-mode) to show inline diffs of changed hunks.
After navigating some more, press SPC (shortened from C-x v SPC by repeat-mode) to mark a hunk.

The right diff in the wrong place…

There’s only one problem: when working on a branch with many commits, diff-hl tracks changes relative to the HEAD of the branch. This is almost never what I want when I’m working on a feature off in a different branch. Representing each commit as a sphere, here’s what I mean:

At this stage, the change from feature / HEAD to the worktree is at best an incomplete picture. Unless looking for something very specific, it doesn’t help to highlight worktree changes against earlier commits on feature either. The previous commits in this branch are temporary checkpoints in an experiment, and don’t necessarily represent atomic, self-contained or meaningful changes – hence the jumble of colors in each commit in the figure. What I find actually helpful is to compare the contents of the buffer to the state of the main branch:

This is, of course, readily accessible via Magit or VC via a couple of keystrokes. Either one can produce pleasingly formatted diff buffers showing the right changes for any range. But as mentioned above, being able to have the right changes indicated in the work buffer is only one of the advantages. With diff-hl and the right range of changes indicated, you can jump between them, mark them, revert them and more.

Recreating the commits in feature to encode atomic – or at least limited – changes is on the docket, but for later. This involves “unscrambling” the commits into uniformly colored spheres, often via an interactive rebase, or just selective git-resets:

Usually the true “shape” of the changes can only be limned at the end of the feature experiment, at which point a “logical” history can be forged before merging into the main branch using your preferred strategy Unless your preferred strategy is to squash all the carefully recreated, atomic commits into a giant merge commit. Then your preferred strategy is wrong. .

…can make all the difference in the world.

As it turns out diff-hl understands this problem to a limited extent. It provides a secondary minor-mode, diff-hl-amend-mode, that shows the change markers with respect to HEAD^, the parent of HEAD. This is typically what you want when your changes are intended to amend the latest commit instead of creating a new one. While it’s not what we’re looking for, it’s a good starting point.

But the mechanism is simple enough. In this pseudo Elisp block:

(show-changes-between from-commit current-buffer-state)

we’d like a way to set from-commit, but just for this buffer or project. If you use diff-hl-amend-mode, from-commit would be HEAD^. If we can set it to master or master^ (or main), we’re done.

And set it we can. from-commit is actually a single global variable conveniently exposed by diff-hl: diff-hl-reference-revision. We can deal with the globality by making it buffer local. And that’s it as far as the Elisp hacking goes – no hooks or advice needed today.

Not that I wish to imply you have been sleeping on the margins.

Only there’s still the matter of the interface. The absolute spartan way of using this option would be to run M-x eval-expression (M-:) and type in

(setq-local diff-hl-reference-revision "master")

On later uses, you can search the minibuffer history for this code via minibuffer-complete-history (M-r). After a few weeks of this, the mild frustration mounts until it crosses a threshold: I should really put this somewhere more convenient.

The logical next step is to define a command that does this. diff-hl actually includes one It’s diff-hl-set-reference-rev , but that sets it globally, across Emacs. So we sigh and grow our configuration files a little bit:

(defun my/diff-hl-set-reference ()
  "Set the reference revision for showing diff-hl changes.

Do so buffer-locally."
  (interactive)
  (setq-local
   diff-hl-reference-revision
   (read-string
    (format "Set reference revision (buffer %s): "
            (buffer-name))))
  (diff-hl-update))

Dust your hands, the problem’s solved. M-x my/diff-hl-set-reference works pleasingly for a few weeks, especially since the minibuffer completion system floats this up with frequent usage You do use savehist-mode or prescient, right? for easy access.

But eventually two further needs appear:

I use this so often that I need it on a key, dammit.
Can’t I just set this across my project instead of in every buffer?

Needs 1 and 2 obviate each other somewhat, in that either one makes it less necessary to call the -set-reference command via M-x. But let’s address them separately anyway.

All the effort in the world would have gone to waste until…

Setting up a keybind is easy if we can find room for it. And then if we can remember it. Emacs keymaps are crowded spaces. On more than one occasion I’ve opened up my init file intending to add a handy keybinding for a useful command, only to discover that I already did months ago… and then forgot it was available.

To some extent you can mitigate this effect by placing it logically with the other diff-hl commands, which are conveniently grouped together into diff-hl-command-map. So assuming you use any diff-hl commands, this one should show up in which-key or your keymap prompter of choice.

But in my case even this is a lost cause. I already combine vc-prefix-map, used by Emacs for version control actions, with diff-hl-command-map under the C-x v prefix because their functions are related. So C-x v is quite a busy junction. Here’s which-key doing its best to show me what’s available:

The solution is to place it where I turn on/off diff-hl-mode in the first place: in a catchall transient menu I use to access all minor-modes I need in Emacs buffers A good chunk of this menu deals with settings that make no sense for most Emacs users – for example, a switch to toggle requiring sentence ends to be single/double spaced, adjust line-spacing on the fly, or switch between different sets of CAPFs.

Calling the diff-hl option from this menu with a prefix-arg now (essentially) runs the above function, allowing me to set the reference revision before turning on the mode (if required).

Here’s a demo combining this with a few other nifty diff-hl commands and repeat-mode:

[VIDEO: Toggling diff-hl reference revision]

Play by play

The keys being pressed are indicated at the top.

Begin in a buffer in some feature branch that is some “distance” away from master.
Use diff-hl commands to navigate to hunks. diff-hl is currently showing buffer changes in the working tree against HEAD.
Use diff-hl-show-hunk (C-x v *) to see the diffs for individual hunks inline.
Call the toggle-modes transient mentioned above.
Choose the g option with a prefix-arg (C-u). This causes the reference revision (the from-commit we want) to be read from the minibuffer. Ask to see changes from master.
diff-hl updates to mark changes from master. As you might expect, there are more changes – everything that’s changed since master.
Navigate through the changes again with diff-hl commands.
Pick the toggle-modes transient menu option again, this time setting the reference revision to HEAD’s grandparent, HEAD^^.
diff-hl updates the changes again. As you might expect, there are fewer changes.

Here’s the actual function that g in the toggle-modes menu is bound to:

(lambda (&optional arg)
  "Toggle `diff-hl-mode'.

With prefix ARG ensure `diff-hl-mode' and set revision to compare
against."
  (interactive "P")
  (if (null arg)
      (diff-hl-mode 'toggle)
    (let ((ref (read-string "Reference revision for diff-hl: ")))
      (setq-local diff-hl-reference-revision ref)
      (diff-hl-mode) (diff-hl-update)
      (message "Showing changes against %s" ref))))

…well, let’s just say your hour has come again.

As you might expect, the way to apply diff-hl’s reference revision setting to all buffers in a project is to use a directory-local variable. In most cases, setting it once per project (or git-worktree, in my case) is all you need.

This approach requires a little forethought but no moment-to-moment busywork: Run M-x add-dir-local-variable

with a major-mode choice of nil,
and setting the variable diff-hl-reference-revision
to "master" .

This produces the following .dir-locals.el file:

;;; Directory Local Variables            -*- no-byte-compile: t -*-
;;; For more information see (info "(emacs) Directory Variables")

((nil . ((diff-hl-reference-revision . "master"))))

Typically you would want to chuck this file into version control as well – but in this case that may be something you want to consider carefully!

So, wake up, Dr. Diffman. Wake up and mark the fringes.

Before I thought to adapt diff-hl to how I worked, I was coding in feature branches in a strange way. I would make a bunch of work-in-progress checkpoint commits and store them on a remote, then soft-reset the branch to the original branch point so I could see indicators for all changed regions in buffers, jump between them with diff-hl-next-hunk and so on.

It took a while a “while” is code for years to consider that it didn’t have to be this way. This isn’t an adjustment that requires Emacs’ much vaunted flexibility – you can probably do this in any editor that provides the diff-hl feature. I just never thought to do it, and worked around the tool instead of making the tool work for me. Well that’s sorted.

There is no other upshot. This yak has been shaved. You’re free now, go mark some fringes.

For Your Reference: RefTeX in Org Mode

Fri, 16 Feb 2024 04:48:00 -0800

TL;DR: “We have X-references at home”

Cross-references in Org mode are not as well developed as its (relatively) new citation system. Org’s built-in linking system is fairly comprehensive and exports to all formats well enough. But if you’re coming to Org from LaTeX, you might prefer something more familiar and oriented towards the label/references mental mapping than the anchor/link system. Over the decades, I drifted into Org mode from writing LaTeX, and brought along RefTeX support. Sort of.

In the past few months I received a number of questions about my usage of LaTeX-style cross-references in Org, so here’s a short explanation and, uh, reference.

Just give me the code

One half of my long-winded Emacs articles begin or end with a call to action:

…and it’s a package, and here’s a link, it’s on MELPA, try it out.

This is not one of those. There is a package, and more code besides. But this is stuff extracted from my Emacs init file, which is a cross between a palimpsest, a crime scene and a dry-erase board that don’t erase no more. Use at your own peril, or better yet, reuse these ideas to make something coherent and plug-and-play:

consult-reftex: A better interface to RefTeX, with Consult
reftex-xref: xref and eldoc support for RefTeX
Some configuration to turn on these enhancements.

Demos and explanations below.

Background: `org-link`, `org-ref` and `oxr`

There are other solutions – actual solutions – for cross-references in Org mode. Org’s built-in linking system can be repurposed for this, and it will export to all document formats. Bruce D’Arcus’ oxr is a proof of concept of a cross-referencing system built on top of Org’s links. For LaTeX exports, there’s John Kitchin’s frighteningly full-featured org-ref, with simple and elegant cross-referencing syntax.

One of these is probably what you want.

One of these is probably what I would have used if I had given my slow transition from LaTeX to Org any active thought. Instead I just continued to use RefTeX.

What’s a RefTeX?

RefTeX is an Emacs minor mode with distinct support for \ref, \label, \cite, and \index commands in (multi-file) LaTeX documents. It is included with Emacs.

The official description undersells it. RefTeX is extensive: it supports cross-references and citations, semi-automatic label creation, reference tracking and updates, indexes, multi-file documents, references to external documents, a dynamic table of contents and more, and provides the means to do everything that we’re about to do more clumsily below.

In a happy coincidence, RefTeX works without a hitch in Org documents… to a point It gets dicey with multi-file Org documents. . This is an oft-ignored advantage of regexp-based, structure-agnostic parsing – once you iron out the many, many edge cases over a few years, it tends to work pretty much everywhere. RefTeX’s Org mode “support” is good enough for my purposes, and having it work the same in Org and LaTeX documents is a bonus.

It even integrates with cdlatex and org-cdlatex, with automatic label insertion when inserting environments. (This is not a coincidence.)

There are two limitations.

Obviously, LaTeX style cross-references only work with LaTeX exports.
The other issue with RefTeX, and the main focus of this write-up, is the UI. It’s very… 90s, let’s say. Better previewing, faster navigation, integration into the modern Emacs API, some DWIM behavior – these are all achievable with a few band-aids. The result is a patchwork, but that’s most things Emacs.

Finally, there’s one other deep connection between RefTeX, CDLaTeX and Org mode. It’s two words. Take your guesses, or open up reftex.el and read the header!

Sprucing up the RefTeX experience

A reassertion: RefTeX already works reasonably well in Org mode, and you can work around edge cases if you encounter them. The write-up until now was thus mainly a PSA. What follows is minor improvements to the UI and the general experience of Org when using RefTeX.

Insert references with `consult-reftex`

As mentioned above, RefTeX is a kitchen sink library – it provides everything you need to manage references, including a multi-step reference insertion menu. But this process leaves a bit to be desired:

I wrote consult-reftex a while ago to provide a better interface for reference creation: The LaTeX previews in the buffer, in consult-reftex’s previews and elsewhere are from Org’s upcoming LaTeX preview system overhaul.

[VIDEO: consult-reftex label insertion]

Play by play

Call consult-reftex-insert-reference to insert a reference at point. I’ve bound it to a snippet, so I invoke it by typing in ref and pressing TAB instead.
This command presents a completing-read interface where you can narrow the candidates to just equations, figures, sections etc. Candidate objects are previewed above the minibuffer.
You can choose how to insert this reference (as a \ref, \eqref, \cref etc).
Repeat this a couple of times.

I wrote it for LaTeX documents, but thanks to RefTeX’s flexibility it works all the same in Org mode.

Looking up references: `consult-reftex` (again)

The preview interface for consult-reftex serves a second purpose – you can use it as a listing of the equations in your document (by label), and act on labels via Embark.

[VIDEO: consult-reftex to look up labels]

Play by play

Same usage pattern, different focus from the above

Cycle through labeled objects (equations/sections etc) in the document
Invoke Embark on a candidate to access additional RefTeX actions: change the label (and all references to it), reparse the file, etc.

I don’t do this when writing, but it’s occasionally useful when reviewing work.

Fontify…

RefTeX labels in Org are plain by default,

so a little syntax highlighting goes a long way:

(font-lock-add-keywords
   'org-mode
   '(("\\(\\(?:\\\\\\(?:label\\|ref\\|eqref\\)\\)\\){\\(.+?\\)}"
      (1 font-lock-keyword-face)
      (2 font-lock-constant-face))))

I didn’t bother making a comprehensive regexp for font-locking here, you might want to thrown in more keywords.

This is more than eye-candy: a little further below, we use the faces we specify here as anchors for jumping between references. If you use different faces for the keywords, you’ll need to update the navigation code below.

…and Prettify: `TeX-fold-mode`

TeX-fold-mode, provided with AucTeX, is useful for shortening long references by placing overlays over them.

Before:

After (with the mouse over one of the references):

The effect is purely visual, moving the cursor into the overlay reveals the full reference:

[VIDEO TeX-fold-mode]

This requires turning on TeX-fold-mode.

It can fold most LaTeX constructs, including environments, sections, comments and even individual math symbols and operators. We’re only interested in folding references and labels here, though, so we can specify this:

(setq TeX-fold-type-list '(macro))

You can make this Org mode-specific with a hook if you want to fold more constructs in LaTeX documents.

Optional: we can tweak the overlay styling for labels and refs as well:

Reference/Label folding style: code

;; Faces
(set-face-attribute 'TeX-fold-folded-face nil :foreground nil :inherit 'shadow)
;; Custom folded display for labels and refs
(defun my/TeX-fold-ref (text)
  (let* ((m (string-match "^\\([^:]+:\\)\\(.*\\)" text))
         (cat (or (match-string 1 text) ""))
         (ref (or (match-string 2 text) text)))
    (when (> (length ref) 13)
        (setq ref (concat (substring ref 0 6) "..." (substring ref -6))))
    (concat "[" (propertize cat 'face 'shadow) ref "]")))
(defun my/TeX-fold-label (&rest texts)
  (cl-loop for text in texts
           for m = (string-match "^\\([^:]+:\\)\\(.*\\)" text)
           for cat = (or (match-string 1 text) "")
           for ref = (or (match-string 2 text) text)
           collect (concat "[" (propertize cat 'face 'shadow) ref "]") into labels
           finally return (mapconcat #'identity labels ",")))
(setq-default TeX-fold-macro-spec-list
              '((my/TeX-fold-label ("cite"))
                (my/TeX-fold-label ("label"))
                (my/TeX-fold-ref ("ref" "pageref" "eqref" "footref"))))

Lastly, you might want to turn folding on in Org buffers. TeX-fold uses the C-c C-o key as a prefix, watch out for key conflicts with Org!

(add-hook 'org-mode-hook 'TeX-fold-mode)

Moving around references: big ol’ pile o’hacks

This is mostly to avoid having to use the mouse – Isearch or Avy aren’t very useful if the reference is folded. That said, its main advantage is not that it moves the cursor (for editing), but that it enables other actions we might want to take immediately after, such as jumping to the definition of a label with xref.

[VIDEO: Jumping around reftex references]

Play by play

I jump to the next reference with M-g r, and then jump forward and backward across references, labels and citations with M-g r and M-g R. Actually, after invoking it once I jump forward and back with just r and R, thanks to repeat-mode. The code is below.

We want several things to happen when we jump to a reference:

Org should open up folded/invisible text if the references is in a hidden region,
Any TeX-fold overlay at the reference should be cleared,
and if we jumped from a reference it should be folded again by TeX-fold.
If a preview is available (via Eldoc, see below), it should be activated.

The code for this is below. It’s not pretty.

Jumping by reference: code

(defun my/next-reference-or-label (_arg)
    (interactive "p")
    (let* ((prop))
      (pcase-let
          ((`(,_ . ,ov)
           (get-char-property-and-overlay (point) 'TeX-fold-type)))
        (when ov (TeX-fold-hide-item ov)))
      (save-excursion
        (and (setq prop (text-property-search-forward
                         'face nil
                         (lambda (_ val)
                           (memq val '(font-lock-constant-face org-cite)))
                         t))))
      (if prop
          (progn (goto-char (prop-match-beginning prop))
                 (when (and (derived-mode-p 'org-mode) (org-invisible-p))
                   (org-fold-show-context 'link-search))
                 (when eldoc-mode (eldoc--invoke-strategy t))
                 (pcase-let
                     ((`(,_ . ,ov)
                      (get-char-property-and-overlay (point) 'TeX-fold-type)))
                   (when ov (TeX-fold-show-item ov))))
        (message "No more references/labels."))))

(defun my/previous-reference-or-label (_arg)
   (interactive "p")
   (let ((p))
     (save-excursion
       (and (text-property-search-backward
             'face nil
             (lambda (_ val)
               (memq val '(font-lock-constant-face org-cite
                           TeX-fold-folded-face)))
             t)
            (setq p (point))))
     (pcase-let
         ((`(,_ . ,ov)
           (get-char-property-and-overlay (point) 'TeX-fold-type)))
       (when ov (TeX-fold-hide-item ov)))
     (when p
       (goto-char p)
       (when (and (derived-mode-p 'org-mode) (org-invisible-p))
         (org-fold-show-context 'link-search))
       (when eldoc-mode (eldoc--invoke-strategy t)))
     (pcase-let
         ((`(,_ . ,ov)
           (get-char-property-and-overlay (point) 'TeX-fold-type)))
       (when ov (TeX-fold-show-item ov)))))

While we’re at it, we might as well make this command repeatable, so you can navigate with just r and R after the first jump:

(keymap-set org-mode-map "M-g r" 'my/next-reference-or-label)
(keymap-set org-mode-map "M-g R" 'my/previous-reference-or-label)
(defvar-keymap my/TeX-ref-map
  :repeat t
  "r" 'my/next-reference-or-label
  "R" 'my/previous-reference-or-label)

Jumping to definition: `xref` support, more hacks

With the cursor at a reference, jump to the corresponding label using Emacs’ standard xref mechanism:

[VIDEO: reftex-xref]

Play by play

Jump to the next reference with M-g r, as before.
Jump to the corresponding label with M-., Emacs’ standard keybinding for xref-find-definitions.
Jump back with M-,, Emacs’ standard keybinding for xref-go-back.
Repeat a couple of times.

Code below. Again, not pretty.

xref support for RefTeX: code

(require 'xref)
(require 'reftex-ref)

(cl-defmethod xref-backend-identifier-at-point ((_backend (eql reftex)))
  (when (looking-back "\\\\\\(?:page\\|eq\\|auto\\|c\\)?ref{[-a-zA-Z0-9_*.:]*"
                                      (line-beginning-position))
		    (reftex-this-word "-a-zA-Z0-9_*.:")))

(cl-defmethod xref-backend-definitions ((_backend (eql reftex)) prompt)
  (unless (symbol-value reftex-docstruct-symbol) (reftex-parse-one))
  (when-let* ((docstruct (symbol-value reftex-docstruct-symbol))
              (data (assoc prompt docstruct))
              (label (nth 0 data))
              (file  (nth 3 data))
              (buffer (or (find-buffer-visiting file)
                          (reftex-get-file-buffer-force
                           file (not reftex-keep-temporary-buffers))))
              (re (format reftex-find-label-regexp-format (regexp-quote label)))
              (found (with-current-buffer buffer
                       (or (re-search-backward re nil t)
                           (progn (goto-char (point-min))
                                  (re-search-forward
                                   (format reftex-find-label-regexp-format2
                                           (regexp-quote label))
                                   nil t))))))
    (list (xref-make prompt (xref-make-buffer-location
                             buffer found)))))

(cl-defmethod xref-backend-apropos ((_backend (eql reftex)) pattern)
  (xref-backend-definitions 'reftex pattern))

(defun reftex-xref ()
  "Function to activate buffer-local backend.
Add this function to `xref-backend-functions' to use xref to find
function and variable definitions in the same buffer.

This should have a low priority among xref backends."
  'reftex)

;; Eldoc support via xref, because why not
(defun reftex-xref--display-in-eldoc (callback)
  "Display reference label location in Eldoc.

Call CALLBACK if possible."
  (when (cl-intersection
         (ensure-list (get-char-property (point) 'face))
         '(font-lock-keyword-face font-lock-constant-face
           TeX-fold-unfolded-face))
    (save-excursion
      (when-let*
          ((inhibit-redisplay t)
           (_macro (car (reftex-what-macro-safe 1)))
           (key (reftex-this-word "^{}%\n\r, \t"))
           (item (car (xref-backend-definitions 'reftex key)))
           (location (xref-item-location item))
           (pos (xref-buffer-location-position location))
           (docstring
            (with-current-buffer (xref-buffer-location-buffer location)
              (goto-char pos)
              (pcase-let
                  ((`(,start . ,end)
                    (condition-case nil
                        (LaTeX-find-matching-begin)
                      (:success
                       ;; Found \begin{}...\end{}
                       (cons (point)
                             (progn (forward-char 1)
                                    (LaTeX-find-matching-end)
                                    (point))))
                      (error
                       ;; No \begin, find \section{} or Org heading instead
                       (goto-char pos)
                       (re-search-backward
                        (pcase major-mode
                          ('org-mode "^*")
                          (_ (concat "\\(" (LaTeX-outline-regexp)
                                     "\\|\\`\\)")))
                        (line-beginning-position -2)
                        t)
                       (cons (line-beginning-position)
                             (line-end-position))))))
                (buffer-substring-no-properties start end)))))
        (if-let* ((prop-and-ov
                   (get-char-property-and-overlay
                    (xref-buffer-location-position location)
                    (pcase major-mode
                      ('org-mode 'org-overlay-type)
                      ('latex-mode 'category))))
                  (_ (memq (car prop-and-ov)
                           '(org-latex-overlay preview-overlay)))
                  (ov (cdr prop-and-ov)))
            (funcall callback (propertize docstring 'display
                                          (overlay-get ov 'preview-image)))
          (funcall callback docstring))))))

(defun reftex-eldoc-activate ()
  (add-hook 'eldoc-documentation-functions
            'reftex-xref--display-in-eldoc
            nil :local))

(defun reftex-xref-activate ()
  "Activate reftex support using xref."
  (add-hook 'xref-backend-functions
            'reftex-xref nil :local))

(provide 'reftex-xref)

To turn on xref support for references in Org mode:

(use-package reftex-xref
  :after (org latex)
  :hook (org-mode . reftex-xref-activate))

Auto-preview reference at point: `eldoc` support

If you’re jumping to label definitions with xref just to look at the corresponding equations, we can skip that step with previews of the referenced object. With eldoc-mode Eldoc is Emacs’ standard and recommended way of showing contextual help. enabled:

[VIDEO: reftex-eldoc]

Play by play

With eldoc-mode enabled, move the cursor into (or jump into) a reference.
This activates a preview of the relevant label, mostly equations in this example.
Works for sections too, but not figures or tables (yet).
Repeat a few times.

Equations and figures can be pretty tall, so if you’re not using a dedicated Eldoc buffer (or eldoc-box) you might want to change the height that the echo area can expand to.

(setq eldoc-echo-area-use-multiline-p t
      max-mini-window-height 0.4)

To activate reference previews as an Eldoc documentation function, we use the helper function defined as part of reftex-xref above.

(use-package reftex-xref
  :after (org latex)
  :hook (org-mode . reftex-eldoc-activate))

Yep, `reftex-dcr` exists

Earlier I mentioned that we would be clumsily recreating features RefTeX already includes. Indeed, most of the above features, like jumping to label definitions and previewing the reference at point, are already provided in the reftex-dcr library, included with RefTeX. The problem is that it predates Emacs’ xref and eldoc APIs (if not their libraries), and like most 90s Emacs packages it reinvents all the wheels. This is painful on more than an aesthetic level – I prefer to have one well-supported and convenient way for each semantic task. The mental model is simpler, as are the required keyboard gymnastics.

Thankfully, there’s enough of a separation between the data-parsing RefTeX backend and the UI that I was able to drive a wedge through and beat it into a more consistent shape. Needless to say, this shape is not very robust. Emacs makes it very easy to cobble together an 80% solution – I spent much longer writing this little explainer than I did actually slapping together the code. Due to a pies ≫ fingers situation, I’m not going to be able to get these hacks to a stage beyond “it works for me”. The interest around this topic suggests that perhaps someone might be interested in developing the idea further and modernizing RefTeX, or working on a better cross-referencing system for Org mode. Have at it!

Different Strokes For Different Folks

Fri, 24 Nov 2023 15:15:00 -0800

A modest defense of the rodent

So, Emacs and the mouse. This is an unexpectedly contentious topic, with discussions that end, at best, with careless dismissal. More often they turn into arguments with folks talking past one another.

The advantages of using the mouse for common actions in Emacs are immediate and obvious. Window selection is a natural extension of basic mouse usage. Resizing windows is a snap. Context (right-click) menus See context-menu-mode. and drag and drop support, which improve with each new Emacs release, are very intuitive. The mouse provides access to basic editor functions with no learning curve, and no exhortations to work through the Emacs tutorial are necessary. Also, feature discoverability via Emacs’ menu-bar is surprisingly good.

Unfortunately, I have to address the rodent in the room carefully before we can talk about mitigating the many disadvantages of mouse-first interaction, since Emacs users tend to be very opinionated about this topic. Ergonomics, speed, and efficiency are three common reasons people advocate for the keyboard against the mouse for non-graphical work. I’m not convinced any of these arguments hold water. The first two are research-worthy topics on their own, with many quotable precedents, and beyond my ability to argue for or against convincingly just from personal experience Besides, anyone who’s had bouts of RSI has made up their mind already on this topic. . On the matter of speed, for instance, I am obliged to include this quote because y’all are going to send me emails linking to it otherwise:

We’ve done a cool $50 million of R & D on the Apple Human Interface. We discovered, among other things, two pertinent facts:

Test subjects consistently report that keyboarding is faster than mousing.

The stopwatch consistently proves mousing is faster than keyboarding.

– Bruce Tognazzini

So let’s pretend for the purpose of today’s discussion that we’re not concerned about the difference in editing speed one way or another.

In the context of Emacs specifically, there are further disadvantages. For example, mouse actions compose in limited ways (such as when dragging to form selections) and cannot build on each other like key sequences can with prefix keys and transient maps. You can’t automate mouse usage with keyboard macros easily.

But today we’re primarily going to address the third reason: efficiency.

I find the arguments about efficiency, in the sense of poor expressivity or economy of motion, shortsighted at best. Here are two facets of this argument, where “mouse” includes any kind of pointing device.

Economy:

Frequent context switching between the keyboard, mouse and keyboard+mouse is wasteful and causes low amounts of constant friction.

Expressivity:

Mouse usage has a low ceiling: it makes easy tasks trivial but involved actions impossible. Adding buttons or widgets to the screen doesn’t scale.

Economy and interprogram contexts

Economy first. I actually agree with the context switching argument, to the extent that the friction of repeated switching feels progressively more annoying. But the conclusion – it’s best to avoid the mouse to avoid context switching – is shortsighted because it only applies if you’re only ever in Emacs and never have to use the mouse, or conversely if you’re never in a text editor and always in a mouse-driven (or keyboard+mouse driven) application like a 3D modeling tool or a big commercial IDE. Most of us are somewhere in the middle.

I’m as keyboard-centric as you can reasonably get: besides Emacs, I use a tiling window manager, a keyboard-driven web browser and mostly TUI applications. Keybindings are the topic I’ve written the most about on this website – an embarrassing amount of yakshaving devoted to an inane subject. Even so, I use the mouse frequently because it’s often the best way to select text, images and links, do graphical work, and to interact with (both simple and complex) GUI software.

When working on something that involves Emacs and one of these mouse driven applications, having to move over to the keyboard for the Emacs bit is exactly the friction we’d like to avoid. The other app may not be flexible, but Emacs is! So we don’t need to switch to the Emacs-typical both-hands-at-keyboard context. Here are a few examples of quick interprogram interaction involving Emacs that you can easily do without moving your hand off the mouse.

Pasting text from other applications into a new buffer

Switch to a scratch buffer+window in Emacs to paste some text:

[VIDEO: Create a scratch buffer with strokes]

I use a mouse gesture in Emacs to create a scratch buffer in Org mode – courtesy of the scratch package – then drag some text into it Incidentally, the text is a LaTeX environment that is rendered automatically via Org’s new LaTeX preview system. . I then switch back to the previous buffer using another mouse gesture.

git-clone from a repository URL

[VIDEO: git-clone from repository URL]

Middle click to paste a link from the clipboard. (This is only for clarity, it’s unrelated to the actual action.) Then use a mouse gesture to git-clone from that link to a prespecified directory.

open a project directory in dired so we can drag and drop a file

[VIDEO: project directory in dired]

Use a mouse gesture to bring up a list of directories in the active project. Pick one – also using the mouse – then drag an image file into dired before switching back.

mpv + live video transcript in Emacs

Control mpv (a video player) by clicking around in a live transcript file in Emacs:

[VIDEO: live, clickable transcripts with elfeed-tube]

No mouse gestures here – the clickable transcripts and mpv connection are provided by elfeed-tube, which was designed to be usable with the mouse since it involves interacting with a video player.

My counter-argument can be summarized: Use the lowest effort means of interaction in each context you work in. Often this means driving Emacs with the mouse.

Expressivity

The expressivity counterargument: Buttons and widgets indeed don’t scale, but they bear the additional burdern of discoverability. Mouse interactions in Emacs don’t have to be prescribed or discoverable – when they are actions we set up, typically after repeatedly observing a cumbersome task that could be mouse-driven. Point-and-click in an editor is not as expressive as full-on keyboard usage, but that’s only true in the generic sense. The relevant question is if we can express the specific verbs that we care about, and from the above demos it’s clear we can.

An example: considering that using the mouse to select and resize windows is already a more natural experience than spamming C-x o and friends (or your evil-mode equivalents), it is possible to extend it to be a more comprehensive approach to window and buffer management:

[VIDEO: strokes window handling demo]

This demo showcases the use of mouse gestures to do the following:

Split the frame vertically and horizontally
Delete windows
Cycle through buffers in windows by left and right clicking the buffer name in the mode line.
Delete other windows
Swap windows to the right and left
Toggle between the last two buffers shown in a window
Go back to a previous window configuration (via tab-bar-history-back or winner-undo)

How to mouse around

This is not, strictly speaking, an article on how to use the mouse in Emacs – it’s more about why and when. For the how I suggest reading Philip Kaludercic’s write-up. You could also try just clicking around, especially in the mode line! However the use of gestures in Emacs rarely gets much attention, so here we go.

For once, this is going to be a short description, since this is a batteries included situation. Emacs ships with everything you need.

Adding mouse gesture support to Emacs is easy with the included Strokes library Many thanks to David Bakhash and the Emacs maintainers for strokes.el. . For each action you want to map to a gesture,

Find or (optional) write a command that does the thing.
Set it to a mouse stroke (gesture) with strokes-global-set-stroke.

That’s it M-x strokes-help has more information. .

Optionally, you could change the mouse button you hold down to perform a gesture. The default is S-mouse-2, which is rather awkward. I use a side button on my mouse (typically the “forward” button):

(keymap-global-set "<down-mouse-9>" 'strokes-do-stroke)

Also optionally, you can hide the live-display of the stroke as you draw (strokes-use-strokes-buffer) – I left it in for clarity in the demos.

I’ve not had to customize anything else about the strokes library, but feel free to explore – it has support for multi-glyph (complex) strokes, for instance.

There are a few general mouse settings you might be interested in:

mouse-autoselect-window: Set to t for focus-follows-mouse behavior inside Emacs. Typically what you’d want if you use mouse gestures.
mouse-drag-and-drop-region: To enable text drag-and-drop within Emacs,
mouse-drag-and-drop-region-cross-program: (Emacs 29+) and across programs from Emacs.
dired-mouse-drag-files: To drag files from dired to other programs.

Improving Strokes

Mouse gestures are a decades-old concept, as many features included with Emacs are. And the Strokes library has a list of notes and todos, as many features included with Emacs do.

No contextual actions: The use of strokes is limited, as of Emacs 29, by the lack of support for mode-specific or buffer-local strokes. This means the same gesture cannot do different things in different contexts without writing cumbersome, bespoke dispatch commands to handle this.
Somewhat unreliable gesture matching: Drawing with the mouse or trackpad is fuzzy and imprecise. The matching algorithm is quite rudimentary and there are mismatches when you have many strokes defined (> 25, let’s say), even with an increased “grid” resolution when drawing. Fixing 1 can take the pressure off the matching algorithm, but we could also use a more sophisticated approach to matching.
No multi-touch gestures: This can increases the dimensionality of the gesture space, allowing for a greater number of “basic strokes” – although the OS usually captures and maps most of these for its window management.

Despite these limitations, this is a very handy tool. I’m not sure why gestures aren’t more common – we only see them on touch interfaces these days. You can draw them anywhere on the screen, and they tolerate a fair bit of fuzz. They avoid the problem of having to move the mouse over to a small target on screen. Not having to fill the screen up with buttons is a win by itself. The only significant problem appears to be that they’re not (re)discoverable, but this isn’t a problem inside Emacs: we have strokes-describe-stroke (like describe-key) and strokes-list-strokes.

It’s not all or nothing. It’s not even something.

Some of the “talking past each other” I mentioned in the beginning is because of assumptions we make about using the mouse in text editors. We gravitate to one of two specious requirements:

The mouse should substitute for the keyboard, such as when using menu or toolbar buttons instead of keybindings.
The mouse should complement the keyboard, so we work best with a hand each on the keyboard and mouse. (This is the Acme editor approach.)

Actual usage patterns are messier than either of these. Sometimes we’re working in a mouse-heavy context, sometimes it’s two handed keyboarding, sometimes its a mix. Often the editor is at the periphery of the task at hand, sometimes it’s dead center This is true despite Emacs swallowing up my desktop applications. Calendar, email, reading, some web browsing… the list keeps growing. . Any degree of flexibility on the part of the editor is welcome. Instead of dismissing the mouse on the basis of the available design affordances, it can help to think about what we actually care to avoid – frequent context switching for me, your answer will be different – and how driving Emacs with the mouse helps us do that.

Cool your heels, Emacs

Mon, 14 Aug 2023 17:54:00 -0700

TL;DR: Sometimes Emacs needs a timeout

A diamond is very pretty. But it is very hard to add to a diamond. A ball of mud is not so pretty. But you can always add more mud to a ball of mud.

– Gerald Sussman, paraphrasing Joel Moses

A common problem with Emacs’ giant ball of shared state: Any code can step on the feet of any other – including yours. There are conventions in place to keep this from being too much of an issue: Code included in Emacs is tested extensively for edge cases by the tireless maintainers, and third-party package authors are generally careful these days about stepping on too many toes.

In practice the casualty here is not correctness, it’s performance. Emacs can, as of today, only do one thing at a time. So every “background” task must, at some point, surface to the foreground and block Emacs for a bit Many types of “background” processing are interruptible by signalling a quit with keyboard-quit, but then the task isn’t done! This doesn’t help the situation beyond giving you control of Emacs again. .

The resultant hitching is experienced both with commands you initiate ("push operations", let’s say) and timers that run code without your involvement ("pull operations"). Every hook and timer installed by packages to dazzle you with real-time updates or feedback is another fraction of a second for which Emacs is blocked. Ideally these run when Emacs is idle and you don’t notice them. In practice there are many cases, especially with “push operations”, that involve significant chunks of synchronous auxiliary processing.

Under these limitations, a few obvious solutions present themselves.

As a package author, you can

Use conservative defaults

…or provide user options to selectively turn off or extend these timers. Packages for which responsiveness is a marquee feature generally do a good job of this.

Account for as many contexts as possible

…when writing packages.

Elisp code doesn’t always run in the context that the author intends. A mode-line update in one window can stagger image display in another. In-buffer completion can slow down keyboard macro execution. The more overarching the mode, the larger the surface area for these kinds of interactions. The list of ways in which a sprawling library like Org+plugins can slow down Emacs (and vice-versa) is long and convoluted. Few Emacs packages can afford the foresight to be, essentially, paranoid defensive drivers that guard against this unpredictable traffic.

These examples are not hypothetical

mode-line update affecting image display: The first example was pdf-tools’s pdf-misc-size-indication-minor-mode freezing Emacs when updating LaTeX preview images in an unrelated buffer/window.
The second is a completion-at-point front-end like Company slowing down playback when using Macrursors, a multiple-cursors emulator that uses keyboard macros.

As a user, you can:

Report slowdowns

…so package maintainer(s) can fix them.

This is easier said than done. Binary-searching your way by toggling active modes is tedious. Profiler output can be mysterious without a good sense for how Emacs’ command loop works. A package like explain-pause-mode does some of this work for you, but the causes can be subtle interactions. Generally – but not always – if you are at the point where you can pinpoint causes of slowdowns, you can also avoid them without much trouble.

Use fewer packages

Turn down the bling. Use less mud.

The saner option. Emacs’ first-class extensibility, one of its biggest strengths, is also an inherent limitation. A significant fraction of complaints I read about Emacs being too slow are usually the result of installing packages with wild abandon. This results in busy, full-fat hooks (post-command-hook, post-self-insert-hook, window-state-change-hook, …) Among many others, like major-mode hooks. These hooks contain functions that run after every Emacs command, after typing in text, after window changes… i.e. all the time. that bring things to a crawl before long.

All right! That was the preamble. Now that we’ve exhausted the good options, we’re free to ignore the less-is-more approach to code today. It’s time to be irresponsible and fix the giant mud ball by… adding more mud.

Timeouts and Delays

The problem common to both “push” and “pull” slowdowns is non-critical code running more often than it should. Our no-context, no-Chesterton’s-fence solution is to force such code into a timeout. There are two common ways of doing this, with different use patterns, and we’re going to implement both.

First up: Throttle

Throttled code (foo) is placed in a timeout after it runs once. Attempts to run again for the duration of the timeout (the “Throttle time” above) are ignored. See this resource for an interactive explanation.

In the context of Emacs, throttling works well for “pull operations”, i.e. code that runs non-interactively and independent of user input Typically this means messing with timers, which is generally a bad idea… but we covered all the good solutions already, didn’t we? . Throttling user commands (or their consequents) leads to state changes being completely ignored, which is rarely what we want.

Of course, if packages with over-eager timers allow for customizable eagerness, then the simpler solution is to tweak the frequency directly. Packages that implement “pull operations” are generally conscientious about this. If something is running far more often than it should, searching for the variable(s) <package-name>-*-delay or <package-name>-*-timer is a good start to fixing it. Further, these actions typically run on idle timers, which is like a built-in debounce and unlikely to block Emacs in a perceptible way.

But there are many exceptions. What we’d like, in the absence of a provided dial for tuning this, is an elisp function or macro that can easily – and generically – throttle any other elisp function.

Second: Debounce

Debounced code (foo) runs after a pre-specified delay from when it is called (the “Debounce time” above). If the command is called again before the delay ends, it resets to its full duration. See this resource for an interactive explanation.

In the context of Emacs, debouncing makes more sense with “push operations”. Debounced user commands are ignored when there are too many calls in quick succession, except for the last one. This is typically what we want in an interactive context, since the intermediate states from running each call would have been invalidated by the next call anyway.

Again, we want an elisp function or macro that can easily – and generically – debounce any other elisp function.

Aside: Memoize

i.e. just caching – store the results of expensive calculations and use a look-up table instead. Emacs 29+ includes a handy with-memoization macro to facilitate this for any chunk of code. We do a bit of caching with the throttle implementation below. But in general this doesn’t work for our purposes because the functions we want to use this with are rarely pure – they work by side-effect using (and on) Emacs’ current state as a potential input. So there’s no way to provide a generic memoization routine without knowing what the specific code in question is doing.

`throttle!` and `debounce!`

What we’d like: given a command or plain function foo, modify it so that

(throttle! 'foo 2.0)

throttles it to run no more than once every 2 seconds, and

(debounce! 'foo 0.5)

debounces it to run with a delay of 0.5 seconds.

We can also envision the safer, “non-destructive” versions Although our versions of throttle! (etc) won’t be destructive because of Emacs’ robust advice system. that return new functions, so we could do

(fset 'foo-throttled (timeout 'foo 2.0))
(fset 'foo-debounced (debounce 'foo 0.5))

This turns out to actually be trickier to do well (see below). For the in-place versions, we can rely on Emacs’ advice system to do most of the work for us.

Before we implement throttle! and debounce!, let’s look at the kinds of thing we’d like to do with them.

Example: throttle `smart-mode-line` updates

Updating the mode-line display is one of the exceptions I mentioned in the throttle description. Typically the mode-line is updated along with redisplay, and Emacs is quite fast at handling all display elements that Emacs has C-level support for (typically the %-prefixed format specifiers).

For efficiency, Emacs does not continuously recompute each window’s mode line and header line. It does so when circumstances appear to call for it—for instance, if you change the window configuration, switch buffers, narrow or widen the buffer, scroll, or modify the buffer.

– Mode Line Basics, elisp manual.

The problem is that it appears to compute every element on the mode-line under any of these circumstances.
You can evaluate arbitrary Lisp code during a mode-line update, and we sure do like to stuff the Emacs mode-line with fancy widgets in :eval blocks.

The combination of these two facts is a recipe for slowdown.

Case in point: the smart-mode-line package uses the function sml/generate-minor-modes to display active minor-modes in the mode-line with rich formatting. Generating this string A rather plain one too, despite support for rich text. takes up to 10% of Emacs’ time during routine text-editing.

As the Emacs profiler illustrates:

Samples   %    Function
---------------------------------------------
   1076  65% - redisplay_internal (C function)
    705  43%  + jit-lock-function
    404  22%  - eval
    220  13%   + and-let*
--> 166   9%   + sml/generate-minor-modes   <-- PRE-THROTTLE
      4   0%     sml/generate-modified-status
     52   3% - ...
     52   3%    Automatic GC

Recomputing the minor-modes string after every buffer insertion or window scroll is a waste. We’re actually fine so long as it’s updated soon after a minor-mode is enabled or disabled. So we throttle this function:

;; only allowed to run once every 4 seconds.
(throttle! 'sml/generate-minor-modes 4.0)

This frees up Emacs to do other things.

Samples    %   Function
----------------------------------------
   1482  66% - redisplay_internal (C function)
    733  33%  - eval
    681  30%   + and-let*
     17   0%     sml/generate-modified-status
-->   9   0%   + sml/generate-minor-modes   <-- POST-THROTTLE
      6   0%   + format
    700  31%  + jit-lock-function
    117   5% - ...
    117   5%    Automatic GC

Throttling lets us work around, in a coarse way, our lack of control over the mode-line update logic.

Throttle vs Debounce

In this example, using a debounce would have worked too… for the most part. There would be scenarios where it wouldn’t work well, though, such as turning on/off a minor mode and then immediately scrolling the window or typing. If we can tolerate slightly-out-of-date reports of Emacs’ state, throttling is generally the better option.

Example: debounce `org-agenda-follow-mode`

An example of an Org-mode feature that’s too eager for its own good: when following along entries with a preview in the Org Agenda, running down the list to the next item you’re interested in causes previews to be generated for each intermediate item (first video). Org does a fair bit of work – relative to the cursor movement speed - to set up the preview display, causing Emacs to hitch.

[Video: org-agenda without a debounce]

[Video: org-agenda with a debounce]

Let’s debounce this feature:

;; run after a resettable delay of 0.3 seconds.
(debounce! 'org-agenda-do-context-action 0.3)

Throwing in a debounce causes the intermediate cursor positions to be ignored (second video), making the process smoother and less visually noisy while keeping Emacs responsive.

Debouncing lets us work around, in a coarse way, user input that’s coming too fast to be smoothly acted on.

An inside-out implementation

To implement throttle! and debounce!, we can work our way outwards from the specification of what throttles and debounces should do.

But before we dig in…

This is primarily a fun elisp exercise.

If you are considering throttling elisp from outside of packages as an actual solution to addressing performance issues, you should have already tried the better options listed at the start of this write-up. We don’t play with mud balls without getting our hands dirty.

A throttled function will:

Run when first called,
and start keeping time.
If called again within the timeout period,
it refuses to run or returns immediately.

The core of this idea is captured in this thunk:

;; FUNC is the function to be throttled, called with arguments ARGS
;; TIMEOUT is the throttle duration

;; If the timer is running
(if (and throttle-timer (timerp throttle-timer))
    ;; do nothing, return nil
    nil
  ;; else run and start the timer
  (prog1 (apply func args)
    (setq throttle-timer
          (run-with-timer
           timeout nil
           (lambda ()
             ;; clear the timer
             (cancel-timer throttle-timer)
             (setq throttle-timer nil))))))

where throttle-timer and timeout need to be persistent between calls to this function.

The debounce version is built similarly. A debounced function will:

Not run immediately, and start a timer when first called.
If called again before the timer expires,
the timer is reset and starts over.
If the timer ends, the function finally runs.

The core of this process is captured in the following thunk:

;; FUNC is the function to be throttled, called with arguments ARGS
;; DELAY is the debounce period

;; If the timer is running
(if (timerp debounce-timer)
    ;; Do not run the function, reset the timer instead
    (timer-set-idle-time debounce-timer delay)
  ;; start the timer over
  (setq debounce-timer
        (run-with-idle-timer
         delay nil
         (lambda ()
           (setq debounce-timer nil)
           ;; Timer ran, finally run the function
           (apply func args)))))

where debounce-timer and delay need to be persistent between calls to this function. We use an idle-timer when debouncing, and a regular timer for the throttle. Using an idle timer here is technically incorrect, but the better choice since func is presumably an expensive call. The throttle timer only has to clear itself, which is cheap.

Next, we need to wrap these in a function that effectively acts as the throttled/debounced func.

If you are trying this in Emacs, be sure to turn on lexical-binding first.

(let ((throttle-timer)
      (timeout 1.0))
  (lambda (&rest args)
    "Run with a throttle."
    (if (and throttle-timer (timerp throttle-timer))
        ;; do nothing, return nil
        nil
      ;; else run and start the timer
      (prog1 (apply func args)
        (setq throttle-timer
              (run-with-timer
               timeout nil
               (lambda ()
                 ;; clear the timer
                 (cancel-timer throttle-timer)
                 (setq throttle-timer nil))))))))

throttle-timer and timeout are now defined in the enclosing environment. Provided lexical-binding is turned on, the inner lambda is a closure and these two objects will be persistent across calls to this closure.

func is still undefined/free. We place the above code into a “throttle-maker” function that “closes over” func:

(defun throttle (func &optional timeout)
  "Return a throttled version of FUNC.

It runs at most once every TIMEOUT seconds (default 1.0)."
  (let ((throttle-timer)
        (timeout (or timeout 1.0)))
    (lambda (&rest args)
      (if (and throttle-timer (timerp throttle-timer))
          nil
        (prog1 (apply func args)
          (setq throttle-timer
                (run-with-timer
                 timeout nil
                 (lambda ()
                   (cancel-timer throttle-timer)
                   (setq throttle-timer nil)))))))))

Note that this is the “non-destructive” version, it returns a new function instead of modifying func.

While we’re at it, we can return the previous result instead of nil during the throttle duration. This is unimportant for top-level interactive commands, but might at least help avoid type errors if this is a pure function, or if we’re monkey-patching something deep inside an elisp library.

We effectively memoize the result of calling func:

(defun throttle (func &optional timeout)
  "Return a throttled version of FUNC.

It runs at most once every TIMEOUT seconds (default 1.0)."
  (let ((throttle-timer)
        (timeout (or timeout 1.0))
        (result))
    (lambda (&rest args)
      (if (and throttle-timer (timerp throttle-timer))
          result
        (prog1 (setq result (apply func args))
          (setq throttle-timer
                (run-with-timer
                 timeout nil
                 (lambda ()
                   (cancel-timer throttle-timer)
                   (setq throttle-timer nil)))))))))

The debounce version is similar, but there’s nowhere to return the result to this time. func may be called from anywhere in the code but runs (eventually, via the timer) at top-level, so it doesn’t make sense to store its return value. We also couldn’t if we wanted to, since the return value doesn’t exist yet. To satisfy the calling code, we can prespecify a constant return value when constructing the function.

There’s a new wrinkle as well: the throttled func runs immediately or not at all. The debounced func, however, runs at a later time when the environment can be different – or invalid. So we need to capture as much of the current context as we can and restore it when func runs. Capturing the full context at call time is not possible (it could be anything) As far as I know. This might be possible in other Lisps with continuations, etc. , but we can set the active buffer at least.

Adding a default “immediate-return” value and the calling context, we get

(defun debounce (func &optional delay default)
  "Return a debounced version of FUNC.

It runs with a delay of DELAY seconds (default 0.5).

DEFAULT is the immediate return value of the function when
called."
  (let ((debounce-timer)
        (delay (or delay 0.5)))
    (lambda (&rest args)
      (if (timerp debounce-timer)
          (timer-set-idle-time debounce-timer delay)
        (prog1 default
          (setq debounce-timer
                (run-with-idle-timer
                 delay nil
                 (lambda (buf)
                   (setq debounce-timer nil)
                   (with-current-buffer buf ;set buffer when running
                     (apply func args)))
                 (current-buffer))))))))

We’re on the right track, but there are many issues with throttle and debounce above:

The generated closures don’t have interactive forms, so they cannot be run as commands. We can’t add interactive forms unconditionally, since we might want to throttle/debounce non-interactive functions too.
The generated closures don’t have any documentation. Assigning them to variables with fset will leave them (mostly) non-introspectable.
Most importantly, we wanted a throttle! and debounce! to corral existing errant elisp code, not generate new, quieter variants.

It turns out most of these issues can be resolved in one go, with some…

Advising around

We have on hand our throttled and debounced versions of func, albeit lacking some niceties. To replace func with these variants, we will depend on Emacs’ advice system. We’re specifically looking for a recipe that routes around func while letting us call it when necessary. The :around advice combinator fits the bill:

‘:around’

Call FUNCTION instead of the old function, but provide the old function as an extra argument to FUNCTION. This is the most flexible composition. For example, it lets you call the old function with different arguments, or many times, or within a let-binding, or you can sometimes delegate the work to the old function and sometimes override it completely. More specifically, the composition of the two functions behaves like: (lambda (&rest r) (apply FUNCTION OLDFUN r))

-Manual section on Advice Combinators (emphasis mine)

This time let’s work our way outside-in. The basic idea is:

Define a function that accepts as arguments the original function (oldfun) and its arguments.
Add this as :around advice to oldfun
Emacs runs this function instead of oldfun.

(defun newfun (oldfun &rest args)
  ;; do stuff
  (if predicate
      (apply oldfun args)
    ;; do something else
    (apply foo args)))

(advice-add 'oldfun :around 'newfun)

Our newfun is the generated closure (throttled or debounced) from the previous section. Here’s the same throttled closure as before, but following the above pattern instead:

(let ((throttle-timer)
      (timeout 1.0)
      (result))
  (lambda (oldfun &rest args)
    "Throttle this function."
    (if (and throttle-timer (timerp throttle-timer))
        result
      (prog1 (setq result (apply oldfun args))
        (setq throttle-timer
              (run-with-timer
               timeout nil
               (lambda ()
                 (cancel-timer throttle-timer)
                 (setq throttle-timer nil))))))))

This closure, intended as :around advice, accepts oldfun as an argument along with args.

This time there’s nothing to “close over” save the (customizable) timeout:

(defun throttle--advice (&optional timeout)
  (let ((throttle-timer nil)
        (timeout (or timeout 1.0))
        (result))
    (lambda (oldfun &rest args)
      "Throttle this function."
      (if (and throttle-timer (timerp throttle-timer))
          result
        (prog1 (setq result (apply oldfun args))
          (setq throttle-timer
                (run-with-timer
                 timeout nil
                 (lambda ()
                   (cancel-timer throttle-timer)
                   (setq throttle-timer nil)))))))))

throttle--advice is an “advice maker” that, when called with a timeout, returns an “advice function” that throttles the function it advises. Phew!

Of course, we need to actually add this advice:

(advice-add 'foo :around (throttle--advice 1.0))

This advice (closure) is nameless – we require a way to refer to it so that we can restore foo to its un-throttled, over-eager, Emacs-blocking state. We should also add this advice last, in that any other advice placed on foo should take precedence – the result of throttling the function would be unpredictable otherwise.

advice-add provides the machinery to do both these things:

(advice-add 'foo :around (throttle--advice 1.0)
            '((name . throttle)
              (depth . -99)))

Wrapping up this action in a function (finally) gives us the throttle! we are looking for:

(defun throttle! (func &optional timeout)
  (if (= timeout 0)
      (advice-remove 'func 'throttle)
    (advice-add func :around (throttle--advice timeout)
                '((name . throttle)
                  (depth . -99)))))

Instead of defining an unthrottle!, we make it so passing a timeout of 0 to throttle! restores the original function.

debounce! works the exact same way:

;; advice-maker
(defun debounce--advice (&optional delay default)
  (let ((debounce-timer nil)
        (delay (or delay 0.5)))
    (lambda (oldfun &rest args)
      "Debounce this function."
      (if (timerp debounce-timer)
          (timer-set-idle-time debounce-timer delay)
        (prog1 default
          (setq debounce-timer
                (run-with-idle-timer
                 delay nil
                 (lambda (buf)
                   (setq debounce-timer nil)
                   (with-current-buffer buf
                     (setq result (apply oldfun args))))
                 (current-buffer))))))))

;; advice-adder or remover
(defun debounce! (func &optional delay)
  (if (= delay 0)
      (advice-remove func 'debounce)
    (advice-add func :around (debounce--advice delay)
                '((name . debounce)
                  (depth . -98)))))

debounce--advice is an “advice maker” that, when called with a delay, returns an “advice function” that debounces the function it advises. debounce! can then add or remove this advice function to its argument.

Fortuitously, the other two problems – mirroring the interactive spec and adding function documentation – have worked themselves out.

Advice functions that don’t have an interactive spec will reuse that of the function they are advising.
The documentation of the original function is still available, with a note about the advice at the end. This note is the documentation of the advice function itself, i.e. “Throttle this function”.

Top-level vs nested calls: what can we timeout?

A short digression on Emacs’ command loop.

Throttling or debouncing code that runs at top-level, such as user commands or timers, is simple. Since there’s nothing for them to “return to”, introducing delays or (effectively) refusing to run code has no consequences beyond a delay in the corresponding library’s understanding of Emacs’ current state.

Things get tricky when we mess with “internal” code. Often it’s not user commands themselves that need debouncing, but something heavy lurking well inside a hook that runs as a result of the command. Our throttle example above (sml/generate-minor-modes) is a “hook function” triggered by mode-line updates. Our debounce example (org-agenda-do-context-action) is a function called from deep inside the org-agenda machinery when the cursor moves. Since

throttled functions can return nil or repeat a previous result, and
debounced functions always return nil immediately,

we require nil to be (at minimum) a valid return value wherever they are called, and (better) a value that stops further processing in the moment.

Picking a different return value

The same is true for any other non-nil value we choose to return (see implementation). Reusing return values from past calls to debounced functions is not possible without setting up global variables… which is a project for another time.

Having throttled and debounced a bunch of internal functions now, I can report that this is generally true of elisp code that needs a timeout, so long as a little care is exercised in picking them.

`throttle` and `debounce`: Non-destructive finagling

So why is:

(fset 'foo-debounced (debounce 'foo 0.5))

difficult to pull off well?

We have the basic skeleton in place from before:

(defun debounce (func &optional delay default)
  "Return a debounced version of FUNC.

It runs with a delay of DELAY seconds (default 0.5).

DEFAULT is the immediate return value of the function when
called."
  (let ((debounce-timer)
        (delay (or delay 0.5)))
    (lambda (&rest args)
      (if (timerp debounce-timer)
          (timer-set-idle-time debounce-timer delay)
        (prog1 default
          (setq debounce-timer
                (run-with-idle-timer
                 delay nil
                 (lambda (buf)
                   (setq debounce-timer nil)
                   (with-current-buffer buf ;set buffer when running
                     (apply func args)))
                 (current-buffer))))))))

The problems are:

Mirroring the interactive form of func.
Documenting the unnamed closure that debounce returns.

Mirroring `interactive` forms

We can lean on the advice system again for the former, but it’s ugly. We essentially write both versions of the function and pick one. Here’s throttle:

Mirroring interactive forms: throttle

(defun throttle (func &optional throttle default)
  "Return a throttled version of function FUNC.

THROTTLE defaults to 1 second."
  (let ((throttle-timer nil)
        (throttle (or throttle 1))
        (iform (interactive-form func))
        (result default))
    (if iform
        ;; INTERACTIVE version
        (lambda (&rest args)
          (interactive (advice-eval-interactive-spec
                     (cadr iform)))
          (if (and throttle-timer (timerp throttle-timer))
              result
            (setq result (apply func args))
            (setq throttle-timer
                  (run-with-timer
                   throttle nil
                   (lambda ()
                     (cancel-timer throttle-timer)
                     (setq throttle-timer nil))))))
      ;; NON-INTERACTIVE version
      (lambda (&rest args)
          (if (and throttle-timer (timerp throttle-timer))
              result
            (setq result (apply func args))
            (setq throttle-timer
                  (run-with-timer
                   throttle nil
                   (lambda ()
                     (cancel-timer throttle-timer)
                     (setq throttle-timer nil)))))))))

debounce is similar.

Inserting function documentation

Named symbols can have function documentation inserted directly into their function-documentation symbol property. Documenting unnamed closures programmatically is beyond me at this point – unless of course, we embrace the idea that we’re writing code that writes code…

It’s macrotime!

At this point it would actually be easier to get Emacs to write the code for us. This process is much more accessible (if not simpler) with a macro. We can fetch the relevant interactive form and documentation and shove them verbatim into the closure definition:

`(lambda (&rest args)
   ;; Add the documentation from FUNC with an extra note
  ,(concat
    (documentation func)
    (format "\n\nThis function is debounced -- it runs after a delay of %.3f seconds." delay))
  ;; Add the interactive form from FUNC
  ,(interactive-form func)
  ;; Rest of the debounce code from above
  )

While we’re at it, we can even skip the fset step and just define the new function func--debounced directly:

`(defun ,(intern (concat (symbol-name func) "--debounced")) (&rest args)
   ;; Add the documentation from FUNC with an extra note
  ,(concat
    (documentation func)
    (format "\n\nThis function is debounced -- it runs after a delay of %.3f seconds." delay))
  ;; Add the interactive form from FUNC
  ,(interactive-form func)
  ;; Rest of the debounce code from above
  )

Adding the lexical environment (for debounce-timer etc) and the rest of the macro definition, we get

If you are trying this in Emacs, be sure to turn on lexical-binding first.

(defmacro debounce (func &optional delay)
  "Return a debounced version of function FUNC.

DELAY defaults to 0.5 seconds."
  `(let ((debounce-timer nil)
         (delay (or ,delay 0.5)))
    (defun ,(intern (concat (symbol-name func) "--debounced")) (&rest args)
      ;; Add the documentation from FUNC with an extra note
      ,(concat
        (documentation func)
        (format "\n\nThis function is debounced -- it runs after a delay of %.3f seconds." delay))
      ;; Add the interactive form from FUNC
      ,(interactive-form func)
      (if (timerp debounce-timer)
          (timer-set-idle-time debounce-timer delay)
        (let ((buf (current-buffer)))
         (setq debounce-timer
          (run-with-idle-timer
           delay nil
           (lambda ()
             (cancel-timer debounce-timer)
             (setq debounce-timer nil)
             (with-current-buffer buf
              (apply #',func args))))))))))

This works as we intended, only the function name should no longer be quoted. The following code

(debounce next-line 0.4)

expands to a definition for next-line--debounced, replete with the correct documentation and interactive behavior Or we could stick to the anonymous closure version and run (fset 'next-line--debounced (debounce next-line)) .

For completeness, here is throttle as a macro:

(defmacro throttle (func &optional timeout default)
  "Return a throttled version of function FUNC.

TIMEOUT defaults to 1 second."
  `(let ((throttle-timer nil)
        (timeout (or ,timeout 1.0))
        (result ,default))
    (defun ,(intern (concat (symbol-name func) "--debounced")) (&rest args)
      ,(concat
        (documentation func)
        (format "\n\nThis function is throttled -- it runs at most once every %.3f seconds." timeout))
      ,(interactive-form func)
      (if (and throttle-timer (timerp throttle-timer))
          result
        (setq result (apply #',func args))
        (setq throttle-timer
              (run-with-timer
               timeout nil
               (lambda ()
                 (cancel-timer throttle-timer)
                 (setq throttle-timer nil))))))))

Questions

A few concerns bubbled up on this excursion, and I don’t know how to address them:

Debouncing a function a few hundred times is easy to do just by holding down a key. ~~This creates and destroys many timers – I don’t know if the ensuing garbage is worth worrying about, and whether it can be avoided.~~ This is now avoided in the code, see acknowledgments. Here is the atimer struct that Emacs uses:

   struct atimer
   {
     /* The type of this timer.  */
     enum atimer_type type;

     /* Time when this timer is ripe.  */
     struct timespec expiration;

     /* Interval of this timer.  */
     struct timespec interval;

     /* Function to call when timer is ripe.  Interrupt input is
        guaranteed to not be blocked when this function is called.  */
     atimer_callback fn;

     /* Additional user-specified data to pass to FN.  */
     void *client_data;

     /* Next in list of active or free atimers.  */
     struct atimer *next;
   };

This is… about 48 bytes of memory? ~~Debouncing a command 200 times – not an uncommon occurrence – then creates at least 10KB of garbage. How does this compare with the regular rate of garbage creation in Emacs?~~

How long does it take, realistically speaking, to create and clear timers? Some testing suggests that this is not an insignificant number when done in bulk, especially coupled with garbage collection.
Using a macro to implement the “non-destructive” versions of throttle! and debounce! does not pair well with our functions – the call signatures are different. Perhaps there is a way to do this with functions that isn’t janky?

The `timeout` library

This functionality is available as an elisp package: timeout. So far it’s exactly the code developed above, and just a couple of helper functions.

Writing debouncers and throttlers this way wasn’t a careful design process on my part. In fact, I have no idea how else I could write them in elisp. This suggests that I don’t understand the problem very well, or don’t understand elisp well, or (more likely) both. If you have corrections, suggestions or answers for me, please get in touch.

All right then – that’s it for me. Gotta debounce!

Glossary

Idle timer: An idle timer is some Lisp code scheduled to run when Emacs is idle for a specified period. What it means for Emacs to be idle is complicated: at minimum, this means no user input, no subprocess communication and no non-idle timers that need running. [2 uses]
Mode-line: This is the “status bar” at the bottom of Emacs windows. There are dozens of Emacs packages that prettify the mode-line, adding widgets and status reports. I’ve found many of these to be too aggressive in how often they update. [10 uses]
Push operations: Slow elisp code that runs as a direct result of user input. Example: an html preview of a markdown buffer that updates with each keystroke. Less exreme examples: sending data to an LSP server when some code is yanked into a buffer, or a header-line update because the cursor moved into a new function. So named because control of Emacs is “pushed” away as a result of the input action. [3 uses]
Pull operations: Slow elisp code that runs independent of user input, although it might be interrupted by it. So named because control of Emacs is “pulled” away by this code irrespective of user input. Examples: any idle timer not tied to user input, like RefTeX’s periodic scans of the LaTeX buffer. Of course, ultimately everything that happens in Emacs is user-driven and thus a “push operation”. This distinction is only one of proximity to the user. [3 uses]
Redisplay: This is the process of redrawing the screen, or more often parts of it, in Emacs. Considering Emacs’ terminal user interface and support for every platform under the sun, displaying is a complicated affair. [1 uses]

Acknowledgments

Joseph Turner points out that timerp handles the case when its argument is nil, so there is no need to check explicitly, as in (if (and debounce-timer (timerp debounce-timer))).

Ihor Radchenko points out that timer attributes (such as the remaining time) can be modified in place with the timer-set-* functions. This completely fixes the problem of debounce timers generating a lot of garbage.

Persistent prefix keymaps in Emacs

Sun, 05 Mar 2023 15:22:00 -0800

Or: Further Musings on the Tedium of Long Key-Chords. In the past I’ve covered various bespoke approaches to the problem of repeating long key sequences: Transient, Hydra, repeat-mode (and repeat-mode’s helpers) require progressively less forethought and custom elisp chops to set up. Today we continue our aggressive descent into laziness with the simplest way yet to use any Emacs key prefix as a springboard for one-key access to commands.

A quick glossary

keymap: A “keymap” is an Emacs data structure that maps a collection of keybindings (i.e. keyboard shortcuts) to commands.
key-chord: This is a sequence of keys, some or all of which can require modifier keys to be held down. Examples:
- C-x C-f (control + x, followed by control + f), which runs the find-file command
- C-c @ C-t (control + c, @, followed by control + t), which runs the command outline-hide-body.
Needless to say, these can get pretty tedious for repeated invocations, even if you avoid the modifiers by using Vim-style leader keys.
prefix-key: Any “incomplete” part of a key-chord that will cause Emacs to wait for further keyboard input. In the above examples, C-x, C-c and C-c @ are all prefix keys.

repeat-mode, Hydra, Hercules and Transient all enable variations of the following interaction:

You (the user) define a special keymap – a set of mappings from key bindings to commands,
where the bindings are short and mnemonic/ergonomic,
where the commands are related at some conceptual level in your mind,
which are displayed in some kind of menu or table,
and can be invoked in quick succession if required without exiting this menu. Additionally,
this menu (and associated editor state) can be enabled by using a dedicated keybinding, or
(repeat-mode only) by calling any one of these commands the long way.

The price you pay for this convenience is that you have to create this command group and specify the menu elements manually. This is not a tall order if you only need a few such menus, and the results can be pretty neat. In this situation these packages solve the tedium issue almost incidentally, since easing repetition is not even their primary purpose.

Figure 1: Pictured: A Transient for assorted tasks. Not pictured: Its long and messy definition.

As I’ve written at length before, Emacs’ built-in repeat-mode straddles the divide between requiring a bespoke menu with associated elisp configuration and a minimally specified approach to repeating commands.

But Emacs is full of prefix maps, and we still don’t have the ability to enter a persistent state – on the fly and without premeditation – where an arbitrary keymap can be “activated” until we are done running or repeating commands in this map.

As it turns out, a 90% solution for this is actually really straightforward, no repeat-mode needed. With some inspiration from Embark:

(defun repeated-prefix-help-command ()
  (interactive)
  (when-let* ((keys (this-command-keys-vector))
              (prefix (seq-take keys (1- (length keys))))
              (orig-keymap (key-binding prefix 'accept-default))
              (keymap (copy-keymap orig-keymap))
              (exit-func (set-transient-map keymap t #'which-key-abort)))
    (define-key keymap [remap keyboard-quit]
      (lambda () (interactive) (funcall exit-func)))
    (which-key--create-buffer-and-show nil keymap)))

(setq prefix-help-command #'repeated-prefix-help-command)

That’s all of it. Here’s how it works:

When you’ve typed any prefix key (say C-c @) and Emacs is waiting for further input, press C-h.
Emacs now remembers whatever you’ve already typed, activates a “repeat state” or repeat-mode, as it were. This is basically modal editing with bespoke modes. and a which-key prompt/menu with available keybindings.
You can now continue to call available commands in sequence without having to re-type the annoying prefix key.
This state persists until you exit it with C-g (bound to keyboard-quit).

Note:

which-key is only a visual aid here – this works if you replace it with a different prompter or if you remove it from the code entirely.

Here is a demo of creating a “repeat state” on the fly, in this case for the ever annoying outline-minor-mode commands on the C-c @ prefix. (The keypresses are shown at the top of the window.)

[Repeated-prefix demo]

In principle, repeated-prefix-help-command functions similar to repeat-mode, but with one difference. The latter requires that you specify beforehand which prefix keymaps should automatically enter the “repeat state”, and define maps that group together related commands if they don’t exist already. The above method lacks this automaticity, but is more flexible: you can enter this state at any time (and for any keymap) with an additional keypress (here C-h).

repeated-prefix-help-command also has an advantage over repeat-mode: pressing keys that are not bound in the “repeat state” will cause repeat-mode to end, and you will have to start over with the full, long key sequence to enter it again. Although this can be remedied with some monkey patching. See repeat-help. The keymap we activate above stays active until we call keyboard-quit, so we can freely mix regular Emacs editing commands and the ones we have temporary one-key access to.

We could, of course, use both approaches together. We are approaching peak laziness, but I don’t think we’re there yet!

Notmuch Ado About Nothing

Wed, 27 Jul 2022 18:32:00 +0530

Addressing an innocuous question about the Notmuch email client’s default behavior took me surprisingly deep into the bowels of the package code. When the normal customization methods didn’t help, I realized it might be a good opportunity to live-code a solution.

The hope was that it might outline a recipe for reaching into the elisp guts of any library and getting Emacs to do what you want – with no specific prior knowledge. The reality is thirty minutes of fairly myopic yakshaving:

[Video]

It Bears Repeating: Emacs 28 & Repeat Mode

Tue, 05 Jul 2022 23:17:00 +0530

Are you tired of pressing C-x o repeatedly to switch to the window you want in Emacs? Or M-g n and M-g p to cycle through compile errors or grep matches? How about navigating outline headings with (yuck) C-c @ C-n and C-c @ C-p?

The correct answer to the latter is that no one traverses headings this way, because these keybindings are atrocious. Even the shorter ones start to grate when you need to use them repeatedly in an editing session.

Depending on their levels of comfort with Emacs, users typically deal with them in one of three ways:

They aren’t aware of or don’t use these commands, or use the menu to access them.
They rebind the ones they need elsewhere, to an easier to press but equally idiosyncratic location. After a few such short non-prefixed keybindings they run out of room on their keyboards.
They use one of the many, many available helpers written with the Hydra or Transient packages for these.¹

But there’s a fourth option. Emacs 28 bundles a simple and hassle-free way to take the tedium out of these keybindings: Repeat Mode.

Repeat Mode lets you call multiple commands in a keymap without repeating the prefix each time. So you can press

C-x o, o, o, … to switch windows repeatedly. O will cycle backwards.
C-x u, u, u, … to undo repeatedly,
C-x @ C-n, n, p, f, b,… to traverse headings,
M-g n, n, p, n,… to navigate errors or grep matches, and so on.

With repeat-mode active, calling the prefix (M-g) the first time “activates” the keymap, after which only the “base” key for a command (n or p)is needed.

Naming things is hard

In this write-up I’ll call all but the final part of a keybinding the “prefix”, and the final key or chord the “base” key.

Example: org-next-link, bound to C-c C-x C-n:

The prefix is C-c C-x.
The base key is C-n.

Repeating a single command

If you want to call a single command repeatedly, repeat-mode is not required. You can just call M-x repeat, bound to C-x z by default. This has been part of Emacs for ages. You can repeat invocations of the repeat command itself with just z, so it’s C-x z z z... to repeat the last command multiple times.

In comparison to M-x repeat, repeat-mode shines when there’s a whole keymap of related commands with keys (like n, p, f, b, u for outline navigation) under the same prefix (like C-c @ for outline-minor-mode). In this video I switch windows, jump through Occur (grep) matches, navigate git-diff hunks With diff-hl-mode, which supports repeating commands out of the box. and call undo repeatedly with single key presses. The buffer on the right lists the keystrokes. Commands with the same prefix or repeated commands are single key presses:

[VIDEO]

Play by play

After the first invocation of other-window (C-x o), I switch windows with o (and O).
Next I find occur -ences of the phrase “repeat-mode” in the buffer. The next-error (M-g n) and previous-error (M-g p) commands jump through the matches. I only need to type the prefix (M-g) once.
I call diff-hl-previous-hunk from the end of the buffer to jump to modified hunks in this version-controlled document. This is provided by the diff-hl package. Again, I only type in the prefix (C-x v in my configuration) once.
I mark a modified hunk with SPC – corresponding to the full version C-x v SPC. Then I call undo a few times. As a bonus, undo in Emacs is limited to the active region.
After the first invocation of the C-x prefix, undo is just u. This is simpler than holding down Control to press C-/, the other undo binding, a bunch of times.

Repeat Mode comes with built-in support for a bunch of keymaps. There’s no learning curve, M-x repeat-mode and you’re set. You’ll wonder how you lived without it.

What’s in a keymap

Before we dive into Repeat Mode proper, let’s address the issue of creating an easily repeatable command using Emacs’ base API.

A “keymap” is a data structure that maps a collection of keybindings (i.e. keyboard shortcuts) to commands. Let’s call each element of this map a “binding”. Any number of keymaps can be “active” at a time in Emacs, meaning that typing a keybinding will run some command that it’s mapped to in these keymaps. Which command runs is a question of which keymap is looked up first.

For our purposes, a “transient keymap” is one that

takes priority over all other keymaps, and
disappears after a keypress unless unless you explicitly ask it to stick around.

If we want to make a key run a command no matter what other keymaps are active, we can use a transient keymap. If we want this keymap to stick around until some arbitrary condition is met, we can do that too. Putting these ideas together lets us add a “repeat” feature to any command.

For example, I cycle through popup buffers in Emacs with the key C-M-`, or Control, Alt and the grave key chorded together. This calls the popper-cycle command. Needless to say, this isn’t very conducive to repeated invocations. So I activate a transient-keymap after each call to popper-cycle:

(advice-add 'popper-cycle :after
            (defun my/popper-cycle-repeated (&rest _)
              "Continue to cycle popups with the grave key."
              (set-transient-map
               (let ((map (make-sparse-keymap)))
                 (define-key map (kbd "`") #'popper-cycle)
                 map))))

This keymap binds popper-cycle to the grave key, and it stays active for exactly one keypress. Typing the grave key thus calls popper-cycle again, or I can break this chain by doing anything else. (Note: This is a terrible way to do it!²)

The logic used by Repeat Mode is quite different, but the effect is similar. In its simplest form, binding a shared set of commands to a transient map is how you could add a “repeat” functionality to the set.

Adding `repeat-mode` support to keymaps

Repeat Mode supports a few keymaps out of the box, including all the ones in my demo above.

To add Repeat Mode support to commands in a keymap, you add a symbol property to each command. Here’s support for the completely unpressable smerge-mode commands: See below for a demo.

(map-keymap
 (lambda (_key cmd)
   (when (symbolp cmd)
     (put cmd 'repeat-map 'smerge-basic-map)))
 smerge-basic-map)

This is simple enough that we can shove it into a function that repeat-izes keymaps:

(defun repeatize (keymap)
  "Add `repeat-mode' support to a KEYMAP."
  (map-keymap
   (lambda (_key cmd)
     (when (symbolp cmd)
       (put cmd 'repeat-map keymap)))
   (symbol-value keymap)))

The “repeat” state is shared between commands that are (i) bound in a keymap, and (ii) have the keymap as their repeat-map symbol property. But what if the commands you want to repeat aren’t defined on top of a prefix, unlike all the above examples? Or if the commands we want to group aren’t part of a single keymap to begin with? Then this is a two step process:

Bind your commands of interest in some keymap, to short keys if necessary.
Attach the keymap name as a symbol property to all of them.

For instance, suppose you’d like to be able to Isearch repeatedly with just s and r instead of hammering C-s over and over. To do this you can bind them to short keys in a keymap, and attach the keymap name to the commands’ repeat-map symbol properties:

(defvar isearch-repeat-map
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "s") #'isearch-repeat-forward)
    (define-key map (kbd "r") #'isearch-repeat-backward)
    map))

(dolist (cmd '(isearch-repeat-forward isearch-repeat-backward))
  (put cmd 'repeat-map 'isearch-repeat-map))

Note: You’re not going to have trouble typing “s” or “r” as part of the search string, even after you’ve begun the search with C-s – it’s only the repeated invocations (isearch-repeat-forward) that are shortened!

This is a somewhat low-level (though simple) operation and the recipe is fairly constant. So we could package it in a macro for ease of use… but we don’t have to. There are already multiple packages that let you specify commands to be repeated along with their short keys. Here are a few:

define-repeat-map by Case Duckworth
repeaters by mmarshall540
Hercules by jjzmajic, an external package that bypasses the whole repeat-mode system and lets you define repeat functionality for any keymap.

Making repeat-maps: Emacs 29 update

Emacs 29 introduces defvar-keymap, making it easier to define keymaps with the repeat-map property attached:

(defvar-keymap hl-todo-repeat-map
    :repeat t
    "n" #'hl-todo-next
    "p" #'hl-todo-previous
    "o" #'hl-todo-occur)

Or, for finer control over when the repeat-map is (de)activated,

(defvar-keymap hl-todo-repeat-map
    :repeat (:enter (hl-todo-insert) :exit (hl-todo-occur))
    "n" #'hl-todo-next
    "p" #'hl-todo-previous
    "o" #'hl-todo-occur)

which specifies that using hl-=todo-insert should activate the repeat-map and hl-todo-occur should deactivate it.

Note that turning an existing keymap into a repeat-map or adding this behavior to individual commands still requires one of the above helpers, like repeatize.

With any of these packages you could develop the above idea into a complete modal editing environment – like God Mode, but with custom modes for specialized editing tasks. Even at a more basic level, you can go wild here, placing all commands into repeat maps: Why delete words with M-d or M-DEL five times when you can just do M-d d d d d? Why cycle through the kill-ring with M-y when you can just yank and cycle with C-y y y y...?

I’m not sure about taking it that far. For one, it’s simpler to use digit arguments: M-5 M-d is shorter and possibly faster to type. Second, many commands that involve more than three levels of “cycling” are better served by a menu with choices, i.e. a completing-read interface or an Avy selection. I’ve found that the returns diminish and the common issues with modality start to surface as the repeat maps become more expansive.

Repeat maps appear to be best suited for families of related commands that are usually invoked in succession and are cumbersome to invoke. Pretty much exactly what folks use Hydras or (more lately) Transients for, which brings us to…

Repeat Mode vs Hydra, Transient and Hercules

Repeat Mode has a few advantages when compared to Hydras/Transients³ for repeating commands:

There’s no special definition or code to write, maintain or copy: it just works.
There’s only one set of keys defined for a command: You can use the same full keybinding with or without Repeat Mode active.
You can rebind both the prefix and the base keys without losing the repeat behavior.
Repeat Mode has support for many prefix maps out of the box, and adding support for new maps is easy, see below.
It’s built into Emacs.

The Hercules package shares many of these advantages, since it too uses existing keymaps as the basis for a repeat interface. However, Repeat Mode is more minimal in its configuration and presentation, does not depend on Which Key, and does not offer a fancy key hinting system out of the box.

With all of the above alternatives, you still need to invoke the mode somehow. With repeat-mode this requires pressing the unwieldy prefix key once: C-c @ for outline-minor-mode, C-c ^ for smerge-mode, and so on. This is cause enough for rebinding them somewhere convenient, perhaps to the user-reserved C-c o (for outline) and C-c m (for merge). Or under a leader key if you use evil-mode. Note that you have to do this with a Hydra/Transient as well.

There are disadvantages to Repeat Mode too. First, Hydras/Transients are incredibly versatile, and repeating commands isn’t even in the top three problems they solve. Using them for repeating commands is like using an elephant gun to hunt a mouse.

They can be full fledged suites combining settings and bespoke commands that don’t have much in common. For example, here’s a Transient I use to toggle minor-modes in Emacs:

And another to resize or clip a video with ffmpeg:

Basically, Transients have state.

In contrast, Repeat Mode only aims to save your fingers some work. You can gather disparate commands under the same umbrella map for use with repeat mode, but it gets out of hand rather quickly. So we will limit ourselves to the intended patterns of Repeat Mode usage in this write-up.

Second, Hydras can stay alive while you press keys not in the keymap. This means you can (usually) move the cursor around to where you next want to call a Hydra command. You can add this behavior to Repeat Mode with some creative use of composed keymaps, but by default the prefix map does not stay active if you call a non-keymap command. Again, I’m going to hew to the default scope of Repeat Mode here.

Finally, repeat-mode prompts you with available keys in the echo area, but not what commands they’re bound to:

This is generally sufficient, but I could use a Which Key style menu for rarely used keymaps with lots of keys (like smerge-mode). As it turns out, this is quite straightforward to add.

Adding a Hydra-like prompt to Repeat Mode

If you prefer an explicit and persistent menu of available keys/commands – like a Hydra or Transient menu – you can produce a menu using Which Key or an Embark prompter when calling a relevant command:

Doing this is quite simple: we disable the built-in hint display and advise the function that sets the transient keymap after a “repeatable key” is pressed. Here’s the Which Key version: This code creates a closure, so remember to enable lexical-binding where it’s placed.

;; Disable the built-in repeat-mode hinting
(custom-set-variables repeat-echo-function #'ignore)

;; Spawn or hide a which-key popup
(advice-add 'repeat-post-hook :after
            (defun repeat-help--which-key-popup ()
              (if-let ((cmd (or this-command real-this-command))
                       (keymap (or repeat-map
                                   (repeat--command-property 'repeat-map))))
                (run-at-time
                 0 nil
                 (lambda ()
                   (which-key--create-buffer-and-show
                    nil (symbol-value keymap))))
                (which-key--hide-popup))))

Specifically, we schedule the which-key popup on the main event loop. (Emacs: Making things happen when other things happen™.)

In action, applied to the smerge-mode keymap when performing a Git merge:

[VIDEO]

Play by play

Open a file with merge conflicts.
Call smerge-previous (C-c m p in my configuration) to go to the beginning of a hunk. This “activates” the keymap and the Which Key pop up.
Jump through conflict regions with n and p.
Resolve conflicts by picking the upper (u) or lower (l) regions.
Save the buffer. This quits the repeat map and the popup.

The code to produce a suitable Embark indicator involves a little more book-keeping, but the idea is the same: Schedule a keymap display when a repeatable command is invoked and remove it once it’s not relevant any more.

;; Disable the built-in repeat-mode hinting
(custom-set-variables repeat-echo-function #'ignore)

(defun repeat-help--embark-indicate ()
  (if-let ((cmd (or this-command real-this-command))
           (keymap (or repeat-map
                       (repeat--command-property 'repeat-map))))
      (run-at-time
       0 nil
       (lambda ()
         (let* ((bufname "*Repeat Commands*")
                (embark-verbose-indicator-buffer-sections
                 '(bindings))
                (embark--verbose-indicator-buffer bufname)
                (embark-verbose-indicator-display-action
                 '(display-buffer-at-bottom
                   (window-height . fit-window-to-buffer)
                   (window-parameters . ((no-other-window . t)
                                         (mode-line-format))))))
           (funcall
            (embark-verbose-indicator)
            (symbol-value keymap))
           (setq other-window-scroll-buffer (get-buffer bufname)))))
    (when-let ((win
                (get-buffer-window
                 "*Repeat Commands*" 'visible)))
      (kill-buffer (window-buffer win))
      (delete-window win))))

(advice-add 'repeat-post-hook :after #'repeat-help--embark-indicate)

Here’s what it produces:

If these are too busy, you might prefer to toggle the prompter on demand. There are only a few keymaps I need hints to use, so I bind the popup key to C-h. Here I jump between modified hunks in a version controlled document and examine and stage them for committing using the Embark popup/indicator as a guide. Keep an eye on the key/command description at the top of the window:

[VIDEO]

Play by play

Call diff-hl-next-hunk, which I’ve bound to C-x v n . This is the only time I type the prefix C-x v.
Jump between modified hunks in the document with n and p, which would be C-x v n and C-x v p without repeat-mode.
Bring up the Embark key description popup with C-h. I toggle it a couple of times.
Call diff-hl-show-hunk with *, and stage the previous hunk with S.
Perform an action that ends the repeat-mode chain, in this case by yanking some text into the buffer.

The key description popup does not need to be cancelled: it automatically disappears when you run any command that’s not in the keymap, such as inserting text. (This is regular behavior for transient keymaps in Emacs.)

Both indicators (Embark and Which Key) and both kinds of behavior (auto-popup or toggle on demand) are available in Repeat Help, a package I wrote to get a simplified Hydra-like prompt for repeat maps. The prompt interface is basic but generic, so any function that can list a keymap’s entries can be plugged in.

Command smells

To find other commands or keymaps that could use repeat-izing, we can look for a code smell:

Any command that has “next”, “forward”, “previous” or “backward” in the name is fair game. For reasons alluded to above, this excludes common commands like next-line or forward-word: jumping across text is better solved by Isearch or Avy. These do other useful things besides, like pushing the mark and letting you act on the region you jumped across. But something contextual like org-next-link is fair game:
```
(defvar org-link-repeat-map
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "n") 'org-next-link)
    (define-key map (kbd "p") 'org-previous-link)
    map))

(dolist (cmd '(org-next-link org-previous-link))
  (put cmd 'repeat-map 'org-link-repeat-map))
```
It’s surprising that link navigation isn’t already part of Org Speed Keys, which is included in Org Mode.
Any predictable sequence of actions that forms a “task” is a good candidate. Smerge Mode is a good example. In its most basic usage you jump to each merge conflict, pick one of three choices and repeat. Critically, it has to be a sequence of actions carried out in (or across) an editable buffer. In read-only-mode buffers like help windows or mail clients, most relevant commands are already bound to single key presses at the top level.

Any command that tweaks an analog setting will need to be repeated. Setting the text scale (C-x C-= ) or window width (C-x {), for instance. Fortunately these are already handled by Repeat Mode.

But other built-in libraries like Windmove, for which Hydras are usually written, can be repeat-ized instead:

(defvar windmove-repeat-map
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "<left>") 'windmove-left)
    (define-key map (kbd "S-<left>") 'windmove-swap-states-left)
    (define-key map (kbd "<right>") 'windmove-right)
    (define-key map (kbd "S-<right>") 'windmove-swap-states-right)
    (define-key map (kbd "<up>") 'windmove-up)
    (define-key map (kbd "S-<up>") 'windmove-swap-states-up)
    (define-key map (kbd "<down>") 'windmove-down)
    (define-key map (kbd "S-<down>") 'windmove-swap-states-down)
    map))

(map-keymap
 (lambda (_key cmd)
   (when (symbolp cmd)
     (put cmd 'repeat-map 'windmove-repeat-map)))
 windmove-repeat-map)

Now you can continue to move across or rearrange windows with the arrow keys after calling any Windmove command.

…but I repeat myself

Keybindings are typically where modal editing paradigms have an advantage. Indeed, most repeated invocations in Vim – like searching forward with n , f or ;– are single key presses. But here too I had to rebind keys to switch windows (C-w j etc) to use it comfortably over a long editing session.

The question remained: Why do I need to press so many keys to do the same few things? After failing to gel with the Hydra paradigm, I had been manually setting up transient keymaps (with set-transient-map) to speed up consecutive calls for a bunch of commands. Placing them behind a uniform interface is a welcome addition. Repeat Mode is a small feature that solves a small problem, but with a big cumulative impact on my experience of using Emacs.

Technically there’s one more approach: Use bespoke solutions like ace-window to switch windows. But in terms of a general approach it’s just these three. ↩︎
Setting a new transient keymap on each call is actually a wasteful way of producing this effect! Instead, you can set a transient keymap just once but instruct it to stay active as long as the only key pressed is grave. ↩︎
It makes sense that the Transient package is called that, since Transients (the menus Magit uses) are “just” souped-up transient maps, the way a Komodo dragon is just a lizard. But it causes no end of confusion when talking about them. Here I refer to a regular Emacs transient map in lowercase and the Magit-style popup-menu variety in uppercase. ↩︎

Scaling Latex previews in Emacs

Fri, 25 Feb 2022 02:39:00 +0530

This is a post in my Latex editing series, an awkward solution to a tiny problem.

The Problem

A common issue with Latex previews in Emacs: The preview images don’t scale when you rescale text in latex-mode or org-mode:

[VIDEO]

Direct link to video

This makes it cumbersome to work with Latex math in Emacs when dealing with different sized monitors or when presenting from Emacs with Org Tree Slide, for example.

A good solution would be to re-render these fragment images at a higher resolution when applying text scaling. The current version of org-mode (9.52 as of this writing) is very slow to render Latex previews and locks up Emacs for a while, this is not a workable solution.

There are a couple of ways this could be improved: For Org, call an async process to render Latex fragments, or better yet, reuse AucTeX’s preview-latex library for fast, near instant updates. Instant Org previews with preview-latex are now feasible, see the next post in this series. For Latex, adjust the preview-scale variable and regenerate the fragments at each new text scale. These are projects for another day, or for someone more proficient.

The Hack

After asking around for an alternative, I settled on writing a big ol’ hack: Just zoom in on the preview images when increasing the text scale:

[VIDEO]

Direct link to video

This is fast and cheap, but the downside is that the images get blurry:

Using SVG fragments can mitigate this problem, at least for Org previews:

(setq org-preview-latex-default-process 'dvisvgm) ;No blur when scaling

The Recipe

Preview images are handled using overlays, so the image scaling is done by scanning for and adjusting appropriate overlay properties when changing the text scale:

(defun my/text-scale-adjust-latex-previews ()
  "Adjust the size of latex preview fragments when changing the
buffer's text scale."
  (pcase major-mode
    ('latex-mode
     (dolist (ov (overlays-in (point-min) (point-max)))
       (if (eq (overlay-get ov 'category)
               'preview-overlay)
           (my/text-scale--resize-fragment ov))))
    ('org-mode
     (dolist (ov (overlays-in (point-min) (point-max)))
       (if (eq (overlay-get ov 'org-overlay-type)
               'org-latex-overlay)
           (my/text-scale--resize-fragment ov))))))

(defun my/text-scale--resize-fragment (ov)
  (overlay-put
   ov 'display
   (cons 'image
         (plist-put
          (cdr (overlay-get ov 'display))
          :scale (+ 1.0 (* 0.25 text-scale-mode-amount))))))

(add-hook 'text-scale-mode-hook #'my/text-scale-adjust-latex-previews)

Dired history in Emacs

Thu, 24 Feb 2022 01:33:00 -0800

Emacs is reasonably consistent across its major-modes in its common usage patterns and keybindings. For example, C-M-a and C-M-e consistently move you to the beginnings and ends of functions in various language modes, and C-c C-z moves the focus to REPLs and back. In read-only modes n and p move the cursor up and down, and w generally copies the path, address or URL of the buffer to the kill ring.

One of these consistent (but less well known) keybindings is for going back and forward across nodes in a tree, arranged into a list: l and r traverse your history and “forward” history of visited help pages in help-mode, info nodes in Info-mode Info mode takes this further. L gives you an index of your visited nodes, which is itself placed into history! , web pages in eww, locations in pdf-tools and probably others. I think of this as moving [l]eft or [r]ight across a traversal path.

But there are some omissions. I frequently find myself using l and r in dired buffers to navigate my history of visited dired buffers, where it annoyingly does nothing. I assumed this feature would be part of one of the many, many Emacs packages that extend dired, but while there are big total makeovers (like ranger.el) for dired that include it, there wasn’t anything simple.

So I wrote a helper: dired-hist. It’s very basic (< 50 LOC) and will remain so, although I might add some customization options in time.

An Elisp Editing Tip

Sun, 24 Oct 2021 14:00:00 +0530

One of the first things new Emacs users learn is the eval-last-sexp (C-x C-e) command and that Emacs can interpret elisp anywhere it appears. Here’s a quick tip about using this command when writing elisp that you may not have discovered.

If you call it with a prefix (C-u) argument, it prints (or attempts to print) the result in place in the buffer. Better yet, call it with an argument of 0 (C-0 C-x C-e) to avoid truncating longer results.

Variables evaluate to their values, so here it prints the current values of these variables:

[VIDEO]

This is handy when writing elisp, for example if you want to tweak the current value of a variable:

[VIDEO]

I replace eval-last-sexp everywhere with pp-eval-last-sexp, which produces a cleaner result:

(global-set-key [remap eval-last-sexp] 'pp-eval-last-sexp)

[VIDEO]

That is all.

Declickbait Elfeed

Mon, 11 Oct 2021 05:27:00 -0700

Using an RSS reader instead of visiting Youtube or other social media has many advantages, including that you have to deal with much less energy-sapping, will-eroding clickbait. Unfortunately feed entries can still have clickbaity titles that can DESTROY your patience! So I wrote a dumb-as-rocks declickbaiter for Elfeed. You WON’T BELIEVE the results!

The Before (The After will SHOCK you!):

The After:

The Code:

(add-hook 'elfeed-new-entry-hook #'elfeed-declickbait-entry)

(defun elfeed-declickbait-entry (entry)
  (let ((title (elfeed-entry-title entry)))
    (setf (elfeed-meta entry :title)
          (elfeed-title-transform title))))

(defun elfeed-title-transform (title)
  "Declickbait string TITLE."
  (let* ((trim "\\(?:\\(?:\\.\\.\\.\\|[!?]\\)+\\)")
         (arr (split-string title nil t trim))
         (s-table (copy-syntax-table)))
    (modify-syntax-entry ?\' "w" s-table)
    (with-syntax-table s-table
      (mapconcat (lambda (word)
                   (cond
                    ((member word '("AND" "OR" "IF" "ON" "IT" "TO"
                                    "A" "OF" "VS" "IN" "FOR" "WAS"
                                    "IS" "BE"))
                     (downcase word))
                    ((member word '("WE" "DAY" "HOW" "WHY" "NOW" "OLD"
                                    "NEW" "MY" "TOO" "GOT" "GET" "THE"
                                    "ONE" "DO" "YOU"))
                     (capitalize word))
                    ((> (length word) 3) (capitalize word))
                    (t word)))
                 arr " "))))

elfeed-title-transform can be replaced with something much better, like a grammar aware title formatter (AI or otherwise), or with information extracted from the content or video description of the entry. But I’ll settle for this pareto solution for what was half an hour of live coding in the dark:

Okay, the above screenshots were chosen as a joke. Here’s a more representative version of the declickbait effect:

Before:

After:

Jumping directories in eshell

Fri, 08 Oct 2021 17:33:00 -0700

A quick note that I thought might be interesting to document.

As befits a shell written in elisp, eshell is extremely easy to modify to your use. There are a few packages floating around that add autojump/fasd/z type functionality to eshell. These let you jump quickly to any previously visited directory. As it turns out it’s very easy to implement a more powerful version of this by piggybacking off of consult-dir.

Here’s a z command that lets you jump to any previously visited directory, as well as any bookmark, project or emacs-wide recent directory:

Your browser does not support the video tag.

It’s a single function:

(defun eshell/z (&optional regexp)
    "Navigate to a previously visited directory in eshell, or to
any directory proferred by `consult-dir'."
    (let ((eshell-dirs (delete-dups
                        (mapcar 'abbreviate-file-name
                                (ring-elements eshell-last-dir-ring)))))
      (cond
       ((and (not regexp) (featurep 'consult-dir))
        (let* ((consult-dir--source-eshell `(:name "Eshell"
                                             :narrow ?e
                                             :category file
                                             :face consult-file
                                             :items ,eshell-dirs))
               (consult-dir-sources (cons consult-dir--source-eshell
                                          consult-dir-sources)))
          (eshell/cd (substring-no-properties
                      (consult-dir--pick "Switch directory: ")))))
       (t (eshell/cd (if regexp (eshell-find-previous-directory regexp)
                            (completing-read "cd: " eshell-dirs)))))))

Plus consult-dir, of course.

Note that if you provide input to the command instead, e.g. z doc, it will jump directly to the last matching directory you visited in eshell, i.e. ~/Documents/ or something like it.

The idea is simple, and it should be trivial to write something similar if you’re a Helm or Ivy user, as well as to write one for the comint mode M-x shell.

Lazy Elfeed

Fri, 22 May 2020 03:20:00 +0530

Elfeed, the feed reader for Emacs, is built on several clever ideas. The basic mode of interaction in Elfeed is through search, specifying what kinds of feeds you want to peruse at the moment. This removes the distinction between an inbox and a search result, which works surprisingly well with the expressive search syntax. The second is integration: search results can be stored as regular bookmarks, and jumping to the bookmark from anywhere in Emacs will run the corresponding query and present you with fresh results. The third is organizing by tags instead of folders. Web services like Gmail use some of these concepts (and probably pioneered them too), but the difference between web-based readers and Emacs in speed, customizability, general hackability and use is night and day.

Elfeed’s default interface has all the right pieces, but I found it needed just a little tweaking to fit what I expect from a feed reader.

Display the feed list and current entry in a split pane setup ¹:

Elfeed has two kinds of views: The search view which shows feed entries matching a search query, and the show view to read a specific entry. By default only one of these is active at a time, but a more useful split-pane setup is a few tweaks away:

Your browser does not support the video tag.

Stay in the search view and preview entries.

There are only two pieces to this. The first is to specify the function we want Elfeed to use to display the buffer with the current entry. In this case write our own elfeed-display-buffer to set the height.

(setq elfeed-show-entry-switch #'elfeed-display-buffer)

(defun elfeed-display-buffer (buf &optional act)
  (pop-to-buffer buf)
  (set-window-text-height (get-buffer-window) (round (* 0.7 (frame-height)))))

A different but less self-contained way would be to set it to use the built in pop-to-buffer but add an entry to display-buffer-alist as an instruction on what to do with elfeed entry buffers.

The second is to set up a keybinding to advance to the next or previous feed in the search window, with a little elbow grease. ²

;; -*- lexical-binding: t -*-
  (defun elfeed-search-show-entry-pre (&optional lines)
  "Returns a function to scroll forward or back in the Elfeed
  search results, displaying entries without switching to them."
      (lambda (times)
        (interactive "p")
        (forward-line (* times (or lines 0)))
        (recenter)
        (call-interactively #'elfeed-search-show-entry)
        (select-window (previous-window))
        (unless elfeed-search-remain-on-entry (forward-line -1))))

  (define-key elfeed-search-mode-map (kbd "n") (elfeed-search-show-entry-pre +1))
  (define-key elfeed-search-mode-map (kbd "p") (elfeed-search-show-entry-pre -1))
  (define-key elfeed-search-mode-map (kbd "M-RET") (elfeed-search-show-entry-pre))

Navigate the entire database with the space bar

Alternatively, you might prefer to stay in the “show” window and just go through each entry by content instead of header. You can use the space bar to scroll the view or move to the next entry as appropriate.

Your browser does not support the video tag.

Go forward (scroll or next entry) with SPC, back with S-SPC

Google Reader had one button navigation, and it is a level of laziness I have aspired to since.

(defun elfeed-scroll-up-command (&optional arg)
  "Scroll up or go to next feed item in Elfeed"
  (interactive "^P")
  (let ((scroll-error-top-bottom nil))
    (condition-case-unless-debug nil
        (scroll-up-command arg)
      (error (elfeed-show-next)))))

(defun elfeed-scroll-down-command (&optional arg)
  "Scroll up or go to next feed item in Elfeed"
  (interactive "^P")
  (let ((scroll-error-top-bottom nil))
    (condition-case-unless-debug nil
        (scroll-down-command arg)
      (error (elfeed-show-prev)))))

(define-key elfeed-show-mode-map (kbd "SPC") 'elfeed-scroll-up-command)
(define-key elfeed-show-mode-map (kbd "S-SPC") 'elfeed-scroll-down-command)

Easier tagging

By default you can tag an entry from the search results by typing “+” followed by the tag name. This is too much work for a central organizational feature, so a little helper sorts things out.

(defun elfeed-tag-selection-as (mytag)
    "Returns a function that tags an elfeed entry or selection as
MYTAG"
    (lambda ()
      "Toggle a tag on an Elfeed search selection"
      (interactive)
      (elfeed-search-toggle-all mytag)))

Tag with a single letter keybind:

(define-key elfeed-search-mode-map "l" (elfeed-tag-selection-as 'readlater))
(define-key elfeed-search-mode-map "d" (elfeed-tag-selection-as 'junk))

Open feeds in Emacs

Elfeed will open links to feeds in your default browser with “b”. But for text heavy posts or to look up something specific I often want to open them in place in Emacs:

Your browser does not support the video tag.

Quick-preview links in eww.

Instead of writing a function to do this from scratch, we set eww (Emacs’ built in web browser) as the default in a short-lived let binding and let the usual browse-url functions handle the rest:

(defun elfeed-show-eww-open (&optional use-generic-p)
  "open with eww"
  (interactive "P")
  (let ((browse-url-browser-function #'eww-browse-url))
    (elfeed-show-visit use-generic-p)))

(defun elfeed-search-eww-open (&optional use-generic-p)
  "open with eww"
  (interactive "P")
  (let ((browse-url-browser-function #'eww-browse-url))
    (elfeed-search-browse-url use-generic-p)))

(define-key elfeed-show-mode-map (kbd "B") 'efleed-show-eww-open)
(define-key elfeed-search-mode-map (kbd "B") 'efleed-search-eww-open)

We can take this idea further. The following snippet will ensure that Emacs (and thus Elfeed) defaults to opening Youtube links in mpv (or the video player of your choice), cutting the browser out of the loop entirely. ³

(setq browse-url-browser-function
      '(("https:\\/\\/www\\.youtu\\.*be." . browse-url-mpv)
        ("." . browse-url-generic)))

(defun browse-url-mpv (url &optional single)
  (start-process "mpv" nil "mpv" (shell-quote-argument url)))

There is Elfeed Goodies, a package on github that provides a split pane setup to Elfeed. But it’s rather large for what it does, has a dependency I don’t need (popwin.el) for a single function and provides much else that I have no use for. ↩︎
A previous version of this write-up used macros instead of closures for the helpers. This simpler solution was suggested by /u/nv-elisp on Reddit. ↩︎
mpv requires Youtube-dl to play youtube videos. ↩︎

yakshaving on Karthinks

Fringe Matters: Finding the Right Difference

Rise and shine, Dr. Diffman. Rise and shine.

The right diff in the wrong place…

…can make all the difference in the world.

Not that I wish to imply you have been sleeping on the margins.

All the effort in the world would have gone to waste until…

…well, let’s just say your hour has come again.

So, wake up, Dr. Diffman. Wake up and mark the fringes.

For Your Reference: RefTeX in Org Mode

Just give me the code

Background: org-link, org-ref and oxr

What’s a RefTeX?

Sprucing up the RefTeX experience

Insert references with consult-reftex

Looking up references: consult-reftex (again)

Fontify…

…and Prettify: TeX-fold-mode

Moving around references: big ol’ pile o’hacks

Jumping to definition: xref support, more hacks

Auto-preview reference at point: eldoc support

Yep, reftex-dcr exists

Different Strokes For Different Folks

Economy and interprogram contexts

Pasting text from other applications into a new buffer

git-clone from a repository URL

open a project directory in dired so we can drag and drop a file

mpv + live video transcript in Emacs

Expressivity

How to mouse around

Improving Strokes

It’s not all or nothing. It’s not even something.

Cool your heels, Emacs

As a package author, you can

Use conservative defaults

Account for as many contexts as possible

As a user, you can:

Report slowdowns

Use fewer packages

Timeouts and Delays

First up: Throttle

Second: Debounce

Aside: Memoize

throttle! and debounce!

Example: throttle smart-mode-line updates

Example: debounce org-agenda-follow-mode

An inside-out implementation

Advising around

Top-level vs nested calls: what can we timeout?

throttle and debounce: Non-destructive finagling

Mirroring interactive forms

Inserting function documentation

It’s macrotime!

Questions

The timeout library

Persistent prefix keymaps in Emacs

Notmuch Ado About Nothing

It Bears Repeating: Emacs 28 & Repeat Mode

What’s in a keymap

Adding repeat-mode support to keymaps

Repeat Mode vs Hydra, Transient and Hercules

Adding a Hydra-like prompt to Repeat Mode

Command smells

…but I repeat myself

Scaling Latex previews in Emacs

The Problem

The Hack

The Recipe

Dired history in Emacs

An Elisp Editing Tip

Declickbait Elfeed

Jumping directories in eshell

Lazy Elfeed

Display the feed list and current entry in a split pane setup 1:

Navigate the entire database with the space bar

Easier tagging

Open feeds in Emacs

Background: `org-link`, `org-ref` and `oxr`

Insert references with `consult-reftex`

Looking up references: `consult-reftex` (again)

…and Prettify: `TeX-fold-mode`

Jumping to definition: `xref` support, more hacks

Auto-preview reference at point: `eldoc` support

Yep, `reftex-dcr` exists

`throttle!` and `debounce!`

Example: throttle `smart-mode-line` updates

Example: debounce `org-agenda-follow-mode`

`throttle` and `debounce`: Non-destructive finagling

Mirroring `interactive` forms

The `timeout` library

Adding `repeat-mode` support to keymaps

Display the feed list and current entry in a split pane setup ¹: