Emacs on . local author .

Simple Document Tagging with 'doc-tags.el'

Thu, 18 Sep 2025 12:17:00 +0300

When I posted last week about tab-sets.el, I didn’t know that this month’s Emacs Carnival topic is “Obscure Packages.” Well, it’s hard to be more obscure than an unpublished package that I use for my own idiosyncratic ends. So, here’s another!

——————————————————————————————

Introducing doc-tags.el: a simple, low-overhead Emacs package for tagging and retrieving files using a SQLite backend.

doc-tags is a straightforward package that lets you:

Tag any file or directory on your computer, with one or more tags
Quickly find and open files by tag, using “AND” (all tags) or “OR” (any tag) search
Update, rename, or remove tags interactively
Keep your tagged-doc database in a single regular file

You add only what matters to you: notes, readings, drafts, reference folders, syllabi, whatever. Tags are just Emacs strings — no renaming or relocating files, no global search, no magic.

Nota Bene

In general, I am skeptical about the long-term use value of tags. I find them flimsy. I much prefer organizing files in directories, and relying on searching to find what I’m looking for.

With that in mind, doc-tags is not — and is not meant to be — a replacement for file management writ large. I use devonthink for that. It is a huge directory structure of PDFs and lecture notes, organized within the devonthink program in all sort of useful ways, for long-term storage and findability, but otherwise — for all intents and purposes — a jumble of files in a maze of directories.

The major downside of devonthink, for me, is that its database structure is not accessible from inside Emacs. (Yet?) Sure, I can use a recursive search to plumb the depths of my devonthink database for what I think I need, but that’s a somewhat crude approach.

So, I wrote doc-tags as a middle-ground, ad-hoc solution, allowing me to assign tags to files in disparate locations across my file system, wherever they may be, even deep within my devonthink database.

Because of my deep skepticism of tags, I mostly use doc-tags when working on fleeting tasks, like preparing for a class or working on short-term writing projects. When the task is finished, I just delete the tags I no longer need and move on without remorse. No need to create a new directory, copy or symlink files. Just quick and dirty tagging, for the moment.

How to set it up

doc-tags.el isn’t up on M/ELPA, so install directly from GitHub:

(use-package doc-tags
  :ensure nil
  :vc (:url "https://github.com/localauthor/doc-tags")
  :custom
  (doc-tags-db-file "~/.emacs.d/var/doc-tags.sqlite") ;; pick your database location
  :config
  (doc-tags-connect) ;; opens/creates the database and initializes the schema
  )

You’ll also need triples (which manages the SQLite database and backups) and sqlite3 available to Emacs.

How does it work?

To add a document: M-x doc-tags-add-doc (prompts for a file, then for one or more tags)
To search by tag: M-x doc-tags-find-file (AND logic by default; use C-u for OR search)
To add/remove tags: M-x doc-tags-add-tag / M-x doc-tags-remove-tag To edit/rename tags: M-x doc-tags-edit-tag
To remove a document: M-x doc-tags-remove-doc

Most commands offer smart completion (minibuffer with tag annotations, document previews); if you use embark, doc-tags offers a keymap for quick actions on tags and docs.

Managing Emacs Tabs with 'tab-sets.el'

Sat, 13 Sep 2025 01:54:00 +0300

——————————————————————————————

In Emacs, my text editor of choice, tab-bar-mode lets you replicate something like the experience of using tabs in a web browser. For me, this means opening a lot of tabs with notes, lists, drafts, etc., such that my tab bar becomes a visual buffet of whatever documents are pertinent to the task at hand, be it writing, teaching, coding, whatever.

This works great for me, on a project by project basis. But what if I want to switch to another task or project? What is to become of the perfectly curated set of tabs I have open?

