Kristoffer Balintona — Articles

Basic journals and logs with org-node

Thu, 01 Jan 1970 00:00:00 GMT

The dilemma
Final result
Final words

The dilemma §

In the last month I’ve become more and more convinced that I should start migrating from org-roam to org-node. Dealing with org-node’s elisp API (as opposed to org-roam’s sqlite API) is easier, and I think org-node has even greater potential for future growth

(see indexed.el, the speedy library tk)

;; Bespoke function meant for datetrees in org-node nodes
(defun krisb-org-capture--org-node-datetree ()
  "Creates datetree at org-node node.
Prompts for an org-node node, creates a datetree there, and leaves point
where a new entry should be.  Meant to be used by itself as a function
in `org-capture-templates'."
  (require 'org-node)
  (require 'org-datetree)
  (let* ((candidate (completing-read "Select journal: "
                                     #'org-node-collection
                                     (lambda (_title node) (member "__journal" (org-node-get-tags node)))
                                     t nil 'org-node-hist))
         (node (gethash candidate org-node--candidate<>node))
         (file (org-node-get-file node))
         (olp (when (< 0 (org-node-get-level node))
                (org-node-get-olp-with-self node)))
         (pt (org-node-get-pos node))
         (date (calendar-gregorian-from-absolute
                (time-to-days
                 (org-capture-get :default-time)))) ; Respect C-1 and :time-prompt
         (buffer (org-capture-target-buffer file))
         (tree-type (org-capture-get :tree-type))) ; Respect :tree-type
    ;; See `org-capture-set-target-location' for an explanation of the next
    ;; few lines
    (set-buffer buffer)
    (org-capture-put-target-region-and-position)
    (widen)
    (goto-char pt)
    ;; Create datetree.  See the implementation of
    ;; `org-capture-set-target-location' for an explanation of the lines
    ;; below; it handles all the cases org-capture does
    (funcall
     (pcase tree-type
       (`week #'org-datetree-find-iso-week-create)
       (`month #'org-datetree-find-month-create)
       (`day #'org-datetree-find-date-create)
       ((pred not) #'org-datetree-find-date-create)
       ((pred functionp)
        (lambda (d keep-restriction)
          (org-datetree-find-create-hierarchy
           (funcall tree-type d) keep-restriction)))
       ((pred listp)
        (lambda (d keep-restriction)
          (funcall #'org-datetree-find-create-entry tree-type
                   d keep-restriction)))
       (_ (error "Unrecognized :tree-type")))
     date
     (when olp 'subtree-at-point))))

Final result §

(setopt org-capture-templates
        `(("t" "Todo" entry
           (file ,(expand-file-name "todo.org" krisb-org-agenda-directory))
           "* TODO %? :INBOX:%^g\n"
           :empty-lines 1)
          ("T" "Todo (without processing)" entry
           (file ,(expand-file-name "todo.org" krisb-org-agenda-directory))
           "* TODO %? %^g\n"
           :empty-lines 1)
          ("j" "Journal" entry
           (function krisb-org-capture--org-node-datetree)
           "* %<%c>\n%?"
           :tree-type (year quarter month)
           :jump-to-captured t
           :immediate-finish t
           :empty-lines 1
           :clock-in t
           :clock-resume t)
          ("l" "Log" item
           (function krisb-org-capture--org-node-datetree)
           "%U %?"
           :tree-type (quarter week)
           :clock-in t
           :clock-resume t)
          ("m" "Work meeting notes" entry
           (file+olp+datetree ,(lambda () (org-node-get-file (org-node-by-id "20241114T091749.707997"))))
           "* (%<%c>)%?\n\n"
           :tree-type (year quarter month)
           :jump-to-captured t
           :immediate-finish t)
          ("b" "Blog post" plain
           (function (lambda ()
                       (let ((org-node-ask-directory krisb-blog-directory))
                         (org-node-capture-target))))
           "#+filetags: :__draft:
,#+hugo_bundle:
,#+export_file_name: index
,#+hugo_tags:
,#+hugo_categories:
,#+hugo_publishdate:
,#+hugo_lastmod:
,#+hugo_custom_front_matter: :TableOfContents true
,#+hugo_draft: true
,#+hugo_paired_shortcodes:\n\n%?"
           :jump-to-captured t
           :immediate-finish t)))

Final words §

Although this code is written for org-node, since accessing org-node’s nodes and org-roam’s nodes are practically identical, it could easily be adapted to be used by org-roam.

Customized LaTeX exports for humanities papers

Thu, 01 Jan 1970 00:00:00 GMT

The pain-point §

Approach 1 §

initially redefined latex exporter; but that created a long section in my config with majority redundancy with upstream code and brittle to future upstream changes

lots of boilerplate to register new derived backend, and a bit hacky to repalce the old latex backend entry in the org export menu with the replacement version

also overkill when you just want “default latex exporter but recognizing a few more keywords”

which is why we have approach 2 and 3

Approach 2 §

first tried org-export-filter-keyword-functions; didn’t work because unknown keywords are ignored, not making it to the stage when filter functions are run

I found a solution with org-export-before-parsing-functions: convert those keyword lines into #+LATEX_HEADER lines (which ox-latex does convert)

Approach 3 §

but, in the end, if you just want latex export, you can use the #+LATEX_HEADER and #+LATEX_HEADER_EXTRA keywords

merit: explicit declaration, not depending on your config

but: as a consequence, if aspects involving in exporting the file are declared outside of the file (e.g., .sty file), the explicit file declaration might be end up brittle

Features I’m looking forward to in Emacs 31

Thu, 01 Jan 1970 00:00:00 GMT

VC-Dir: Offer to register files before checking in

savehist.el: Handle concurrent access to `savehist-file` But…

This feature is activated only when 'savehist-additional-variables' is nil.

New user option to hide minor mode lighters (bug#77361) Basically minions.el

vc-dir-mark-file: Consistently don’t allow marking a subdirectory

* | a5f574429db 2025-04-06 (10 days ago) Sean Whitton
| |   vc-dir-mark-file: Consistently don't allow marking a subdirectory
commit a5f574429db1f820cc4d25bfb0e700aae050dc07
Author: Sean Whitton <spwhitton@spwhitton.name>
Date:   Sun Apr 6 09:09:32 2025 +0800

vc-dir-mark-file: Consistently don't allow marking a subdirectory

* lisp/vc/vc-dir.el (vc-dir-mark-file): Don't allow marking a
subdirectory if its parent is already marked.  This fixes an
inconsistency whereby if a subdirectory was already marked then
its parent could not be marked, but not vice-versa (bug #76769).

Teach VC-Dir to automatically add and remove marks on other lines

* | 936b2efdb38 2025-04-06 (10 days ago) Sean Whitton
| |   Teach VC-Dir to automatically add and remove marks on other lines
commit 936b2efdb389488d291086d5c2189fd1a7170aa6
Author: Sean Whitton <spwhitton@spwhitton.name>
Date:   Sun Apr 6 11:18:57 2025 +0800

Teach VC-Dir to automatically add and remove marks on other lines

* lisp/vc/vc-dir.el (vc-dir-allow-mass-mark-changes): New option.
(vc-dir-parent-marked-p): Replace with ...
(vc-dir--parent): ... this.
(vc-dir-children-marked-p): Replace with ...
(vc-dir--children): ... this.
(vc-dir-mark-file): Unmark subitems before marking a directory.
Offer to unmark a directory before marking a subitem.
(vc-dir-unmark-file): For an implicitly marked item, offer to
unmark it by marking everything else that's implicitly marked.
For an unmarked directory with marked subitems, offer to unmark
them all.
* etc/NEWS: Document the changes.

vc-setup-buffer: Don’t pass a string to buffer-live-p.

* | 2310c12658c 2025-04-09 (7 days ago) Sean Whitton
| |   ; vc-setup-buffer: Don't pass a string to buffer-live-p.
commit 2310c12658c4b563f9860cb1196bab0d56c6f94d
Author: Sean Whitton <spwhitton@spwhitton.name>
Date:   Wed Apr 9 11:04:26 2025 +0800

; vc-setup-buffer: Don't pass a string to buffer-live-p.

savehist.el: Handle concurrent access to `savehist-file`

* bfeb755e03b 2025-04-12 (3 days ago) Stefan Monnier
|   savehist.el: Handle concurrent access to `savehist-file`
commit bfeb755e03b5cab8f1f234b1a54afbcfd71f9eb2
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Date:   Sat Apr 12 22:43:20 2025 -0400

savehist.el: Handle concurrent access to `savehist-file`

* lisp/savehist.el (savehist--manage-timer): Minor simplification.
(savehist-coding-system): Use `utf-8-emacs-unix` so it works even if
some history entries contain chars that aren't in Unicode.
(savehist-loaded): Mark it obsolete.
(savehist--file-sync-modtime): New var to replace it.
(savehist--file-modtime, savehist--merge): New functions.
(savehist--reload): New function, extracted from `savehist-mode`.
Make it merge the old history and the newly loaded one.
Remember the time of sync in `savehist--file-sync-modtime`.
(savehist-mode): Use it.
(savehist-save): Use it as well, and set `savehist--file-sync-modtime`.
(savehist--last-autosave): New var.
(savehist-autosave): Use it to skip saves when not enough time has passed.

Better diagnostic capabilities in flymake 1.4.0
Awesome: mode-line-collapse-minor-modes Only applies to active minor modes (unlike minions.el, which shows all minor modes that are hidden). If any minor mode is hidden, then an ellipsis will be shown at the end of the mode line lighters section.
New ‘fancy value for flymake-show-diagnostics-at-end-of-line (commit diff)
```
Enhanced 'flymake-show-diagnostics-at-end-of-line'
The new value 'fancy' allowed for this variable will attempt to layout
diagnostics below the affected line using unicode graphics to point to
diagnostic locus.
```
Note that it works best (i) when the line-spacing is 0 (because of the vertical bars) and (ii) when there aren’t many diagnostics per line

buffer-match-p (and therefore display-buffer-alist) now accepts the “this-command” condition, allowing per-command buffer display rules^[1]

* 343f0c44f35 2025-05-01 (75 minutes ago) Sean Whitton (upstream/master, upstream/HEAD)
|   New this-command buffer display action alist entry
commit 343f0c44f35c41b93c66f67da0ddeceb98bbdb93
Author: Sean Whitton <spwhitton@spwhitton.name>
Date:   Thu May 1 20:55:56 2025 +0800

New this-command buffer display action alist entry

* lisp/subr.el (buffer-match-p): New this-command cons cell
condition to implement new this-command buffer display action
alist entry (bug#78082).
* lisp/window.el (display-buffer):
* doc/lispref/windows.texi (Buffer Display Action Alists):
* etc/NEWS: Document the new buffer display action alist entry.

New native-comp-async-on-battery-power option
Add next-error support for flymake diagnostics buffers

delete-trailing-whitespace-mode

* 8a19c249f81 2025-05-05 (7 days ago) Stefan Monnier
|   simple.el (delete-trailing-whitespace-mode): New minor mode (bug#78264)
commit 8a19c249f813e9f3830308e40f0205d7665f78a3
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Date:   Mon May 5 11:55:29 2025 -0400

simple.el (delete-trailing-whitespace-mode): New minor mode (bug#78264)

Partly motivated by bug#78097.

* lisp/simple.el (delete-trailing-whitespace-if-possible): New function.
(delete-trailing-whitespace-mode): New minor mode.

* lisp/editorconfig.el (editorconfig-trim-whitespaces-mode):
Change default to `delete-trailing-whitespace-mode`.
(editorconfig--get-trailing-ws): Simplify accordingly.
(editorconfig--add-hook-safe-p): Delete function.  Don't touch
`safe-local-eval-function` any more.

New vc-async-checkin for async Git and Mercurial vc checkin (e.g., committing)

* 8e02537d0be 2025-04-05 (5 weeks ago) Sean Whitton
|   New vc-async-checkin user option
commit 8e02537d0be3cfdeaaf7764e2ef2db8b66de542a
Author: Sean Whitton <spwhitton@spwhitton.name>
Date:   Sat Apr 5 10:58:35 2025 +0800

New vc-async-checkin user option

* lisp/vc/vc.el (vc-async-checkin): New option.
(vc-checkin): Don't use with-vc-properties on or display
messages around asynchronous checkins.
* lisp/vc/vc-git.el (vc-git-checkin):
* lisp/vc/vc-hg.el (vc-hg-checkin, vc-hg-checkin-patch): Perform
an async checkin operation when vc-async-checkin is non-nil.
* doc/emacs/vc1-xtra.texi (General VC Options):
* etc/NEWS: Document the new option.

* lisp/vc/vc-dispatcher.el (vc-wait-for-process-before-save):
New function.
(vc-set-async-update): If the current buffer visits a file, call
vc-refresh-state.
* lisp/vc/vc-hg.el (vc-wait-for-process-before-save): Autoload.
(vc-hg--async-command, vc-hg--async-buffer, vc-hg--command-1):
New utilities, partially factored out of vc-hg-command.
(vc-hg-merge-branch): Use vc-hg--async-command, thereby newly
respecting vc-hg-global-switches.

Prettify and improve hideshow: hs-display-lines-hidden and “Buttonize the ellipsis and optionally display in the ellipsis the total number of hidden lines.”

New log-edit-hook which can be combined nicely with new log-edit-show-diff to automatically display diff of changes to commit. From b9886bb2069:

New 'log-edit-hook' option to display diff of changes to commit.

You can customize 'log-edit-hook' to include its new
'log-edit-maybe-show-diff' option to enable displaying a diff of the
changes to be committed in a window.  This is like the 'C-c C-d' command
in Log Edit mode buffers, except that it does not select the *vc-diff*
buffer's window, and so works well when added to 'log-edit-hook'.

New user option vc-dir-hide-up-to-date-on-revert - emacs.git - Emacs source repository
Add option for not highlight parens inside comments or strings - emacs.git - Emacs source repository
New crm-prompt (patch contributed by vertico author)
bec823b107e: New user option: vc-allow-async-diff
60fbeda7716 Support strings for electric pairs
VC: New incoming & outgoing diff commands (bug#62940) - emacs.git - Emacs source repository

f746762e74a New command mode-line-invisible-mode

  * f746762e74a 2025-06-23 (3 weeks ago) Elías Gabriel Pérez
|   New command 'mode-line-invisible-mode'
commit f746762e74adeac8beaa73abcf20ee5e74298597
Author: Elías Gabriel Pérez <eg642616@gmail.com>
Date:   Mon Jun 23 12:50:28 2025 -0600

  New command 'mode-line-invisible-mode'

  This new command allows hide the mode line in the current
  buffer.  (Bug#78881)

  * doc/emacs/display.texi (Optional Mode Line): Document feature.
  * etc/NEWS: Announce changes.
  * lisp/simple.el (mode-line-invisible--buf-state): New buffer
  local variable.
  (mode-line-invisible-mode): New minor mode.

9d750c7e804 New global minor mode vc-auto-revert-mode

  * 9d750c7e804 2025-07-13 (31 minutes ago) Sean Whitton (upstream/master, upstream/HEAD)
|   New global minor mode vc-auto-revert-mode
commit 9d750c7e8041437758c919f6088d6f3686847812
Author: Sean Whitton <spwhitton@spwhitton.name>
Date:   Sun Jul 13 12:50:22 2025 +0100

  New global minor mode vc-auto-revert-mode

  * lisp/vc/vc-hooks.el (auto-revert-mode): Declare.
  (vc-auto-revert-mode): New global minor mode.
  (vc-turn-on-auto-revert-mode-for-tracked-files): New function.
  * lisp/vc/vc-dispatcher.el (auto-revert-mode)
  (auto-revert-buffers): Declare.
  (vc-resynch-window): Don't call vc-revert-buffer-internal when
  auto-revert-mode will revert the buffer.  Call
  auto-revert-buffers to ensure that this reversion happens in a
  timely manner.
  * lisp/vc/vc.el (vc-register): Apply vc-auto-revert-mode to
  buffers visiting newly registered files.
  * lisp/emacs-lisp/easy-mmode.el (define-globalized-minor-mode):
  Improve the generated docstring.
  * doc/emacs/vc1-xtra.texi (VC Auto-Reverting):
  * etc/NEWS: Document the new minor mode.

A less computing-taxing solution to global-auto-revert-mode since it is on-demand (after VC changes).

Bind vc-rename-file to C-x v R - emacs.git - Emacs source repository
VC: New support for other working trees - emacs.git - Emacs source repository
Commit 50ffb29d0bb 2025-07-25 Sean Whitton: VC: New support for other working trees
Commit cd31c3cb423 2025-06-16 James Thomas: Add ‘other-window-backward’ for a default binding (bug#78803)
Commit 6b2856f9cab 2025-07-28 Paul Nelson: Allow numbered buffer selection for project-shell
Commit 997461f48497e67ca4913ad18ae7d6d3562459d7 whitespace-mode: New style to prettify page delimiters characters.
Commit 4d90bdb385a23b26ddecae04b92e5557be172d27 Add support for updating Completions as you type
New commands for outgoing diffs including uncommitted changes - emacs.git - Emacs source repository
Commit 2cc525467bcf3ec5c3ba437fc8291a236ee138bc: New mode ‘minibuffer-nonselected-mode’
Commit a760f1fe6e10f91c9600595ac57a1ff53b006343: (register-preview-info): sort registers in preview buffer
All the new hideshow features
New commands to rewind decentralized VCS branches - emacs.git - Emacs source repository
Expand on showing warnings on first daemon frame.
Default split-window-preferred-direction to ‘longest’
Commit ab8d3624c414ebf8c4df7dd5385b8759eb477bf1 Do eager display of Completions while idle
Commit 11b68c6223d154b4c85e8feec63581dcf7c76a3e Sean Whitton New commands to rewind decentralized VCS branches
Commit 2b1440946e20bcf910f03cd665f68a268c687192 Stéphane Marks New optional recentf autosave timer (bug#80002)
Commit 7425e33287547b879c22c4f4ac1b7c78fcbdd6f9 Sean Whitton New M-RET, M-p, M-n commands in Log View mode
Allow reviewing packages before installaion - emacs.git - Emacs source repository
Make diff-hunk-kill respect an active region - emacs.git - Emacs source repository
Allow using xref-find-references without visiting a tags table - emacs.git - Emacs source repository Convenient; I had lines in my init.el that removed etags--xref-backend from xref-backend-functions for this purpose. I no longer need those lines.
commit aa181cd35220242a23fe98932386facaba18c4c5: Rewrite flex completion with Gotoh algorithm Author: João Távora <joaotavora@gmail.com> Date: Tue Feb 3 12:14:03 2026 +0000

Org and LaTeX integration

Thu, 01 Jan 1970 00:00:00 GMT

My desired workflow §

Org-export is a means to convert org files into LaTeX files. The question this article explores is how I answer the following question: How can I write my university essays in org and export them directly into a LaTeX PDF file without any further adjustments? This means the following:

Basic formatting: Elements such as line spacing, margins, font should be set automatically.
Citations: In-text citations and bibliographies should be formatted automatically.
Flexibility with styles: I should be able to switch between, e.g., MLA, APA, and Chicago Manual Style without any fuss.
Boilerplate text: I want to do all of the above with very little to no boilerplate text in my org files (e.g. I shouldn’t rely on many #+LaTeX_header: lines).

In short, I simply want to produce my final paper’s PDF by calling a single org-export command. Here, I visit the portions of my configuration where I make accomplish such a workflow.

A note for STEM (Science, Technology, Engineering, and Mathematics) students: As a philosophy undergraduate, this article primarily centers on a subset of concerns STEM students would face in formatting their papers, since mathematics, tables, and other LaTeX features will be much more common. This is beyond my use case, but I hope that this article still has a use for those students. Additionally, there are many other resources available that cover similar use cases (link such sources later tk).

Basic Formatting: `org-latex-classes` §

Title pages: Creating an Org-export backend §

The most challenging hurdle is conveniently producing a formatted title page^[1].

The most convenient method would be setting org-latex-title-command. With this, we can manually insert a formatted title page. However, this method is inflexible: different styles require different values for this variable.

A nearby alternative would be redefining the default \maketitle command that org already uses for every file. However, doing so would require additional #+LaTeX_HEADER: text.

Conveniently, we can leverage the already exist .sty file and redefine the \maketitle command there, instead.

The challenge, however, lies in how to get the requisite metadata from our org file. For instance, MLA requires four pieces of information in its title page:

Author name
Professor’s name
Course code and/or title
Current date

Items (1) and (4) can be done simply. However, (2) and (3) are contingent on the exported essay. We can try making use of built-in org options such as #+AUTHOR: and #+CREATOR:, but this alone cannot provide a robust solution. So, instead of trying to abuse existing options, I opt to create my own.

Take a look at the docstring for org-export-define-backend:

Docstring for org-export-define-backend

(org-export-define-backend BACKEND TRANSCODERS &rest BODY)

Define a new backend BACKEND.

TRANSCODERS is an alist between object or element types and
functions handling them.

These functions should return a string without any trailing
space, or nil. They must accept three arguments: the object or
element itself, its contents or nil when it isn’t recursive and
the property list used as a communication channel.

Contents, when not nil, are stripped from any global indentation
(although the relative one is preserved). They also always end
with a single newline character.

If, for a given type, no function is found, that element or
object type will simply be ignored, along with any blank line or
white space at its end. The same will happen if the function
returns the nil value. If that function returns the empty
string, the type will be ignored, but the blank lines or white
spaces will be kept.

In addition to element and object types, one function can be
associated to the ‘template’ (or ‘inner-template’) symbol and
another one to the ‘plain-text’ symbol.

The former returns the final transcoded string, and can be used
to add a preamble and a postamble to document’s body. It must
accept two arguments: the transcoded string and the property list
containing export options. A function associated to ‘template’
will not be applied if export has option “body-only”.
A function associated to ‘inner-template’ is always applied.

The latter, when defined, is to be called on every text not
recognized as an element or an object. It must accept two
arguments: the text string and the information channel. It is an
appropriate place to protect special chars relative to the
backend.

BODY can start with pre-defined keyword arguments. The following
keywords are understood:

:filters-alist

    Alist between filters and function, or list of functions,
    specific to the backend. See org-export-filters-alist for
    a list of all allowed filters. Filters defined here
    shouldn’t make a backend test, as it may prevent backends
    derived from this one to behave properly.

:menu-entry

Menu entry for the export dispatcher. It should be a list
like:

(KEY DESCRIPTION-OR-ORDINAL ACTION-OR-MENU)

where :

KEY is a free character selecting the backend.

DESCRIPTION-OR-ORDINAL is either a string or a number.

      If it is a string, is will be used to name the backend in
      its menu entry. If it is a number, the following menu will
      be displayed as a sub-menu of the backend with the same
      KEY. Also, the number will be used to determine in which
      order such sub-menus will appear (lowest first).

ACTION-OR-MENU is either a function or an alist.

      If it is an action, it will be called with four
      arguments (booleans): ASYNC, SUBTREEP, VISIBLE-ONLY and
      BODY-ONLY. See org-export-as for further explanations on
      some of them.

If it is an alist, associations should follow the
pattern:

(KEY DESCRIPTION ACTION)

where KEY, DESCRIPTION and ACTION are described above.

Valid values include:

(?m “My Special Backend” my-special-export-function)

       (?l “Export to LaTeX”
           ((?p “As PDF file” org-latex-export-to-pdf)
            (?o “As PDF file and open”
                (lambda (a s v b)
                  (if a (org-latex-export-to-pdf t s v b)
                    (org-open-file
                     (org-latex-export-to-pdf nil s v b)))))))

or the following, which will be added to the previous
sub-menu,

       (?l 1
          ((?B “As TEX buffer (Beamer)” org-beamer-export-as-latex)
           (?P “As PDF file (Beamer)” org-beamer-export-to-pdf)))

:options-alist

    Alist between backend specific properties introduced in
    communication channel and how their value are acquired. See
    org-export-options-alist for more information about
    structure of the values.

You have a few options.

Customize the `org-export` LaTeX backend §

File properties

Backend §

There is org-export-define-backend and org-export-define-derived-backend. Defining a backend…

The latter is identical, only in that it inherits the definition of a parent backend. For instance, beamer is a derived backend from latex. I won’t go in depth into this because you can read the docstrings for them.

Template §

Final title command §

\renewcommand{\maketitle}{
  \begin{flushleft}
    \theauthor \\
    \professor \\
    \course    \\
    \thedate
  \end{flushleft}

  \centerline{\thetitle}
}

Citations and bibliographies: Org-cite §

Nowadays, with the comparatively new org-cite, citations and bibliography is the easiest step of this process. Readers should refer to Citations in org-mode: Org-cite and Citar for more information, but once org-cite is set up, potentially with citar, org-export will seamlessly export citations and bibliographies.

For reference, the following is my org-cite configuration (this doesn’t include citar):

org-cite configuration

(use-package oc
  :elpaca nil                           ; I use the `elpaca' package manager
  :general (:keymaps 'org-mode-map [remap citar-insert-citation] 'org-cite-insert)
  :custom
  (org-cite-global-bibliography kb/bib-files)
  (org-cite-csl-locales-dir (file-name-concat user-emacs-directory "locales/"))
  (org-cite-csl-styles-dir (expand-file-name "~/Zotero/styles/"))
  (org-cite-export-processors
   '((md . (csl "chicago-fullnote-bibliography.csl"))   ; Footnote reliant
     (latex biblatex)                                   ; For humanities
     (odt . (csl "chicago-fullnote-bibliography.csl"))  ; Footnote reliant
     (docx . (csl "chicago-fullnote-bibliography.csl")) ; Footnote reliant
     (t . (csl "modern-language-association.csl"))))    ; Fallback
  :custom-face
  ;; Have citation link faces look closer to as they were for `org-ref'
  (org-cite ((t (:foreground "DarkSeaGreen4"))))
  (org-cite-key ((t (:foreground "forest green" :slant italic))))
  :config
  ;; NOTE 2023-07-14: Require all `oc-*' packages so that I don't run into the
  ;; issue where the package associated with a style (e.g. `oc-biblatex' for the
  ;; biblatex style) in `org-cite-export-processors' is used prior to its
  ;; loading
  (require 'oc-natbib)
  (require 'oc-csl)
  (require 'oc-basic)
  (require 'oc-bibtex)
  (require 'oc-biblatex))

One way to specify citation style §

The value of org-cite-export-processors is most notable. The configuration above instructs org-export to use the biblatex export processor to process citations and bibliographies when exporting to LaTeX. This can be overridden, for example, at the file-level with the #CITE_EXPORT keyword. See the docstring for org-cite-export-processors for more information about valid values.

Notably, for LaTeX exports, we can specify the style (citation style and bibliography style) of citations in this way. For instance, taking a look at the commentary for the oc-biblatex library, we read:

;; In any case, the library will override style-related options with those
;; specified with the citation processor, in `org-cite-export-processors’ or
;; “cite_export” keyword. If you need to use different styles for bibliography
;; and citations, you can separate them with “bibstyle/citestyle” syntax. E.g.,
;;
;; #+cite_export: biblatex authortitle/authortitle-ibid

This means that, for instance,

#+cite_export: biblatex mla-new/authoryear

results in "bibstyle=mla-new,citestyle=authoryear" being passed as an option to biblatex. Or we can set this in org-cite-export-processors:

(setq org-cite-export-processors '((latex . (biblatex "mla-new/authoryear"))))

Valid styles include those provided by the built-in with biblatex, found in section 3.3.2 of the biblatex CTAN manual (link tk), and those provided by numerous other packages.

My method to specify citation style §

Though the above works, since I’m already using a .sty file to set all the options for the relevant LaTeX packages, I also do so there. For instance, with the MLA citation style:

% * Bibliographic source management
% Declares MLA internal cite and bibliography styles
\RequirePackage[style=mla-new]{biblatex}
\addbibresource{../../master-lib.bib}

In this way, I avoid adding a line in my org files to specify the citation style:

#+cite_export: biblatex mla-new

Final result and screenshots §

The following org file produces this:

which, compiled into a PDF, looks like this:

Extras §

Section numbers §

(setq org-export-with-section-numbers nil)

Hyperref §

(setq org-latex-hyperref-template
      "\\hypersetup{
pdfauthor={%a},
pdftitle={%t},
pdfkeywords={%k},
pdfsubject={%d},
pdfcreator={%c},
pdflang={%L}
colorlinks={true},
hidelinks={true}}\n")

Table of contents §

(setq org-latex-toc-command
      "\\renewcommand{\\contentsname}{
  \\begin{center}
    Table of Contents
  \\end{center}
}
\\tableofcontents
\\newpage")

Org links §

Custom org-mode links (org-link-set-parameters)

Full configuration §

(Make a note about that there are other stuff in the configuration not referenced or described tk.)

The state of grammar checking in Emacs

Thu, 01 Jan 1970 00:00:00 GMT

Old
- artbollocks-mode
- writegood-mode
- languagetool
  - flymake-languagetool
  - flycheck-languagetool
- proselint via…
  - flymake-proselint
  - flymake-collection
Modern
- vale
- harper-ls
  - Mention emacs configuration? · Automattic/harper · Discussion #150 · GitHub for hints/leads on the progress of org-mode support

There are lots of options for sidenotes

Thu, 01 Jan 1970 00:00:00 GMT

Blessed Syntax and Ergonomics - gingerBill

Tufte CSS

Sidenotes In Web Design · Gwern.net

Tufte-Style Sidenotes in Astro - keith.is

Making semantic sidenotes without JavaScript | Koos Looijesteijn GitHub - kslstn/sidenotes: Semantic sidenotes for the web without JavaScript · GitHub (CSS + HTML example) My web site: sidenotes implementation - Denis Defreyne (for improvement to avoid overlaps and finicky absolute positioning: float: right and clear: both)

Today I learned: Cool CSS anchor positioning use case: margin notes — Julian Burr CSS anchoring live example

What I learned starting web dev with Astro

Thu, 01 Jan 1970 00:00:00 GMT

HTML best practices §

see [BROKEN LINK: 20260406T155358.633044]

This is a sentence.

Components are awesome §

scoped CSS (selectors, see [BROKEN LINK: h:20260421T031520.230702])

CSS §

a confusing bit: selectors are scoped by styling in the rendered page is not scoped by component

MD vs MDX vs Markdoc §

Markdoc | Frequently asked questions Markdoc | The Markdoc syntax

An Amazing Marvin Starter Pack

Thu, 24 Jun 2021 22:37:00 GMT

TL;DR
Core concepts
- The Master List
- The Main View
What good is Amazing Marvin’s system?
The beauty of Strategies
A list of must-look-at Strategies
Author’s Note

TL;DR §

Read this if you are either 1) interested in and want to try out Amazing Marvin, 2) just started using Amazing Marvin but feel overwhelmed, or 3) don’t know what Amazing Marvin is but want to read about a few of its features.

This post goes over the peculiarities of Amazing Marvin — namely the Master List, Main View, and Strategies. Understanding these concepts is the first step to leveraging the strengths of Amazing Marvin to create your own workflow.

I’ve also added a list of the first Strategies a new Mavinaut (users of Amazing Marvin) should check out.

By the end you’ll have a grasp of Amazing Marvin’s foundational components and ready to start building your own workflow.

Core concepts §

The Master List §

You open Marvin. You’re greeted with a friendly UI — you notice buttons and a sidebar. Press “M” and you’ll be taken to the Master List. This is the place where you can see all your tasks. Think of it as the closest thing to a generic todo list application, like Microsoft Todo. You can view your tasks and projects (which can be further separated into categories) in either a column or list view (try it out!).

You may also notice a sidebar on the left which also lists tasks and projects — this can be toggled using “X”. This will be handy in the future, but isn’t necessary to worry about for now.

In the Master List, I sometimes add tasks in bulk, which will often be when I want to flesh out tasks for a project. Though you can easily access all your projects and tasks using the Master List, you will likely not spend much time here.

The Main View §

The place where you will most interact with your todos and get things done is the Main View. The Main View is where you decide which tasks are shown, when they are shown, and how they are shown to you by taking advantage of Amazing Marvin’s customizability.

The Main View is centralized around being able to show you what you want to do today. This doesn’t, however, necessarily mean that Marvin is limited to showing you tasks which are due today. Amazing Marvin is more powerful than that and has the flexibility to accommodate so many workflows.

What good is Amazing Marvin’s system? §

Those are the two most important pieces to wrap your head around using Amazing Marvin. But why depart from the typical todo list format?

The strength of this system is that you have access to all your tasks in your Master List but don’t have to look through these long task lists — even sorted or filtered, they are overwhelming and dissuasive to productivity — in order to get things done. The Main View creates a divide between working on your tasks and viewing them. This is a surprisingly powerful feature of Marvin, which removes much of the difficulty of trying to juggle tasks within folders or across tags. You choose when to see the subset of tasks you want to work on, and go to the Master List when you choose to see all of your tasks.

The beauty of Strategies §

On top of that, Marvin is still feature-rich yet manages to limit that complexity for an easier learning curve. How Marvin accomplishes this is through its clever Strategies system. Strategies allow you to only enable the features which are useful to you. They can be thought of as togglable features.

Strategies are one of the aspects that make Amazing Marvin shine. It gives you the flexibility to implement as many strategies as you want (again, think of them as features) into your workflow or be as minimalist as possible and use only a select few. In the end, Amazing Marvin can be customized to how you think and work.

This is different from other task management apps, which follows the “you-get-what-you-see model.” In other task management apps, users have to use a space in which every feature, whether useful to them or not, coexists. This is especially the case with bloated or other feature-rich task management apps. In this way, Marvin can be feature-rich but much less overwhelming than other task management solutions.

Amazing Marvin goes a step further by providing brief yet useful descriptions for every Strategy on how to use it. Additionally, there is often an accompanying short video (made by Christina, one of the founders, herself) demonstrating what the Strategy looks like in action. Finally, most strategies have a list of settings which allow you to further fine tune your experience.

A list of must-look-at Strategies §

To conclude, I’ve included several lists of Strategies that should be taken a look at as soon as possible as a new user. In addition to checking these Strategies out, Workflow Templates are curated sets of settings and strategies which have been pre-made for you. They range from small snippets to full workflows. I’d highly recommend looking through these templates as a starting point for your workflow.

Standalone, non-intrusive, must-use Strategies

Subtasks
Mobile sidebar
Check off Behavior
Right-click menu
Hover button actions

Other common Strategies which are easy to set up

Quick add
Task notes
Category context
Skinny sidebar
Sidebar

Strategies you will likely be looking for if you’ve used other task management applications

Labels (tags)
Task reminders
Duration estimates
Full-calendar functionality
1. Calendar
2. Agenda
3. All-day items
4. Events
Smart lists (?)
Priority levels
Sequential projects

Useful Strategies which are standalone, easy to understand, yet aren’t found in almost any other task management app (Experiment with them!)

Work session scheduler
Eat that Frog
Procrastination count
Backburner
Time tracking
Missing Next Step warning
Timers

Author’s Note §

I have not been told to write about Amazing Marvin. I receive no compensation from Amazing Marvin for this post. I only want to share this amazing piece of software with others.

On Zettelkasten purism and the misdirection of backlinks

Tue, 27 Jul 2021 22:37:00 GMT

TL;DR §

Don’t be distracted by the allure of backlinks; a good knowledge management practice provides more value. Luhmann’s Zettelkasten isn’t law; your needs should instruct the directives you follow.

I disagree with ‘backlink exceptionalism’ §

The commonly understood novelty of the Zettelkasten tool is its non-hierarchical organization composed of hyperlinks. Backlinks generate interconnected networks of thought which mirror the associative nature of our brains. It is a departure from traditional hierarchical note-taking practices. Looking at the outlier of Niklas Luhmann, we can be quick to conclude that the backlink is the cause of Zettelkasten’s efficacy. The novelty of backlinks has made the concept synonymous with ‘Zettelkasten.’ However, there are many successful personal knowledge management systems, and it would be unwise to study only a sample size of one, decontextualizing Luhmann’s methodology from other successful knowledge management systems.

The spotlight is regularly on the serendipity and surprise from backlinks from an emergent network of interconnected notes. However, this is too narrow of a spotlight; there are many other changes in note-taking and production. For instance, the time spent writing — and thus thinking — is increased. There is a heightened intentionality from creating links, rearranging ideas, and concretely classifying new information. Deliberate writing and thinking has benefits to production which are too scarcely acknowledged. That is what I wish to address here.

The ‘practice’ is most essential §

At the broadest level, what makes a Zettelkasten effective? Firstly, a faithful Zettelkasten should help produce written pieces. Secondly, Zettelkasten’s note-taking process facilitates idea mastery and emergence. The latter induces the former because the artifacts of that note-taking process are directly used in future works; much of the thinking is often done before the first draft is even begun. Take away those artifacts, and you’re left with something awfully similar to a conventional note-taking system. Thus, we arrive at idea mastery as the core vehicle for Zettelkasten’s success.

I ask: from what does most of your mastery over new material arise? How does Zettelkasten facilitate idea mastery and emergence? Most would turn to the feature of backlinks because of its perceived novelty. However, I counter the common sentiment by claiming that idea mastery mostly arises from the practice associated with maintaining a Zettelkasten. I argue Zettelkasten’s essence is to repeatedly revisit, recall, and engage with that which you have learned, iterating upon the writing artifacts of that process — your crystallized thoughts — over time. Engaging with what you learn is the crux to a successful knowledge management system. The contribution of backlinks is too commonly conflated with the contribution of that routine. Backlinks are a complementary feature.

An aside: but what about backlinks?! §

I will address a potential concern. Namely, to underappreciate the power of backlinks is to discard the essential power of associative thinking. However, we must remember that we naturally think associatively irrespective of what system we use. Luhmann’s Zettelkasten is just the most formalized system (I know of) for this process. We need not be interdisciplinary to Luhmann’s degree; serendipitous discovery is not necessary for interdisciplinary work. At the very least, we should settle for a ‘good enough’ system and be productive, rather than working to find the perfect system. Surely, devoting all your energy to creating the perfect system is putting the cart before the horse — good thinking and meaningful work take priority.

Luhmann isn’t the only success story §

I observe similar principles intuitively arrived at by other incredibly productive and learned thinkers. It is common for scholars to reread books, have discourse with other intellectuals, obsess over ideas in gaps in their day, and, perhaps most importantly, write and talk about it. For instance, many authors and writers espouse the idea of a Commonplace Book, traditionally a journal which contains quotable passages, personal comments, and literary excerpts. Ryan Holiday, a prolific reader and author who has published over ten books in just a decade, is famously known for his own incarnation of the Commonplace Book known as The Notecard System. His system was directly adopted from one of his mentors, another bestselling author by the name of Robert Greene. I currently attend university and more than one of my professors have intuitively created their own knowledge management systems and found success in their academic work. One of those professors recommended I read How to Write a Thesis by Umberto Eco, which I found to be a surprisingly close analog to Luhmann’s Zettelkasten. The Zettelkasten community is also very familiar with Andy Matuschak’s Evergreen Notes, which is inspired by, but significantly departs from, Luhmann’s Zettelkasten. Also in this list are many notable figures in history including George S. Patton and Ronald Reagan. In short, Zettelkasten isn’t the only successful knowledge management system.

All of these systems have found incredible success, yet are not Zettelkasten; their particulars drastically differ. How? I have found that the details of these systems — when a note is made, when it is returned to, how sources are managed, et cetera — differ widely but are united by the common directive to continually linger with the material.

So what do you do now? §

Methodologies should not be dogmatic. The Notecard System, Evergreen notes, the Commonplace Book… Luhman’s Zettelkasten is just one incarnation of a personal knowledge management system out of many. The very fact that there are so many methodologies demonstrates that none are a panacea. Purism is counterproductive — it confines expression to Zettelkasten-esque formulations. Treat them as resources and conclude your own decisions. Eclectism is a sign of thoughtfulness and intentionality.

Furthermore, Luhmann likely did not begin with an awareness of the exact rules and principles his Zettelkasten would ultimately have. Rather, he began with an initial premise and built his Zettelkasten — and its rules — around what he needed: a means to think interdisciplinarily and broadly, enough to form a ‘Theory of Society.’ Thinking interdisciplinarily and broadly are attractive and most would no doubt value those benefits in a Zettelkasten system. But should that be the North Star for your Zettelkasten? Is that your ultimate goal in knowledge management? You must appreciate the difference between your goal and Luhmann’s. If they do not align, your system will not serve you as well as it should. Worse, if you do not have a clearly defined and articulated purpose, then your Zettelkasten will become a hodgepodge of things gathered elsewhere, vying for your attention to use it this way and that. It will be undirected and reliant on luck to stay afloat.

Indeed, new Zettelkasten users often get swept away by the semantics of “What does it mean for a note to be atomic?” or “What should be in a literature note instead of a Zettel?” or “When should I make a note?”. On the other hand, most longstanding users of Zettelkasten intuitively arrive at the same conclusion as me: consider what others have done, and take what is appropriate for you.

How has my own advice affected me? §

Once I disabused myself from the notion that I should know exactly what Luhmann’s principles were in order to follow his rules to a T, everything fell into place. Instead of thinking that a malfunction or failure of my system reflected my own lack of understanding, I started to adopt a problem-solving mentality, treating other implementations as resources and making my own judgments. For the first time my Zettelkasten started truly being effective.

Windows

Wed, 11 Aug 2021 02:30:00 GMT

Beauty §

Rarely do moments of clarity arrive: ephemeral gifts recognized only a beat too late. As an exercise in free association, my memory draws, once again, to that thunderstorm.

It materialised slowly yet caused me little alarm, not unlike my relationship with my dear window. I think its gradual pace is the reason why I didn’t notice it. But what I did notice was a feeling. An intangible awareness. The winds shivered ever so slightly, a seemingly imperceptible turbulence in the air.

I find this feeling akin to a fun-fact I read years ago. Buried in a forum thread is a comment that reads something along these lines; I work as a paramedic. I have a lot of experience with these kinds of situations. From my experience, we have some sort of inherent sense that something is wrong. When a patient tells me they’re going to die, or they have this intense fear in their eyes — not the normal kind, but a deep, infinite kind — something bad happens very soon. Something fatal like a heart attack, for instance, strikes minutes later. The human body just knows. I can’t corroborate this fact or the anonymous tale, but its veracity is irrelevant — I entertain a faith in this phenomenon. Almost like a dog instinctively barking at a brewing tornado, I felt a compelled certainty.

Entranced in my chair, I watch the flash seep everywhere. It confirms my gut instinct. With it passed, and my brain rebooted, I recognize this as a familiar yet confusing scene: Shouldn’t there… CRASH! The off-beat thunderclap shook me.

In this tiny space, I feel, for the first time, like I was living in more than just the room I call mine. The label of ‘room’ became inappropriate. It was at this moment, from a mere open window, that I learned sensations could be so raw. Such an oceanic largeness on its other side; an immensity that demands humility. I wondered: Why have I just now noticed this?

Discomfort §

The season: Summer. The temperature: Scorching. The consequences of that heat are especially urgent on my soles. Not the entire flat of my feet, just two spots: one where my first and second toes wrap around the wire of my flip-flops, and another near my heel where the wire inserts into the sole. These particular points dig into my skin at every step. Jutting from the landscape of my East Coast campus are spurts of hills and plateaus. Unfortunately for me, Google Maps apparently demands the pain of managing uneven terrain perfectly conducive to the pricking of soles. The twists and turns in these narrow, one-way streets don’t help either.

“My god, why is Providence so damn hilly…” I can’t help but feel disadvantaged for having been raised in Chicago, the land of ‘unchanging-altitude.’

That’s the acute discomfort. Demanding my focus chronically is the humid stickiness that permeates every surface of my body. At this point, my clothing feels more like soggy paper. The household walls across the street and close to my right are high, variegated, and annoyingly bare. With no passerby in sight so far, there is no escape. I am alone in this mundane struggle. The only saving grace from the incessantly burning sun is the relief of my first in-person class. I’m not bubbly or giddy, just expectant mixed with a tinge of nervousness.

I welcome the sun’s immense and uncomfortable pressure. It’s too good of a coincidence that the heat advisory warning overlapped with this momentous occasion — already delayed by two weeks, in fact. I tend to entertain myself with my own humor nowadays. I think it’s a habit I developed who-knows-when during that swath of solitude. All-in-all, I consider the sun’s grace a harsh “welcome back.”

Inquiry §

I admire it.

My window has an audience. A picture frame of a poem gifted as an off-to-college present from my mother; a duet of flasks, one tall and skinny, the other short but wide; a metal cup with a handle, perfect for tea and water; my ivy plant, whose leaves number more than seven times the initial five it started with when I brought it to Brown. Behind the main characters of the stage — the foreground you could say — is the unsuspecting setting. Unclear glass muffled from fingerprints and residue. A pure guess, I assume that the frame is wood coated with white paint. Contrasting the aged glass is this wine-like wood: age evident but not distasteful. A grid screen sits just behind it. It stops the bugs from getting in, and me from falling out.

Most of the time the pane is lifted more than a foot above its closed position. How wonderful such a simple change has been. Shallowly, this story is about the way my window has dyed the color of my first year of college: positively. Deeply, on the other hand, is a commentary on our sheltering, which twists sanctuary into captivity. What have we isolated ourselves from?

Without §

Someone I knew once said, “I started playing chess when I was five.”

“Oh, is that why you’re so good now?”

“I’m not that good.”

“Your rating is literally 1800!”

In Freshman year of high school, I met someone who had been a gymnast since the third grade. One of my close friends had been playing piano since kindergarten. It’s a usual occurrence for these outliers to broadcast themselves on YouTube or Instagram — a knack for art paired with an intractable sum of dedication. That isn’t me.

My idols, none of which I’ve actually met, tend to have a childhood filled with something. I did not. Vacuous is how I’d describe myself. But this description is all retroactively applied. I say this now with the knowledge of a bigger world, filled with more stresses and joys alike. I picture my young environment as hollow because time didn’t really exist. My memories of a time when urgency was an undefined sensation are fond: such a stark contrast to life now. That basement and even tinier living room was my world, my detention. Existence was what was immediately in front of me: the TV.

“Today on How It’s Made, we’ll learn about how erasers first…”

“The Kid’s Next Door!…”

“But Finn, you can’t…”

Although I reimagine myself as being silent and unnoticed, it was the other way around: the world around me was unnoticed. Unnatural. That infinitesimally small space was only so because I couldn’t see something larger. I couldn’t see more of the world — physically and metaphorically. There was much, much, much more beauty to behold. So much more chaos and serendipity. So much more to appreciate and wonder and stare at. When your world is the only one you know, you can’t see anything but that.

Comfort §

DRRRING!!! DRRRRRING!!! DRRRRRRING!!!…

There are things that cannot be done when you are in a rush. Waking up is one of those things for me. Waking up is tormenting. My mind resists being rustled. Far too easily, I shove my late-night reminders behind the warming luxury of blankets.

In my struggle, a break in the clouds becomes apparent. Literally. I listened to a podcast a few months ago about how light rays, especially those that hit your eyes directly from the sun — those not refracted and scattered through a window’s glass — are essential to the wake of the body. I keep my left eye a tenth open but the right completely shut. The left one can’t even do that for much longer than a few moments before its accumulated nocturnal debris grows too troublesome — but it’s enough for me to find the outline of a certain black rectangle. I need to shake it because I use a special alarm clock app. It’s a preventative measure for a chronic over-sleeper. All that matters is that it’s been doing its job. The fact that I’m conscious enough to have this thought proves my point.

I couldn’t help but notice the unfettered rays peering through the opening. Stopped a foot above the windowsill is the bottom of my blinds. I’m reminded of my foresight last night to lower them so that my present self’s retinas wouldn’t be burned. I mentally pat myself on the back for it. I then laugh at myself for mentally giving myself a pat on the back.

At any rate, the sunlight demands my attention. It is bright but balanced by the darkness of the crevices it cannot reach on my messy table. The area is bright enough to stir yet dark enough to soothe. I’m surprised at how natural this feels — was it always like this? No, my old room didn’t even have a window in the first place. In my trance, I realize the coherency of my thoughts. I rather quickly raise my upper half from under my tempting sheets, rub both eyes with either hand, and check the time.

Unnoticed §

If your second semester in college was unexceptional, then yours wasn’t so far off from mine. Mostly monotonous weeks passed until any novelty arose at all. But only an inkling, a turning ambiance: an inappreciably small shift. I stand at a distance, across the room, far from the window. Peering through it produces in me a feeling I never knew I yearned for. Even as I type this paragraph several weeks later, I sense a radiating, motherly familiarity.

An inanimate object, this window reminds me of our fickle randomness. Unappreciated. Unmoved. Unnoticed. Our myopia dawns on me. We stumble through life, deceiving, loving, becoming learned, then sputter out within the span of a dozen tree rings. What possesses you? Is it your career? Your homework? Money? Has gasping for breath at the workday’s close become routine? Reflect on your day-to-day: has a moment ever penetrated into you as much as this window has into me?

Author’s Note §

This is a piece I wrote for a creative non-fiction class — I didn’t write it with a public audience in mind. Furthermore, this is the second piece of creative non-fiction I’ve ever produced. Take what you will from it.

Mar 5, 2022 This piece has been somewhat edited and published separately by Sole Magazine.

The “Great Books Idea” and liberal versus general education

Tue, 07 Dec 2021 18:30:00 GMT

The origins of the “great books idea” §

The Great Books of the Western World is a landmark event for the manifestation of the “great books idea,” a campaign whose ideal was a liberal education. Throughout the 1920s, 1930s, and 1940s, the great books idea went from “being an academic experiment in New York City to a national phenomenon based in Chicago” (Lacy 86). The spearheads for the movement were Robert Hutchins and Mortimer Adler, the president and chancellor of the University of Chicago, respectively. The Great Books of the Western World, edited by both Hutchins and Adler and published by the Encyclopedia Britannia, where Adler was part of the board of directors, marks when the great books idea’s burst into the public sphere. The Great Books of the Western World is a 54-volume set which compiles ‘great’ written works. The criteria for which works include but is not limited to those which have an “intellectual amplitude,” are “universally relevant and always contemporary,” are “indefinitely readable,” and “deemed indispensable… to a genuine, sound liberal education” (Lacy 269). The final criterion is what Hutchins, Adler, and the exponents for the great books idea most firmly thrust into the public eye.

What exactly is the great books idea? It is the essence of why the Great Books of the Western World found so much success and assent to intellectuals of the era. Its ideal was a universal liberal education — that every citizen be ‘intellectually rounded.’ The great books idea is an approach of what a liberal education should be. Hutchins and Adler identified a gap in liberal education, namely, it wasn’t liberal enough. Hutchins, reflecting on what the great books idea means to him, during a celebratory party for the publication of the Great Books of the Western World, described liberal education as the “education for leisure and citizenship” (Lacy 158). To them, a liberal education, is “but a means to intellectual freedom” (Lacy 158); this is the goal the Great Books of the Western World embodies. This means that thinkers were envisioning something to put into perspective any other knowledge they have — an expansive notion of history and ideas of the past, undiluted from the dispositions and transience of the present, or as Clifton Fadiman asserted, it is a means to escape “from the thralldom of the current… the curse of the contemporary” (Lacy 157).

Chicago’s mayor, Martin Kennelly, proclaimed a “Great Books Week” in September 1948; its top attraction was a public demonstration spearheaded by Adler and Hutchins. Though mostly performative, this demonstration provided an imagery of productive, healthy, organic intellectualism and dialogue the great books idea strove for:

Their discussion of Plato likely resembled the routine of Socratic questioning with which they had plagued unsuspecting University of Chicago students since the fall of 1930… They sometimes argued “moot points” for the students’ “amusement”… Of him Adler later recalled: “His lightning flash rejoinders left me speechless, astonishing those who were already his friends, but confounding others not so well disposed”… McNeill recalled Adler’s “argumentative skill” and “seriousness.” Thomas Aquinas’ “scholastic method” of posing questions and raising objections fit “Adler’s habit of mind perfectly.” (Lacy 85–86)

The ideal of liberal education §

The mission of the great books idea was to shift the attention of what the most important things to learn are. To Adler and Hutchins, the status quo in universities was characterized by vocational and professional training. They were diametrically opposed: “For college students seeking a liberal education, Hutchins, Adler, and his entire community of discourse predicted that their experience in higher education, focusing on specialization and vocationalism, would leave them unsatisfied…” (Lacy 223). The two believed that the education found through reading great books would provide a liberating feeling from the “stultifying, conformist tasks, students and laborers” (Lacy 224).

Underlying their call to a more liberal education was the aim to create a “thinking citizenry,” one which regularly regularly mulls over “liberal causes” of “education reform, world government, nuclear disarmament, free speech, and racial and economic equality” . Ultimately, Adler and Hutchins sought for a “more democratized culture, not the reification of an existing order” (Lacy 159) — they aspired to redefine our values. Though this ideal immediately applies to the university, it also applies to every member of society:

If the great books idea worked this way for [the university] cohorts, perhaps some family members experiencing repression, by way of conformity to gender and age expectations, might also escape into the great books. They could express themselves through buying and reading the great books, or participating in discussion groups. (Lacy 224)

Compare this to contemporary popular discussions of education systems. For instance, education is often framed in economic terms: institutions do not have enough funding (Zyngier). Though money is always involved in implementing educational practices, the conversation only tangentially addresses the fundamental problems of whether what funds are being allocated to is correct in the first place. This is clearly not an exhaustive description of contemporary conversation, but is indicative of how we often miss addressing the faults of the premises of our education institutions, that which everything grounded on. Similarly, concerns of imagination being ‘killed’ in our educational institutions “stifling creativity” leading to “problems in the classroom.” Students start to “act out, drift off, or shut down” (Lynch), then we propose solutions such as physical movement. In other words, presents concerns often superficial chit-chat which neglect the core question of “What should we educate on?”

In 1929, “Adler recalled that ‘reading the great books, both as a student and as a teacher, had done more for [his] mind than all the rest of the academic pursuits in which [he] had been so far engaged’” (Lacy 24). The great books ‘methodology’ is most critically founded on the prioritization of (i) facilitating conversation around “Great Ideas,” that is the “Great Conversation,” via (ii) a common corpus of texts. Return to the core aim of Adler and Hutchins to create a “thinking citizenry”: a functioning democracy requires a literate populace (Lacy 26). Thus, one had to be aware of the larger issues and concerns of society — the Great Conversation: “… a discussion of ideas by authors who, though spread across twenty-five hundred years of Western history” (Adler 252). This followed from the claim that “…ideas can be studied only in their historical context” (Adler 252). A common set of texts is vital in order to grapple with such broad and important ideas. Indeed, how can productive discourse occur without a common set of facts that are agreed upon. In the words of Adler, a common set of texts “provided ‘common intellectual themes’ for students, and prevented conversations from ‘degenerating’ into small talk.’” (Lacy 23).

The 1950s was the peak of the great books idea:

During the 1955-56 fiscal year… In 889 Canadian and American communities, 1,735 great books discussion groups existed by June 1956. By December 1961 the “world total” was 3,135 groups. Actual participants numbered around 26,000 in the mid-1950s, indicating a median steady state between 50,000 in 1947 and 17,000 in 1952. Estimates for late 1961 were 47,025. In 1956 the largest numbers of groups were in New York and Colorado (165 each), Illinois (129), and Ohio (115); the smallest in Idaho (2), Montana (3), and Vermont and Wyoming (4 each). The Foundation was based in Chicago, but its reading groups spread all over the country. (Lacy 226–27)

This speaks to the appeal the public found in the values of liberal education. Furthermore, the great books idea complicates the common intuition that education is an individualistic pursuit. Although learning occurs with the individual, the value of dialogue should not be neglected.

A case against Adler and Hutchins §

Although there substantial momentum around the great books idea and its values of liberal education in the 50s, the 60s and particularly the 70s marked its nadir. The great books idea is promising: an ideal for the intellectual optimum of every citizen, found in participating in the “great conversation.” It seemed to be a panacea. The “encyclopedia businesses” of the early 1950s are an ostensive signal that for the growing belief that, in a world becoming more and more complex, “Buying the great books, or encyclopedias, secured your child’s place in America’s middle class” (Lacy 221); in reading the great books of the past all can cut passed the bombardment of information that was coming with mass media such as television. But it is problematic: the ideal hinges on the student being a reader. What happens if one isn’t?

Let’s return to the our common intuition that education is a pursuit for the individual. Why is that? There certainly is a kernel of truth: information and wisdom are held within books, but that is only useful for facilitating growth; the growth only occurs once the individual has taken the steps to utilize that resource. Mere reading is not enough; reading is not intrinsically useful. Reading can be good or bad, it is up to the individual to get take the effort and time to make use of what a book has to offer. It is indisputable that there is effective and ineffective reading. That is, there will always be members of the public who do not like or want to read, and will therefore get less out of out of a book compared to inherent readers. Compare the software engineer who sees the smartphone as a miracle of human ingenuity and the layperson who only sees convenience. This observation complicates the proposition of universitization liberal education: how can a pedagogical philosophy possibly be suitable for a population which arguably is unreceptive to deeply reading the classics of Western society?

Beneath the exciting and grand promise of liberal education is the suspicious presupposition that a liberal education is the best general education. A liberal education is one with “considered to be subject centered, with a fairly fixed body of content material, logically organized. Its goal is also the stimulation of reflective thinking, with less emphasis on behavior, and it draws its clientele from the intellectual elite.” In contrast, a general education is one designed to “fit all students — not just the upper ten percent… liberal education as often defined and practiced, will not fit all students” (Zayed 42).

And Alder and Hutchins did indeed envision this as an ideal for the public. For instance, in their talks for a promotional movie in 1954, Adler and Hutchins wanted to market the movie as a ‘family-friendly’, relaxing venture, “Benton directed Adler to ‘imagine that the movie is to be shown in a home to small group of people… make it as intimate and friendly and relaxed as possible.’ Benton reminded him: ‘You are not lecturing; you are teaching.’ Adler and Hutchins heeded Benton’s input” (Lacy 234). Thus, ironically, although the great books idea argues that liberal education is the path to being the ideal citizen, the ideal is inherently exclusionary. For instance, what the general public should read is likely different from what a reader already receptive to reading should read.

This is more than theoretical. The great books idea only became a cultural phenomenon after coming from a plea originating from the “planes of high culture” (Lacy 159), “The Great Books came to be a form of mass culture, subject to the concerns of business: sales, marketing, production, profits, standardization, and efficiency. Once the great books idea took a fixed form, critics targeted it as the commodification of culture” (Lacy 159). The movement, however, never quite grew out of this population. The 1962 Marplan-Chicago Great Books Awareness study analyzed the market of the Great Books of the Western World and concluded the following:

A typical great books owner’s social and personal profile in 1962, according to Marplan, began with the fact that they were “upper middle class.” They filled occupations “structured and governed by definite rules, such as medicine, engineering, accounting, and middle management jobs.” Because of their “high intelligence,” however, they correctly perceived “their lack of knowledge in the philosophical and liberal arts fields.” The Great Books and the Syntopicon enabled them to remedy their knowledge deficit without forcing them to “contemplate ambiguities” or determine the “appropriateness of… vague ideas.” The set offered them “satisfaction” in that they could find “the answer to questions.” Owners were “action” driven people who liked to accomplish “something,” or “complet[e] a task with perceivable results.” In sum, “the Great books appeal to the core culture [of] individuals who strive to function efficiently and within the outlines of what is proper and correct.” So long as America’s larger culture retained this tendency, centering on order and propriety, then the great books idea would maintain its appeal. (Lacy 256–57)

Despite the aspirations for a ‘responsible citizen’, a goal directly broadly, the ones who took up the mantle of the great books idea were those already predisposed to doing so already. In other words, the great books idea remained localized to a self-selecting populous. The actions of Adler himself during the great books idea’s nadir shows that, despite his words, his audience was not the common man, “Adler had been involved in Aspen seminars, which utilized a great-books approach to learning, regularly since the 1950s, but the seminars were aimed at business and government executives: the elite” (Lacy 264).

To Adler, “the great books should be read ‘to deepen and broaden our intelligence and imagination, not to acquire up-to-date information’” (Lacy 244). At the heart of the great books idea is the universal imposition of a value, namely of reading the greats as the best path for self-improvement and ideal citizenship, that the “most satisfactory byproduct of reading the Great Books was that you ended up “a much more satisfactory companion to yourself” (Lacy 240). The great books idea is alluring solution to a definite problem but with too broad a scope. The great books idea, and by extension liberal education, is not a pedagogical panacea; it is more suitable as a personal goal — for one’s personal education, not as a standard.

Author’s note §

This a paper I wrote for one of my classes. It is in an incomplete state but I put a lot of work into it and think that someone might enjoy taking a peek at it.

Adler, Mortimer Jerome. Philosopher at Large: An Intellectual Autobiography. Macmillan, 1977.

Lacy, Tim. Making a Democratic Culture: The Great Books Idea, Mortimer J. Adler, and Twentieth-Century America. 2006, https://www.proquest.com/dissertations-theses/making-democratic-culture-great-books-idea/docview/305319330/se-2?accountid=9758. Ann Arbor.

Lynch, Matthew. “Is Education Killing Imagination?” The Edvocate, 5 Sep. 2016, https://www.theedadvocate.org/is-education-killing-imagination/.

Zayed, Kevin. “The Paradox of Mortimer J. Adler: Revisiting the Distinction between Liberal and General Education.” 2013.

Zyngier, David. “Test Shock: Is Our Education System Failing Students?” The Conversation, http://theconversation.com/test-shock-is-our-education-system-failing-students-11308. Accessed 30 Nov. 2021.

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

Mon, 21 Feb 2022 21:46:00 GMT

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

Synopsis §

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

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

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

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

Marginalia §

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

Using helpful-variable

Using find-file

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

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

All-the-icons-completion §

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

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

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

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

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

Vertico §

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

Basic §

This is a very basic Vertico configuration.

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

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

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

Extensions §

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

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

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

buffer — minibuffer treated as a normal, separate buffer,

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

Vertico-flat minibuffer UI
grid — a grid format,

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

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

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

Vertico-indexed UI

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

(vertico-multiform-mode)

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

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

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

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

These are rarely used, but can be handy.

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

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

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

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

Vertico extension commands §

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

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

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

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

Niceties §

Finally, I add a few niceties.

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

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

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

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

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

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

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

End product §

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

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

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

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

Orderless §

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

Basic §

To use orderless you simply need the following.

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

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

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

Style dispatchers §

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

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

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

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

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

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

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

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

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

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

End product §

The end result is this^[4]:

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

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

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

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

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

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

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

Changelog §

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

Corfu, Kind-icon, and Corfu-doc

Sun, 27 Feb 2022 06:56:00 GMT

Synopsis
Corfu
Kind-icon
Corfu-doc
Changelog

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

Synopsis §

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

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

Corfu §

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

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

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

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

Basic §

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

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

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

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

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

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

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

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

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

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

Working with the recent changes to `corfu` §

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

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

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

Further configuration in minibuffers and with `lsp` §

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

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

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

Using corfu in the minibuffer prompt for eval-expression.

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

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

End product §

Putting it together, we end with my actual configuration:

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

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

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

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

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

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

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

Kind-icon §

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

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

The following is my configuration:

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

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

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

Corfu-doc §

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

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

Here is a sample configuration^[4]:

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

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

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

Changelog §

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

Cape

Sun, 13 Mar 2022 07:02:00 GMT

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

What is `cape`? §

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

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

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

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

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

Basic usage: keybinds §

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

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

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

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

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

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

I then add this to the appropriate hook:

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

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

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

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

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

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

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

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

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

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

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

`pcomplete` nicety §

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

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

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

My `completion-at-point-functions` §

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

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

Here they are

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

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

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

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

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

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

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

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


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

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

Changelog §

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

True Emacs Transparency

Tue, 07 Jun 2022 15:00:00 GMT

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

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

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

alpha-background set to 75.

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

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

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

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

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

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

In practice, this is what toggling transparency looks like:

Live-toggling of the alpha-background parameter.

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

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

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

Changelog §

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

Citations in org-mode: Org-cite and Citar

Tue, 14 Jun 2022 23:52:00 GMT

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

Summary §

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

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

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

Helpful sources §

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

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

What are citation systems? §

There are roughly three moving parts to citation management.

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

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

Org-cite §

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

Understanding `org-cite` export processors §

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

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

(BACK-END . PROCESSOR)

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

(NAME BIBLIOGRAPHY-STYLE CITATION-STYLE)

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

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

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

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

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

In sum:

Which processor should I use? §

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

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

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

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

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

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

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

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

Configuration §

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

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

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

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

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

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

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

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

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

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

Usage §

Using org-cite is incredibly simple:

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

Citar §

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

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

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

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

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

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

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

Capturing (Outdated) §

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Aesthetics §

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

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

Here’s the end-result:

Visual improvements to citar’s minibuffer interface.

Other interesting packages §

Zotero §

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

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

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

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

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

Embark §

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

Org-roam-bibtex §

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

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

Citar-capf §

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

Org-ref §

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

Changelog §

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

Knowledge: A Very Short Introduction by Jennifer Nagel

Tue, 03 Jan 2023 05:14:00 GMT

Knowledge: A Very Short Introduction by Jennifer Nagel (2014) ^[1] is a phenomenal introduction to epistemology. Spanning a little over 100 pages, one would not expect an in-depth overview of the field. Indeed, Nagel does not bog down the reader with terms nor the intricacies epistemologists would be interested in—but the ideas often linger in the air for the reader to dwell on, and Nagel doesn’t fall short in teasing the magnitude of what hasn’t been explained. Unequivocal, the pace of the book is digestible yet the book demands the reader stay on their toes—each paragraph is productive.

Nagel is incredibly accessible and engaging. He does an outstanding job (i) using demonstrative examples accessible to the layperson, (ii) inserting examples that probe the inquiry, (iii) and treating each topic evenhandedly, not privileging one view over another (at least, from the perspective of a novice reader). Consequently, the reader feels naturally propelled from one inquiry to another. This is another strength of Nagel: the book is inquiry-driven, that is, grounded by the common sense questions that follow an exposition. He slithers through the touchstone topics of epistemology with ease: skepticism, rationalism and empiricism, internalism and externalism.

Of course, such brevity can only be achieved by omitting a lot of what would otherwise be interesting to the reader. Nagel doesn’t present even approximations of a “final answer;” there are only open questions here. But, the book fulfills the role readers would expect it to fill: it enticingly introduces subtopics within epistemology that invites curiosity.

Think: A compelling introduction to philosophy by Simon Blackburn

Tue, 10 Jan 2023 22:10:00 GMT

I first encountered a mention of Simon Blackburn’s 1999 Think: A compelling introduction to philosophy when I was looking for a good introductory book to philosophy. At the time, I was a Senior in high school not having read an once of philosophy. The hope was for something broad yet with an appreciation for nuance. It didn’t take long for me to discover Think, one of the few books r/philosophy recommends as a general introduction.

We may indeed hope that it survives in the seas of thought I have tried to stir up this chapter. (269)

Found at the end of one of the later chapters, Blackburn’s style of teaching can be summed up in the above. Blackburn dares to stir, complicate, and entangle philosophical ideas in an introduction to philosophy—but not carelessly. Blackburn is extremely cautious (and successful) at straddling the line between writing that is intimidating, burdensome, or vexing to the novice and writing that is tantalizing and invites curiosity. His writing is not technical but manages to respect the necessary nuances of exploring the landscape of philosophy. For instance, in the span of about ten pages (namely 200–210), Blackburn covers formal logic and its interactions with language (i.e. pragmatics and semantics). Having been a topic I later learned about across several months in university, I recognized the sheer land that Blackburn was covering. This is one of many nuggets of gold that the novice may recognize but will only appreciate as they learn more about philosophy. Blackburn presents connections only an experienced philosopher could make, making the book useful even to someone somewhat studied. In sum, Blackburn exposes nuance without technical burden.

Furthermore, the bountiful beginner-friendly working examples and analogies are in the best interest of the novice philosopher. Blackburn captures an analogy with a clarity of mind to point to a fishiness or suspicion the reader readily picks up on. The points he makes are expectedly down-to-Earth and digestible and have the dual purposes of exposition and highlighting implications that drive the inquiry forward. And he returns to many analogies throughout, extending them hundreds of pages later. He uses his examples more like “intellectual toys,” twisting them until they break and make way for further progression. This all contributes to an interconnected conceptual map for the reader. At the very least, he is effective at familiarizing the reader with philosophical ideas.

But Think is not a survey, organized by author or period. Though the book is not historically propelled, it is historical in the sense that Blackburn sits as a judge like a historian, only caring about an idea insofar as it bears relevance and import. The reader who picks up Think is in the business of fostering their curiosity, and Blackburn’s inquiry-driven tour caters to precisely this audience. Blackburn captures the common sense objections at the tip of the layperson’s tongue into deftly formulated argument or suspicion that motivates the reader to flip to the next stage of the journey. Time and time again a chain of relationships like this develops: “X idea was a natural offshoot of the shortcomings of Y idea that came before or existed with X.” This is a demonstration of Blackburn’s philosophical and pedagogical expertise. Organized by questions, Blackburn is indifferent to chronology and author; they only influence his decisions insofar as they are relevant to the progression of ideas. He transitions smoothly between sections and chapters as if the topics were meant to be placed in that order; descriptions of Hume’s problem of induction (Hume was writing in the 1700s) are adjacent to descriptions of Frege’s proto-quantificational logic (the turn of the nineteenth century). Recognizing conceptual continuities is a boon for any student trying to organically yet thoroughly learn any field. Though this necessarily blurs conceptually (e.g. logic to Bayesian statistics in 211–24), it serves the more important purpose of familiarizing and guiding. Indeed, it is compelling.

Finally, Blackburn does not fear making his philosophical preferences apparent. Some may disagree with his choice to openly state his ultimate positions to the learning reader, but a philosopher will necessarily hold preferences, so an author that comes off as impartial is merely feigning. Take the last chapter. Blackburn declaratively rebukes psychological egoism, and his rebuke is the entry point to the rest of the chapter. Importantly, this does not render the book dogmatic or one-sided. Because Blackburn does not bury his intent, the reader is aware of where they are being pulled to and is therefore armed to push back. Overall, I found Blackburn mindful of the novice’s concerns yet respectful to the depths of the topics.

When the Noise Falls Away

Sun, 29 Jan 2023 07:56:00 GMT

I found my room remarkably quiet. I returned passed sunset, yet my suitemates hadn’t arrive at our dorm yet. I swung my room’s door open and… nothing. Nothing grand, not that I was expecting anything. The emptiness was just what struck me. How empty the room felt. My pre-move cleaning is responsible—I was happy with that. But the room no longer wears the mantle it does when things are amiss and the semester is bustling. It’s just a room. It doesn’t radiate companionship like a humble abode would.

I sit and contemplate my trip, and realize something crucial. There comes with traveling—traveling alone, that is—an intense interior awareness. A mental state characterized by the feeling of “no one else is the room but me.” By “room” I mean my mental space. School assignments, social pressures, household responsibilities, music, videos, friends… these all normally clutter the mind, forms of interrupting noise vying for space. All layers of stimuli that demand attention, distract. From what? From the Self experiencing. The static noise of everyday experience shrouds the Self, the only constant. Traveling is like a nice, warm shower in that it disarms the defensive walls we instinctively erect around our internal reality. Without mental cruft to lure, the only option left is for the Self to turn inward and confront your internal shadow, secrets and all. Traveling renders me barren, leaving my mind to confront itself.

You only get such an interiority in early mornings, warm showers, withdrawn travel, and the quietude of an empty dorm room. Don’t underestimate what’s left when you deprive yourself of external stimuli. Those moments show a wholly clear tint of reality.

Something I once heard comes to mind. Entertain the time period when lovers didn’t have the ability to see one another once parted. This was the world before it was connected, before trains, cars, and phones. How much would that affect the intensity of your emotions? Wouldn’t that transform moments between you? Might love have a truly different taste?

Neat behavior of M-x occur

Sat, 09 Nov 2024 06:00:00 GMT

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

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

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

It is bound to M-s o.

(occur REGEXP &optional NLINES REGION)

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

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

[…]

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

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

[…]

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

[…]

So:

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

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

Pretty neat!

A surprising upside to vc-dir marks over magit

Wed, 27 Nov 2024 04:40:00 GMT

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

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

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

The nicety of `vc-dir` marks §

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

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

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

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

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

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

A caveat §

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

Changelog §

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

Org-review: A way to never forget org-agenda todos

Sat, 22 Mar 2025 19:40:00 GMT

The ideal: Separating “now” and “very soon” from everything else
“Later”
“Unsure when”
“Never”
1: Occlusion
2: Prioritization
3: Reviewing
- Two org-agenda views
- Org-review: Immediately identify which tasks need addressing
The ideal: Separating “now” and “very soon” from everything else
“Later”
“Unsure when”
“Never”
1: Occlusion
2: Prioritization
3: Reviewing
- Two org-agenda views
- Org-review: Immediately identify which tasks need addressing
Bonus: bespoke org-agenda scatter function

In the last few months I’ve revamped my org-agenda workflow to a state I’ve never been more satisfied with. I’ll share here how org-review^[1] made it possible.

The ideal: Separating “now” and “very soon” from everything else §

In my view, the primary purpose of a “task management” is system is to show you only the tasks you need to be shown, while hiding the rest until it becomes urgent to do them, their importance to other tasks rise, or you simply feel like doing them now. As such, we should distinguish tasks which are relevant to “now” and “very soon” from everything else: “later,” “never,” and “unsure when.”

I’d bet (i) is a familiar and intuitive ideal for most Emacs users since we tend to be the type to think about the workflows/systems we use and how we might reshape them to suit our needs better. An org-agenda without (i) is like a workflow where one simply calls M-x org-agenda t (“List of all todo entries”). It’ll be obvious to those who have hundreds or even thousands of todos how seeing a gigantic running list of all your tasks doesn’t help. We need to fulfill (i) because, otherwise, the looking at your todo list to decide what task you need to do now becomes a task in itself—and that means we expend time and energy figuring out what to do rather than doing what needs to be done.

”Later" §

"Unsure when" §

"Never” §

1: Occlusion §

As such, an ideal org-agenda means (i) occluding (hiding) or separating tasks non-relevant to the present.

There are two common straightforward ways to fulfill (i):

Having an “inbox.” An inbox separates tasks which one has already committed to from ones they haven’t yet committed to.
Add scheduling and deadline information to tasks and occlude (hide) them until they approach. This is to delay visibility of tasks until a date more appropriate to attending to that task.^[2]

I have used and continue to use both strategies to occlude tasks.

2: Prioritization §

However, those two strategies are not enough. Even with an inbox and hiding tasks until their scheduled/deadline date approaches, I still had dozens (at least) of todos simultaneously visible in my org-agenda views. I committed to these tasks, but there was a problem: although I committed to all these tasks, when considering factors such as urgency, life-priorities, mood, and time available, only a small portion of these tasks were ones I should be worked on now. The rest were ones that I could worry about later, whether next week, two weeks from now, a month from now, or some ambiguous, yet-to-be-determined point in the future.

This suggested another pillar for my org-agenda: *(ii) the ability to discern

Consequently, I naturally moved to crafting an org-agenda practice reliant on org-agenda’s built-in priorities and effort estimates. I had previously used priorities and time efforts sporadically, but

My previous org-agenda set up tried to cut down the number of non-inbox todos by abusing the scheduling functionality of org. The functionality of deadlines remained as intended, but I re-tooled scheduling in an atypical way: a task’s scheduled date was the date I wanted to see that task again. In my org-agenda views, the tasks meant for “now” were the ones whose scheduled date was today or in the past. There was flexibility in the method, since I could also use the scheduled date as simply a date I wanted to check back in with a todo, deciding whether I should move it to the inbox, do it now, or defer it again. (Of course, abusing scheduling like this meant there was no longer an equivalent to the typical schedule-deadline difference.)

Effectively, this was a way to snooze^[3] tasks until later—that is, I would defer tasks, which is a temporal way to occlude todos. I ended up sticking with this workflow for over a year.

But over time, I discovered a significant issue. I realized that (i) wasn’t enough: there was no way to tell how long a todo sat in my agenda, waiting for me to attend to it. As such, although I could hide a task for another day, once it became visible and I was actively working on it, if I forgot about the task or de-prioritized it, there was nothing in the system that would tell me that too much time had passed since I was last productive on that task. Consequently, there were many todos that fell through my workflow because I started work on them, did not complete them, and the time I should’ve had it completed by had passed. (Strictly speaking, one could use deadlines for this purpose, but I never could find a way for such deadlined todos to be prominent nor distinguished from other deadlines used in the typical “this is an actual deadline” way.)

Therefore, in addition to (i), there is (ii): visible (non-occluded) tasks should have a way of indicating to me that they should be checked on.

In sum, there should be a way to occlude tasks (i.e., make a todo visible until a specified date)—this is (i)---while also indicating a certain date when my future self should be concerned it is not yet completed (i.e., specify another date for reviewing a todo) whether to re-defer it, to move it the inbox, or to start working on again—this is (ii).

3: Reviewing §

Two org-agenda views §

Retaining (i) while achieving (ii) is what I have made perfect use of org-review for. My current org-agenda is much more effective and simpler, not requiring a re-conceptualization of org’s scheduling functionality.

Currently, I have (in outline) two org agenda views.

One org-agenda view for tasks whose scheduled or deadline date is today (or in the past) and other tasks (non-schedule, non-deadline) that I’m either working on now or will work on soon—the urgency and priority of these tasks are determined using org priorities and effort estimates, although it’s ultimately up to me what I choose to work on any given day.^[4] This is my main, “time to be productive” org-agenda view.
The other org agenda view shows my “inbox” and “to-review tasks”---this is where org-review comes in. A task tagged with “inbox” is in the inbox org-agenda block until I call org-review-insert-next-review on it, selecting the date on which this task will reappear as a task to review.^[5] (Alternatively, I can just remove the inbox tag and this task will appear in my first agenda view: it is a task that I am working on now or will work on soon. In these cases, I also call org-review-insert-next-review, or org-review-insert-last-review which automatically sets the NEXT_REVIEW property value if org-review-sets-next-date is non-nil. I explain why later.) In this same agenda view, I have another org-agenda block for tasks whose NEXT_REVIEW date is today or in the past.^[6] It is here that I decide what to do with a task. Do I move it to my main, first agenda view by removing the inbox tag? Do I call org-review-insert-next-review again to re-defer it? Or do I remove its NEXT_REVIEW property because I’m no longer sure whether or when this task should be deferred to.

Org-review: Immediately identify which tasks need addressing §

These two views, however, are not uniquely made possible by org-review. In fact, I had very similar views when I used scheduling instead of org-review’s org-review-insert-next-review: instead of filtering by the date in the NEXT_REVIEW property, I would filter by the scheduled date. (Although, of course, using NEXT_REVIEW instead of scheduling allows actually scheduled tasks to always appear in my main agenda view, which is a plus.) The benefit unique to org-review is my usage of the NEXT_REVIEW property in tasks that are also in my main agenda view. That is, with org-review, I can set a date in which tasks I’ve set out to do “now or soon” can be reviewed (without using schedules or deadlines, which would remove the possibility of using schedules or deadlines for other purposes). I do this with another org-agenda block in that agenda view, showing tasks that aren’t in the inbox and whose NEXT_REVIEW date is today or passed.

This solves the issue of (ii), that tasks need to be done soon otherwise too many pile up and either require long sessions of reviewing todos or important or urgent todos to pass by with you realizing (tk is this the essence of it?). The tasks in the to-review agenda block in my main view are those which my past-self determined should be checked on (put back on the inbox, re-prioritized, cancelled, etc.) by now. So, when I fall behind in work, I can review the tasks in the to-review block and not worry about having important or urgent tasks slip by me—the non-schedule, non-deadline tasks in this view but not in that block are ones that aren’t in-need of review now, and thus are fine not having been done already.

There are many more details to how I use org-agenda, but I hope this write-up explains my usage of org-review in a way that might’ve shown you a way to use the package you haven’t already thought of.

In the last few months I’ve revamped my org-agenda workflow to a state I’ve never been more satisfied with. I’ll share here how org-review^[1] made it possible.

The ideal: Separating “now” and “very soon” from everything else §

”Later" §

"Unsure when" §

"Never” §

1: Occlusion §

As such, an ideal org-agenda means (i) occluding (hiding) or separating tasks non-relevant to the present.

There are two common straightforward ways to fulfill (i):

Having an “inbox.” An inbox separates tasks which one has already committed to from ones they haven’t yet committed to.
Add scheduling and deadline information to tasks and occlude (hide) them until they approach. This is to delay visibility of tasks until a date more appropriate to attending to that task.^[2]

I have used and continue to use both strategies to occlude tasks.

2: Prioritization §

This suggested another pillar for my org-agenda: *(ii) the ability to discern

Effectively, this was a way to snooze^[3] tasks until later—that is, I would defer tasks, which is a temporal way to occlude todos. I ended up sticking with this workflow for over a year.

Therefore, in addition to (i), there is (ii): visible (non-occluded) tasks should have a way of indicating to me that they should be checked on.

3: Reviewing §

Two org-agenda views §

Currently, I have (in outline) two org agenda views.

One org-agenda view for tasks whose scheduled or deadline date is today (or in the past) and other tasks (non-schedule, non-deadline) that I’m either working on now or will work on soon—the urgency and priority of these tasks are determined using org priorities and effort estimates, although it’s ultimately up to me what I choose to work on any given day.^[4] This is my main, “time to be productive” org-agenda view.
The other org agenda view shows my “inbox” and “to-review tasks”---this is where org-review comes in. A task tagged with “inbox” is in the inbox org-agenda block until I call org-review-insert-next-review on it, selecting the date on which this task will reappear as a task to review.^[5] (Alternatively, I can just remove the inbox tag and this task will appear in my first agenda view: it is a task that I am working on now or will work on soon. In these cases, I also call org-review-insert-next-review, or org-review-insert-last-review which automatically sets the NEXT_REVIEW property value if org-review-sets-next-date is non-nil. I explain why later.) In this same agenda view, I have another org-agenda block for tasks whose NEXT_REVIEW date is today or in the past.^[6] It is here that I decide what to do with a task. Do I move it to my main, first agenda view by removing the inbox tag? Do I call org-review-insert-next-review again to re-defer it? Or do I remove its NEXT_REVIEW property because I’m no longer sure whether or when this task should be deferred to.

Org-review: Immediately identify which tasks need addressing §

Bonus: bespoke org-agenda scatter function §

go over my krisb-org-review-randomize

for when a lot of todos happen; I mark ones I know I want to put off sometime in the far-ish future (e.g. 1–2 months), but don’t want them appearing on the same day (manually adding offsets is a mental burden and unreliable at solving the “too much on one day” problem anyway). Around that time, or sometime before or after that is undetermined.

Zettelkasten: Memorization and Inspiration through Traversal and Surprise

Wed, 26 Mar 2025 16:27:00 GMT

Jujutsu (jj) VCS workflows and the convenience of its “operation log”

Thu, 27 Mar 2025 08:35:00 GMT

Over the last month or two I’ve been trying out the relatively new jujutsu version control system (VCS) — and loving it. At first, I discovered it and read their GitHub README with curiosity but skepticism. Then I sought a few YouTube videos^[1] demonstrating jj in action, and a tutorial for a text-based reference. I became very interested. I initialized a jj repo in one of my small git projects and played around. Since then, I’ve migrated all of my personal repositories to jj, and use jj for practically everything.

From the time I’ve spent with jj, I’ve felt myself sliding into some general workflows:

A jj squash workflow
In git, this would be a workflow where you make a commit and continually amend/extend that commit until its intended goal is completed.
1. Make progress toward a desired goal.
2. Commit (jj commit, or jj new then jj describe -m "...") with a message describing this unit of work.
3. Continue making changes.
4. Squash (perhaps interactively: jj squash -i^[2]) new changes until the desired goal is accomplished.
5. Maybe change the description of the previous commit commit.
Work in the working copy
1. Envision a goal for a new commit. Express that into the description of the working copy commit: jj describe -m "...".
2. Work until much of that goal is met.
3. jj new to work on the next goal. Or jj split -i if some of the changes in the working copy belong in the next commit.
4. jj edit to hop between commits and work on each until completion. Perhaps jj new -A ... one or more times when when you don’t want certain changes in a commit: make changes across however many of those commits, then jj squash them all into your original commit when you’re happy. (You’re basically creating a new git branch!)
Concurrent commits workflow
Work on several commits simultaneously, using combinations of jj squash, jj new, and jj rebase to make make reversible changes while having a clean jj log at the end. In essence, this is point (3.4) above but with room for added complexity.

I’m not a VCS expert, and my projects are small, but I’ve gravitated to (1) and (2) without feeling any mental strain of keeping track of where this and that change is and what CLI operations avoid x problem or y merging conflict (which, by the way, jj permits! Jujutsu treats conflicts as first-class, so conflicts and their resolutions percolate through ancestors and descendants without problem.)^[3]

Perhaps the most exciting part of using jj is fearlessly making changes and experimenting. This has been an extraordinary boon for my learning about how to use jj in accordance to its VCS concepts. The reason is jj’s operation log (jj op log) and the ability to revert back to any past repository state (jj op restore OPERATION_ID).

With jj op restore, I can merge branches, create conflicts, resolve conflicts, mess up… then go back as if it never happened. I can make sweeping repository changes without fear! In git, I’d be walking on egg shells, worried about the potential to ruin the entire state of my local repository if I’m not careful…

I’d definitely recommend trying jj out if you haven’t already! Easily turn a git repo into a jj repo with a git backend: jj git init \-\-colocate.

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

Sat, 05 Apr 2025 14:23:00 GMT

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Changelog §

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

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

Mon, 21 Apr 2025 00:34:00 GMT

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

It establishes conventions for keeping files created from packages:

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

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

Here’s a look at my own directories.

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

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

3 directories, 2 files

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

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

60 directories, 22 files

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

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

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

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

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

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

(no-littering-theme-backups)

Theme locations where backups of various sorts are created.

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

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

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

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

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

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

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

Some Notes Setting Up Syncthing in NixOS

Mon, 05 May 2025 03:19:00 GMT

The configuration
Devices
Folders
Closing remarks
Other resources
Changelog

So I recently got around to trying out NixOS. Part of that experience was setting up Syncthing, which I’ve used on the past on my machines and mobile phone to sync files related to note-taking.^[1] It was a bit confusing since I had to fill-in-the-blanks for a few steps. Here, I write about a bit of the blanks I had to fill in myself, stuff that was not clear from the existing docs and forum posts I discovered.

The configuration §

Below is the final NixOS configuration I have (with IDs elided for privacy) alongside commentary via comments:

systemd.services.syncthing.environment.STNODEFAULTFOLDER = "true"; # Don't create default ~/Sync folder.  See https://wiki.nixos.org/wiki/Syncthing
services.syncthing = {
  enable = true;
  openDefaultPorts = true;
  # I change the address SyncThing uses (which is also how you access the
  # browser UI).  This is to avoid conflicts with the other SyncThing instances
  # I have on the same machine.  Namely, from different WSL2 instances.
  guiAddress = "127.0.0.1:8385";
  user = "krisbalintona";
  group = "users";
  configDir = "/home/krisbalintona/.config/syncthing";
  # Override all settings set from the GUI.  This is necessary if I don't want
  # to have changes made from the GUI apply.
  overrideDevices = true;
  overrideFolders = true;
  # Settings: this is where you set up devices and folders
  settings = {
    devices = {
      "G14 2024 Arch" = {       # Name of SyncThing instance on other machine
        id = "OQHSZRL-L2TT7IC-7USSLNU-ST7JYML-FOO-BAR"; # Elided for privacy
      };
      "OnePlus 7 Pro" = {       # Name of SyncThing instance on mobile device
        id = "OVGYOBT-JPFQJKE-6CKRY7J-JULRCWK-FOO-BAR"; # Elided for privacy
      };
    };

    folders = {
      "k4vqh-foo" = {           # The ID of a folder you'd like to sync
        label = "Agenda";       # Optional device-specific folder name
        path = "/home/krisbalintona/Documents/org-database/agenda/";
        # Share with these devices
        devices = [
          "G14 2024 Arch WSL2"
          "OnePlus 7 Pro"
        ];
      };
      "qtuzy-foo" = {           # The ID of a folder you'd like to sync
        label = "Notes";        # Optional device-specific folder name
        path = "/home/krisbalintona/Documents/org-database/notes";
        # Share with these devices
        devices = [
          "G14 2024 Arch"
          "OnePlus 7 Pro"
        ];
      };
    };
  };
};

It was pretty straightforward to figure out the general settings for Syncthing by referencing NixOS Search. The tricky part was the “devices” and “folders” section. What should I put there? Below are the important bits.

Devices §

“Devices” are Machines/devices you’d like Syncthing to be aware of.
Each machine has an ID.
Each machine can optionally have a “label” (probably a human-readable name, like “Home computer”).

Looking at the relevant portion of my configuration:

devices = {
  "G14 2024 Arch" = {  # Name of SyncThing instance on other machine
    id = "OQHSZRL-L2TT7IC-7USSLNU-ST7JYML-FOO-BAR"; # Elided for privacy
  };
  "OnePlus 7 Pro" = {       # Name of SyncThing instance on mobile device
    id = "OVGYOBT-JPFQJKE-6CKRY7J-JULRCWK-FOO-BAR"; # Elided for privacy
  };
};

This tells Syncthing that I have two devices:

One labeled “G14 2024 Arch” with an ID of "OQHSZRL-L2TT7IC-7USSLNU-ST7JYML-FOO-BAR".
Another labeled “OnePlus 7 Pro” with an ID of "OVGYOBT-JPFQJKE-6CKRY7J-JULRCWK-FOO-BAR".

Now that Syncthing is aware of these devices, I can reference them by their label later in the folders section to specify which folders should be shared to which devices.

Folders §

Folders are the directories you’d like Syncthing to be aware of.
Each folder has an ID.^[2]
Each folder may optionally have a label (probably a human-readable name, like “Agenda”). This is basically a nickname you give to the folder specific to the current device.
Folders are only shared to devices specified for each folder.

Looking at the relevant portion of my configuration:

folders = {
  "k4vqh-foo" = {               # The ID of a folder you'd like to sync
    label = "Agenda";           # Optional device-specific folder name
    path = "/home/krisbalintona/Documents/org-database/agenda/";
    # Share with these devices
    devices = [
      "G14 2024 Arch WSL2"
      "OnePlus 7 Pro"
    ];
  };
  "qtuzy-foo" = {               # The ID of a folder you'd like to sync
    label = "Notes";            # Optional device-specific folder name
    path = "/home/krisbalintona/Documents/org-database/notes";
    # Share with these devices
    devices = [
      "G14 2024 Arch"
      "OnePlus 7 Pro"
    ];
  };
};

This tells Syncthing that I want to share two folders:

Share folder "k4vqh-foo", whose label is “Agenda,” with two devices: the one labeled “G14 2024 Arch WSL2” and another labeled “OnePlus 7 Pro.”
Share folder "qtuzy-foo", whose label is “Notes,” with two devices: the one labeled “G14 2024 Arch WSL2” and another labeled “OnePlus 7 Pro.”

It is important that the “devices” section be specified, otherwise Syncthing will not sync those folders to other devices.

Closing remarks §

And with that, I was done!

In sum:

Devices
- “Devices” are Machines/devices you’d like Syncthing to be aware of.
- Each machine has an ID.
- Each machine can optionally have a “label” (probably a human-readable name, like “Home computer”).
Folders
- Folders are the directories you’d like Syncthing to be aware of.
- Each folder has an ID.
- Each folder may optionally have a label (probably a human-readable name, like “Agenda”). This is basically a nickname you give to the folder specific to the current device.
- Folders are only shared to devices specified for each folder.

Simple, but it wasn’t obvious from the resources I encountered online, so I had to do some tinkering to figure it out myself.

For those who heavily customize Syncthing, there are other NixOS options available to tweak. You can find them in the NixOS Search for options. Additionally, if you are trying to migrate an existing Syncthing configuration to Nix, then you can check out your config file at ~/.config/syncthing/config.xml.^[3] With this, you can see the value of every Syncthing setting (although the file will, of course, be in JSON format).

Other resources §

Syncthing - NixOS Wiki: General resource; good starting point.
Vimjoyer - YouTube: A fantastic visual resource of making full use of Nix and NixOS. Has some beginner-friendly videos, but most videos are for intermediate or advanced users, ones looking to explore the ecosystem, full potential of Nix, and already having a familiarity with navigating Nix.

Changelog §

May 17, 2025
- Add link to the Syncthing configuration file documentation.

Surprisingly, Emacs on Android is pretty good

Thu, 29 May 2025 19:38:00 GMT

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

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

The good and bad: what to expect on Android §

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

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

So, really, the situation is pretty good!

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

Installation §

Option 1 §

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

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

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

Option 2 (recommended) §

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

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

In short,

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

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

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

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

Configuring an Android-specific Emacs §

Necessary reading: the manual §

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

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

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

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

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

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

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

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

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

First step: A Better UI for touchscreens §

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

modifier-bar-mode
tool-bar-mode

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

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

Android-specific Commands and Options §

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

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

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

Use a Special virtual keyboard §

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

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

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

Fonts §

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

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

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

Tip: You can remap the volume buttons §

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

Conclusion §

In conclusion,

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

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

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

Bonus: My wish list §

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

Kristoffer Balintona — Articles

Basic journals and logs with org-node

Table of Contents

The dilemma §

Final result §

Final words §

Customized LaTeX exports for humanities papers

The pain-point §

Approach 1 §

Approach 2 §

Approach 3 §

Features I’m looking forward to in Emacs 31

Table of Contents

Org and LaTeX integration

My desired workflow §

Basic Formatting: org-latex-classes §

Title pages: Creating an Org-export backend §

Customize the org-export LaTeX backend §

Backend §

Template §

Final title command §

Citations and bibliographies: Org-cite §

One way to specify citation style §

My method to specify citation style §

Final result and screenshots §

Extras §

Section numbers §

Hyperref §

Table of contents §

Org links §

Full configuration §

The state of grammar checking in Emacs

Table of Contents

There are lots of options for sidenotes

What I learned starting web dev with Astro

HTML best practices §

Components are awesome §

CSS §

MD vs MDX vs Markdoc §

An Amazing Marvin Starter Pack

Table of Contents

TL;DR §

Core concepts §

The Master List §

The Main View §

What good is Amazing Marvin’s system? §

The beauty of Strategies §

A list of must-look-at Strategies §

Author’s Note §

On Zettelkasten purism and the misdirection of backlinks

TL;DR §

I disagree with ‘backlink exceptionalism’ §

The ‘practice’ is most essential §

An aside: but what about backlinks?! §

Luhmann isn’t the only success story §

So what do you do now? §

How has my own advice affected me? §

Windows

Beauty §

Discomfort §

Inquiry §

Without §

Comfort §

Unnoticed §

Author’s Note §

The “Great Books Idea” and liberal versus general education

The origins of the “great books idea” §

The ideal of liberal education §

A case against Adler and Hutchins §

Author’s note §

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

Table of Contents

Synopsis §

Marginalia §

All-the-icons-completion §

Vertico §

Basic §

Extensions §

Vertico extension commands §

Niceties §

Basic Formatting: `org-latex-classes` §

Customize the `org-export` LaTeX backend §

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

Working with the recent changes to `corfu` §

Further configuration in minibuffers and with `lsp` §

What is `cape`? §

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

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

`pcomplete` nicety §

My `completion-at-point-functions` §

Understanding `org-cite` export processors §

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

The nicety of `vc-dir` marks §