The problem of tab proliferation is a distinctly modern one. Raise your hand if the top of your web browser looks like a graveyard of articles you’ve been meaning to read since the last time your computer crashed. Many browsers have solved this issue by allowing users to save and restore groups of tabs under meaningful names, like “Research Project” or “Articles I Still Won’t Read.” But who does that? (Ok, I do…)

As far as I know,™ Emacs does not offer any built-in way to save and restore a beautifully curated row of tabs. There are many options for saving and restoring activities, workspaces, and frame/buffer configurations. But none that do exactly what I want, namely, allow me to save and later re-open a set of tabs, one file per tab, in a specific order.

So, I wrote tab-sets.el.

I find tab-sets most useful for teaching and writing.

For example: I sometimes teach the same class several times in a week. I therefore often found myself repeating the process of finding and re-opening all the files that I wanted to reference for that class, mostly lecture notes and slides (exported with org-reveal). Because these files can be spread out across my file system, finding and re-opening them is rarely as simple as navigating to a dedicated directory.

Now, with tab-sets.el, I can use a single command, tab-sets-save, to save the current frame’s tabs under a meaningful name, say, “Week 1 Class”, and safely close the frame. When it’s time to teach the same class again, I can call tab-sets-open, select “Week 1 Class,” and find a brand new frame displaying all the tabs exactly as they were when I saved them.

The same process works for quickly returning to a writing project.

A few niceties include:

minibuffer annotations, offering a preview of each tab set
optional integration with bookmarks.el, meaning tab sets are accessible as standard bookmarks, through list-bookmarks
optional integration with embark, meaning you can open, rename, or delete a tab set right from the minibuffer

This package isn’t published anywhere, so install directly, however you want or know how. For example:

(use-package tab-sets
  :ensure nil
  :vc (:url "https://github.com/localauthor/tab-sets")
  :custom
  (tab-sets-data-file "~/.emacs.d/var/tab-sets.eld")
  :config
  (tab-sets-setup-embark))

Emacs Popup Frames Anywere — MacOS Edition

Sat, 28 Sep 2024 11:15:00 +0300

This post shows how to set up Emacs popup frames in macOS, allowing quick access to Emacs functions from anywhere on your system.

——————————————————————————————

As much as I would like to live in Emacs full time, I’m not quite there. But a recent post by Protesilaos Stavrou (aka Prot) is helping me bridge the gap.

Prot has written a short but powerful bit of code that allows you to access any piece of Emacs goodness — like org-capture — from outside Emacs with just one keystroke. The only requirement is that you are running in server-mode or using the Emacs daemon.

Whether you’re in a web browser, a PDF reader, or just staring at an empty desktop, your favorite Emacs command can be right at your fingertips. See Prot’s video for a thorough demonstration.

Now, I can quickly open a PDF using citar or copy a password from my pass-store. See below for some other useful popups — org-agenda view, mu4e inbox, and a quick translation interface.

Since Prot wrote the code for use in Linux, it didn’t immediately work in MacOS. It turns out, the only necessary change was to add a window-system frame parameter to the popup frame. (See code below).

But while I was at it, I made a few additions: 1) a title frame parameter, which allows me to configure the popup frame size and placement through my tiling window manager, yabai; and 2) an optional argument that runs delete-frame after the main command runs. This makes it possible to call commands that are minibuffer-centric — in my case, that’s citar-open-file and password-store-copy.

Here’s the main code:

(defun popup-frame-delete (&rest _)
  "Kill selected frame if it has parameter `popup-frame'."
  (when (frame-parameter nil 'popup-frame))
  (delete-frame))

(defmacro popup-frame-define (command title &optional delete-frame)
  "Define interactive function to call COMMAND in frame with TITLE."
  `(defun ,(intern (format "popup-frame-%s" command)) ()
     (interactive)
     (let* ((display-buffer-alist '(("")
                                    (display-buffer-full-frame))))
       (frame (make-frame
               '((title . ,title)
                 (window-system . ns)
                 (popup-frame . t)))))
     (select-frame frame)
     (switch-to-buffer " popup-frame-hidden-buffer")
     (condition-case nil
         (progn
           (call-interactively ',command)
           (delete-other-windows))
       (error (delete-frame frame)))
     (when ,delete-frame
       (sit-for 0.2)
       (delete-frame frame))))

(use-package server
  :defer 1
  :config
  (unless (server-running-p)
    (server-start)))

And here are the macro calls that define commands:

(popup-frame-define org-capture "capture-popup")
(add-hook 'org-capture-after-finalize-hook #'popup-frame-delete)

(popup-frame-define password-store-copy "minimal-popup" 'delete-frame)

(popup-frame-define citar-open-files "minimal-popup" 'delete-frame)

Triggering Popups with Keyboard Shortcuts

To quickly bring up these popup frames with keyboard shortcuts, I use skhd, a hotkey daemon for macOS. The following configuration goes in the skhd config file:

cmd + ctrl - c : emacsclient -e '(popup-frame-org-capture)' || yabai -m window –focus recent
cmd + ctrl - o : emacsclient -e '(popup-frame-citar-open-files)' || yabai -m window –focus recent
cmd + ctrl - p : emacsclient -e '(popup-frame-password-store-copy)' || yabai -m window –focus recent

Managing Windows with yabai

Finally, I have configured my tiling window manager, yabai, to give the popup frames the desired size and placement.

First, the following goes in the yabai config file:

yabai -m signal –add event=window_created app="Emacs" action="~/.yabai-emacs-window-handler.sh"

This will run a bash script (located at ~/.yabai-emacs-window-handler.sh) every time a new Emacs frame is created. The script tells yabai how to move and resize the new frame, depending on the frame’s title. Here is that script:

#!/bin/bash

data=$(yabai -m query –windows –window $YABAI_WINDOW_ID)

title=$(echo $data | jq .title)
display=$(echo $data | jq .display)

if [[ $title =~ "capture-popup" && $display == 1 ]]; then
yabai -m window $YABAI_WINDOW_ID –toggle float –move abs:430:230
yabai -m window $YABAI_WINDOW_ID –resize abs:655:300
yabai -m window $YABAI_WINDOW_ID –focus
elif
[[ $title =~ "minimal-popup" && $display == 1 ]]; then
yabai -m window $YABAI_WINDOW_ID –toggle float –move abs:430:230
yabai -m window $YABAI_WINDOW_ID –resize abs:655:200
yabai -m window $YABAI_WINDOW_ID –focus
else
false
fi

Additional Custom Commands

In some cases, an Emacs command will work nicely in a popup frame right out of the box. A good case in point is org-capture. In other cases, I have needed to write my own custom commands. Here a few:

Google Translate Interface

(defun my/translate ()
  (interactive)
  (let ((choice
         (completing-read "Select: " '("EN->LT" "LT->EN"))))
    (cond ((string= choice "EN->LT")
           (google-translate-query-translate-reverse))
          ((string= choice "LT->EN")
           (google-translate-query-translate)))))

(popup-frame-define my/translate "minimal-popup")

Unread Emails in mu4e

(defun my/mu4e-unread ()
  (interactive)
  (mu4e 'background)
  (mu4e-search-bookmark
   (mu4e-get-bookmark-query ?u)))

(popup-frame-define my/org-agenda "large-popup")

For this, I add another “elif” to the bash script, to ensure I can see the whole inbox in the popup:

elif
[[ $title =~ "large-popup" && $display == 1 ]]; then
yabai -m window $YABAI_WINDOW_ID –toggle float –move abs:350:130
yabai -m window $YABAI_WINDOW_ID –resize abs:730:600
yabai -m window $YABAI_WINDOW_ID –focus

Custom Org-Agenda View

(defun my/org-agenda (&optional p)
  (interactive "P")
  (org-agenda p "d")
  (org-agenda-redo-all))

(popup-frame-define my/org-agenda "large-popup")

Just don’t forget to add a system-wide keyboard shortcut for each new command!

Emacs: Quickly find and insert links in zk notes, with Embark

Thu, 21 Jul 2022 14:12:00 +0300

This post continues a series of video demos in which I show how I use the Emacs package zk for notetaking. The emphasis is on showcasing the practicalities of my process.

——————————————————————————————

In this video, I show how I quickly find notes related to the note I am working on in zk, and then insert the relevant links.

The goal is to find and insert links with a minimum of mental overhead and technical friction, so that I can keep my focus on the ideas and content of the note at hand.

Trying to find a single note among hundreds, and then putting the link in the right spot, could be a task unto itself — a not inconsiderable problem and distraction. But a few handy search functions, and some help from the package Embark, make the matter all but effortless.

Emacs: Getting started with zk, using hydra and an inbox note

Tue, 19 Jul 2022 00:31:00 -0400

This post inaugurates a series of video demos in which I will show how I use the Emacs package zk for notetaking. The emphasis will be on showcasing the practicalities of my process.

——————————————————————————————

In this video I show how I use a hydra as an entry point to my zk. The config for my hydra is here, in my dotfiles.

I also show how I use an “inbox” note as a starting place for new notes. For more on the place of the inbox in a notetaking practice, see section 2.1 of How to Take Smart Notes by Sönke Ahrens.¹

In the next video, I will show how I use the function zk-find-file and others in combination with Embark to quickly find notes and insert links — with a minimum of effort!

Sönke Ahrens, How to Take Smart Notes: One Simple Technique to Boost Writing, Learning and Thinking (North Charleston, SC: CreateSpace, 2017). ↩︎

Emacs: With ace-window and link-hint, open links exactly where you want them

Thu, 14 Apr 2022 12:28:00 +0300

This post describes how the Emacs package link-hint can be combined with ace-window to allow you to select, on-the-fly, which window a link will open in—instead of letting fate, or custom, or Emacs decide for you.

——————————————————————————————

Ace-window is (more than) a fancy window-switcher

The ace-window package, written by abo-abo, offers a handy, full-featured alternative to the built-in window-switching function other-window. The package’s primary function—the titular =ace-window=—overlays a different character (letter or number) over each visible Emacs window, so you can switch to the desired window by simply pressing its assigned character. Very useful, very sleek.

But ace-window is more than just a handy way to switch windows.

The package also offers the ability to perform an action in the selected window before switching to it. In this regard, it follows the design of its parent package avy—also by abo-abo. Instead of simply switching to a window, you can split it first, call switch-to-buffer in it, or even close it. For a demonstration of this aspect of ace-window, see this video from Protesilaos Stavrou.)

The greatness of ace-window truly comes through, however, when it is combined with other packages.

With ace-window and Embark, open files/buffers in specified windows

In his detailed write-up on using Embark, Karthik Chikmagalur showcases a killer mash-up of ace-window and Embark, demonstrating how ace-window can be used for more than just switching windows.

Briefly put, Karthik shows how to incorporate ace-window’s window-selection function into the opening of a file or buffer from the minibuffer so that, as he writes, “any buffer/file/bookmark I open is always placed exactly where I want it to be on the screen.”

An example usage would be:

call find-file
call embark-act on file you wish to open
call my/embark-ace-action-find-file (this is the slightly unwieldy name Karthik gives to the embark/ace-window function)
select desired window with ace-window

With ace-window and link-hint, follow links in specified windows

Inspired by what Karthik showed was possible, I wanted to incorporate ace-window with link-hint, so that I could choose which window a link would open in. The result is a function called link-hint-aw-select:

Figure 1: Using ’link-hint-aw-select’ to open each of the links in the top left window in a different window. First, the desired link is chosen via character overlay, courtsey of link-hint, then the desired window is chosen via character overlay, courtsey of ace-window.

If you’re unfamiliar, link-hint is a package that is conceptually similar to ace-window: it puts a character overlay on visible links in a buffer so that you can choose a link to follow by typing its assigned character. (The conceptual similarity of link-hint and ace-window is not surprising, since both are based on avy.)

Link-hint can identify a lot of different type of links, such as urls, file paths, mailto links, org-links, buttons, and dired filenames. New link types can also be defined by the user. (More on that later.)

As with avy and ace-window, link-hint allows for different actions to performed on the chosen link. However, there are only two default actions for acting on links: open link and copy link.

Defining a new action is done by defining a new function, in this case the above-mentioned link-hint-aw-select, which will be entry-point command for all link types:

(defun link-hint-aw-select ()
  "Use avy to open a link in a window selected with ace-window."
  (interactive)
  (unless
      (avy-with link-hint-aw-select
        (link-hint–one :aw-select))
    (message "No visible links")))

Things get more complicated very quickly, however.

Each action must be tailored to each different link type. Take the case of the “open” action, for examples: urls open one way—in a browser—and filepaths open another way—in a relevant application—and email addresses open another way—in a new draft email. Each action is actually many different actions, all roughly similar.

When creating a new action, then, it is necessary to make sure that each link type is associated with a function that will perform the new action in the appropriate way.

The aw-select action for file links is quite simple:

(defun link-hint–aw-select-file-link (link)
  (with-demoted-errors "%s"
    (aw-switch-to-window (aw-select nil))
    (find-file link)))

To make the link-hint ecosystem aware of this new association of link-type, action, and function, there is a handy macro:

(link-hint-define-type 'file-link
  :aw-select #'link-hint–aw-select-file-link)

If different link-types behave similarly, it is possible to create a macro of our own that will do all of the above very efficiently. This is the case with buttons and dired-filenames, for example:

(defmacro define-link-hint-aw-select (link-type fn)
  `(progn
     (link-hint-define-type ',link-type
       :aw-select #',(intern (concat "link-hint–aw-select-"
                                     (symbol-name link-type))))
     (defun ,(intern (concat "link-hint–aw-select-"
                             (symbol-name link-type))) (_link)
       (with-demoted-errors "%s"
         (if (> (length (aw-window-list)) 1)
             (let ((window (aw-select nil))
                   (buffer (current-buffer))
                   (new-buffer))
               (,fn)
               (setq new-buffer (current-buffer))
               (switch-to-buffer buffer)
               (aw-switch-to-window window)
               (switch-to-buffer new-buffer))
           (link-hint-open-link-at-point))))))

(define-link-hint-aw-select button push-button)
(define-link-hint-aw-select dired-filename dired-find-file)

The same is almost the case with org-links as well, except that by default org-links are opened using find-file-other-window instead of find-file, meaning that the above macro wouldn’t work properly.

I prefer to change this setting globally, so that org-links are opened in the current window, by evaluating the following:

(setf (cdr (assoc 'file org-link-frame-setup)) 'find-file)

This allows me to use the macro:

(define-link-hint-aw-select org-link org-open-at-point)

To leave org’s default behavior in place globally, it is necessary to define a function specifically for org-links, in which the behavior is changed locally in a let-binding:

(defun link-hint–aw-select-org-link (_link)
  (let ((org-link-frame-setup
         '((file . find-file))))
    (with-demoted-errors "%s"
      (if (> (length (aw-window-list)) 1)
          (let ((window (aw-select nil))
                (buffer (current-buffer))
                (new-buffer))
            (org-open-at-point)
            (setq new-buffer
                  (current-buffer))
            (switch-to-buffer buffer)
            (aw-switch-to-window window)
            (switch-to-buffer new-buffer))
        (link-hint-open-link-at-point)))))

(link-hint-define-type 'org-link :aw-select #'link-hint–aw-select-org-link)

Things are actually even a bit more complicated than this with org-links.

Since org handles different link-types internally, the function link-hint–aw-select-org-link can also be made to handle certain org link-types differently. For example, if you want http/https links to be opened externally, there is no reason to call the aw-select behavior for that type of org-link. This could be accomplished by including something like the following in the function’s “if” conditional:

(not (member (org-element-property :type (org-element-context))
             '("http" "https")))

The whole function would be:

(defun link-hint–aw-select-org-link (_link)
  (let ((org-link-frame-setup
         '((file . find-file))))
    (with-demoted-errors "%s"
      (if (and (> (length (aw-window-list)) 1)
               (not (member (org-element-property
                             :type (org-element-context))
                       '("http" "https"))))
          (let ((window (aw-select nil))
                (buffer (current-buffer))
                (new-buffer))
            (org-open-at-point)
            (setq new-buffer
                  (current-buffer))
            (switch-to-buffer buffer)
            (aw-switch-to-window window)
            (switch-to-buffer new-buffer))
        (link-hint-open-link-at-point)))))

Example use-case: note-taking, zettelkasten, etc.

I find this functionality really useful in my note-taking environment, where each of my notes contains several links to other notes. I rarely want to follow a link in the same window as the note where the link appears. I typically want to leave that note where it is and open a link somewhere else. If I have several windows arrayed around my screen, I can use link-hint-aw-select to open the linked note exactly where I want it to be.

To use this with org, the above configuration is enough. If you use another note-taking environment, you may need to define a new link type.

For example, for use with my own Zettelkasten package zk, I define a new link type zk-link and a function zk-link-hint-aw-select, along with other functions necessary to fully incorporate a new link type into the link-hint system:

(defun zk-link-hint–zk-link-at-point-p ()
  "Return the ID for the zk-link at the point or nil."
  (and (zk–id-at-point)
       (thing-at-point-looking-at zk-link-regexp)))

(defun zk-link-hint–next-zk-link (bound)
  "Find the unext zk-link.
Only search the range between just after the point and BOUND."
  (link-hint–next-regexp zk-id-regexp bound))

(defun link-hint–aw-select-zk-link (id)
  (with-demoted-errors "%s"
    (if (> (length (aw-window-list)) 1)
        (let ((window (aw-select nil))
              (buffer (current-buffer))
              (new-buffer))
          (zk-follow-link-at-point id)
          (setq new-buffer
                (current-buffer))
          (switch-to-buffer buffer)
          (aw-switch-to-window window)
          (switch-to-buffer new-buffer))
      (link-hint-open-link-at-point))))

(link-hint-define-type 'zk-link
  :next #'zk-link-hint–next-zk-link
  :at-point-p #'zk-link-hint–zk-link-at-point-p
  :open #'zk-follow-link-at-point
  :copy #'kill-new
  :aw-select #'link-hint–aw-select-zk-link)

(push 'link-hint-zk-link link-hint-types)

Even though link-hint can be a bit complex under the hood, it is quite effortless, even elegant, when put in combination with ace-window. Give it a try and puzzle over what you had done so long without it.

Emacs on . local author .

Simple Document Tagging with 'doc-tags.el'

Nota Bene

How to set it up

How does it work?

Managing Emacs Tabs with 'tab-sets.el'

Emacs Popup Frames Anywere — MacOS Edition

Setting Up Emacs Popup Frames in MacOS

Triggering Popups with Keyboard Shortcuts

Managing Windows with yabai

Additional Custom Commands

Google Translate Interface

Unread Emails in mu4e

Custom Org-Agenda View

Emacs: Quickly find and insert links in zk notes, with Embark

Emacs: Getting started with zk, using hydra and an inbox note

Emacs: With ace-window and link-hint, open links exactly where you want them

Ace-window is (more than) a fancy window-switcher

With ace-window and Embark, open files/buffers in specified windows

With ace-window and link-hint, follow links in specified windows

Example use-case: note-taking, zettelkasten, etc.