. local author .

####

Fri, 03 Oct 2025 10:04:00 +0300

2025-09-26

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))

Ežerų Dugne

Sat, 22 Feb 2025 17:46:00 +0200

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

“But nature is a stranger yet”

in the above film –
Ežerų dugne (In the Depths of Lakes) (2014), dir. Akvilė Anglickaitė
— —
divers explore their love for four Lithuanian lakes
and the alien terrain at their depths:
— —

— — — — —

on view at MO until March 30, 2025,
as part of an exhibition on solastalgia
—

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!

To Carve Something Meaningful

Tue, 15 Nov 2022 20:57:00 +0200

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

“One of the most important functions of ‘place’
is its ability to bridge
the scholarly realm of the academic geographer
and everyday terrain of ordinary people
trying to understand the world
and make it better.
Without ‘place,’ geographers risk
losing their most important audience:
those engaged in the struggle
to carve something meaningful
out of an impersonal, abstract world.”¹

Steven Hoelscher, “Place,” in The Wiley-Blackwell Companion to Human Geography, ed. John A. Agnew and James S. Duncan (Chichester, West Sussex: Malden, MA : Wiley-Blackwell, 2011), 256–57. ↩︎

"What should I read next?"

Sat, 12 Nov 2022 18:31:00 +0200

Read one of these. (And then read the others.)

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

Anne Carson, Autobiography of Red
Annie Dillard, Pilgrim at Tinker Creek
Claudia Emerson, Pinion
Maggie Nelson, Bluets
W. G. Sebald, The Emigrants

Notetaking: What are you after?

Thu, 01 Sep 2022 11:00:00 +0300

Why do you want to take notes in the first place?

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

Each person’s notetaking practice is—and must be—distinct. No two people have the same needs when it comes to making, organizing, and accessing notes.

Adopting someone else’s practice just because they can loudly sing its merits, or even clearly demonstrate its efficacy, may very well be an exercise in shortsightedness. A person’s notetaking practice could certainly have merits and be effective—for them—but there can be no guarantee of universality in such things.

So, a few questions to consider:

Why do you want (or need) to take notes at all?
What kind of information are you trying to store and keep track of?
When and how do you want to come across the stored information again?
Will the notes be an end in themselves or raw materials for other writings?

My own answers:

I take notes for the purposes of academic research and lecturing.
I store and keep track of the thoughts, ideas, and insights of others, as encountered in books, articles, presentations, etc., as well as my own thoughts, ideas, and insights, as they occur to me, most often in response to the thoughts (etc.) of others.
I want to come across the stored information both as I am writing other notes, for the purposes of making connections between ideas and insights, and as I am writing research papers and lectures.
My notes are both an end in themselves, to the extent that they facilitate and constitute my thinking, and raw materials for other writings.

My Starting Points

The “Inbox” Note

I keep a note that I call an “inbox” note, which is just a plaintext file on my computer. It is one of two entry-points to my notetaking pactice. When I have an idea that I want to keep track of, instead of making a new note right away (a new file on my computer), I go to my “inbox” and start writing things down, a bit freeform, right at the top.

I consider this space like a sketch pad. There is no pressure to produce anything polished or fully thought through. If I end up writing something worth keeping, I copy it into a new note (that is, a new text file—each of my notes is a separate text file, all stored in a folder called “Notes”).

If the idea doesn’t really develop or seem worth keeping, I either delete it, or just leave it there. I will write the next idea above it, and it will simply be pushed down a few lines. The bottom of my inbox is something of a graveyard of ideas. Sometimes I go through and clean them out, to “clear the inbox,” as it were. Sometimes when I do this I find something worth recovering.

The purpose of the “inbox” note is to eliminate any friction that might disrupt the actual taking of a note when the need/desire to take a note arises. It allows me to get right to the important business of putting an idea down and avoid having to fool with any other, less pressing business, like finding the right place to put the idea. I have a shortcut key that opens the inbox note right away. Highly recommended.

The “Literature” Note

Often I am taking notes on something I’m reading, be it a book, an article, or a website. After entering the appropriate citation information into my bibliographic database and assigning the resource a unique citekey, I skip the “inbox” and go straight to creating a new note dedicated to the material I am reading. This is called a literature note.¹

The name of each literature note is the resource’s unique citekey followed by its author and title, like so: “Conrad1899 - Joseph Conrad - Heart of Darkness.txt”. By having a programmatic titling scheme, I always know right where to find my notes for what I’ve read.

As I read, I keep the literature note open and write down ideas, quotations, and questions as they occur to me, always making reference to the appropriate page number when relevant.

If any idea or line of thought arises while reading that seems interesting enough to stand on its own, I can make a separate note for it, and include a reference to that new note in the literature note itself. A literature note could be a page-by-page account of a resource, or it could be a list of references to stand-alone notes. Most often it is somewhere in between.²

See Sönke Ahrens, How to Take Smart Notes: One Simple Technique to Boost Writing, Learning and Thinking (North Charleston, SC: CreateSpace, 2017). ↩︎
The matter of inserting references to other notes can be facilitated by any number of progams. I use a package I wrote for Emacs called zk, demonstrations of which can be seen here and here and here. Similar programs worth looking at are nvALT, The Archive, and Zettlr. ↩︎

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). ↩︎

Chthonophagia

Sun, 24 Apr 2022 23:28:00 +0300

\Chthon`o*pha"gi*a\, Chthonophagy \Chtho*noph"a*gy\, n. [NL. chthonophagia; Gr. ?, ?, earth + ? to eat.]

A disease characterized by an irresistible desire to eat earth, observed in some parts of the southern United States, the West Indies, etc.

Webster’s Revised Unabridged Dictionary (1913)

Citekeys: For Better Research / Life

Sun, 24 Apr 2022 23:19:00 +0300

Use citekeys to consistently and uniformly correlate in-text references with original source materials, not just in final submissions but also in notes and drafts.

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

For long research projects, it is necessary not only to keep straight a variety of sources but also to ensure that in-text references to those sources are unambiguous. This allows readers to trace all lines of thought to their original contexts. This is obviously a requirement of all formal publications.

But a clear and consistent citation practice should not be neglected in the writing that leads up to a final submission, such as notes, outlines, drafts, etc. When you are still the project’s primary (or only) reader, you must still be able to trace lines of thought to their origins.

In many cases, this may not be difficult. In the middle of a project, when everything is fresh in your working memory, you might be able to make sense of all kinds of non-standard forms of citation, no matter how informal: “cite book on national identity formation,” “quote comes from that article we read during week 3,” “see Foucault 257.”

But the larger a project is and the more time that passes between note-taking and final submission the more effort will be involved in tracing such citations to their sources.

In the case of a career researcher, informal citations like the above will inevitably lose their meaning as their originary contexts recede into the past. Which book on national identity formation was that? Which class? Which book by Foucault, and which edition?

The use of citekeys can greatly reduce the effort involved in mainlining clear lines of connection between citations and sources—not just in final products but in notes and drafts as well, and not just in single projects but in a lifetime of research.

Citekey Basics

A citekey (or citation key) is a unique code assigned to a particular piece of source material that can be used to quickly and consistently refer to that source.

A citekey is typically composed of some combination of the source’s year of publication, its primary author’s surname, and/or a short version of its title.

Here are three different citekeys, in three common styles, that could be used for the same source, the book Imagined Communities by Benedict Anderson. Each offers a far more precise indication of what source is being referred to than the comparatively ambiguous “cite book on national identity formation”:

Anderson2006
andersonImaginedCommunities2006
anderson2006_ImaginedCommunities

It is important to note that citekeys are not expected to be clearly understandable to anyone other than the researcher who assigns them. Consider that “Anderson2006” in the example above could refer to any number of publications from the year 2006 by anyone with the surname Anderson.

In this way citekeys are unlike ISBN or DOI numbers: they are not universal indicators—they do not point directly and unambiguously to particular sources themselves.

Rather, citekeys point to a researcher’s own individual collection of bibliographic entries (more on this ahead). Citekeys offer, as a result, a simple, private system of shorthand for encoding reference information into any written document, all without the work entailed in writing out full formal citations and bibliographic entries in every instance.

Given their simplicity and ease of use, citekeys help to lower any barriers that might otherwise have impeded the inclusion of clear, reliable citations in even the most informal of written documents, including and especially those that are not intended for publication. They thereby help to eliminate any temptation to insert ambiguous and cryptic notes-to-self that risk baffling more than benefiting.

Your Bibliographic Database

For texts that are intended to be published, citekeys offer great flexibility, as they can be easily replaced with formal citations in whatever citation style is appropriate to the intended context, such as Chicago, MLA, Harvard, APA, etc.

This requires maintaining a centralized repository of bibliographic information wherein all citekeys are listed with relevant information about the associated source. This may sound more complicated than it is.

While it is possible to manage bibliographic information with one of the many popular reference management programs—such as Zotero, Endnote, or Mandeley—it is equally possible to maintain nothing more than a simple text document of entries like the following:

@book{Anderson2006,
        title = "Imagined Communities: Reflections on the Origin and Spread of Nationalism",
        author = Anderson, Benedict",
        year = "2006",
        publisher = "Verso",
        address = "London; New York",
}

The above entry happens to be written in a standardized format called BibTeX, often used or at least supported by reference management software. For the sake of future-proofing your bibliography, it might be worthwhile to use such a standardized format.¹

But such entries can easily be written and maintained in any format and without such software, using nothing more than a plaintext editing program like TextEdit (MacOS) or Notepad (Windows). The most important thing is to include all the relevant information about the source and associate it with a unique citekey.

From such information, it will be possible to produce citations and references in any of a seemingly endless array of standardized citation styles.²

Key Rule: Be Consistent

No matter what style of citekey or method of bibliography management is used, internal consistency is essential. Use a consistent citekey style—I use AuthorYEAR, like “Anderson2006”—so that each source is associated with a only single citekey. Do not use both “Anderson2006” and “andersonImaginedCommunities2006.”

Also, take care to ensure that each citekey is associated with only a single source. If you add a source by a different Anderson also written in 2006, assign it a unique citekey, like “Anderson2006a” or “Anderson2006-1.”

Note that using citekeys also makes it easy to include and distinguish between different editions of a single text. You might also have reason to cite the first edition of Imagined Communities (1983) alongside the reprint. Luckily, there is no confusing “Anderson1983” and “Anderson2006.”

Citekeys In Use

Choosing a citekey style, assigning citekeys to sources, and keeping them all matched up in a bibliography database is only the beginning.

Once you’ve done all that, how to go about putting them to use in your writings?

Here is an example from my reading notes:

Heise cites [#Anderson2006], who make a similar connection between representations and identity-formation.[5][#Heise2008]

I was not taking these notes for any specific project or a potential publication where accurate citations would be necessary. Nevertheless, it was so simple to include the citekeys and a page reference that I didn’t consider not doing it.

It was the use of citekeys, formatted in a distinct syntax—in brackets, preceed by the hash sign³—that made it effortless to find this reference (along with several others) to Anderson’s Imagined Communities in a file on my computer that is not obviously about the text in question and that I haven’t looked at or thought about since I wrote it. How about that?

Bonus: PDF Management

Aside from helping you keep your citations legible and locate deeply embedded notes in the recesses of your file system, citekeys can also help you keep track of PDFs and other digital documents. No longer worry over what to name that PDF. Enter its information into your bibliography file, assign it a citekey, and use the citekey as the name of the file. You’ll never have to guess what “Anderson2006.pdf” contains.

https://www.bibtex.com/g/bibtex-format/ ↩︎
https://citationstyles.org ↩︎
These citations are in a syntax called MultiMarkdown. A similar syntax, called Pandoc, uses the @ prefix instead of the #, among other differences: [@Anderson2006, p 22-23]. ↩︎

Coracoid

Fri, 22 Apr 2022 01:26:00 +0300

\Cor"a*coid\, a.[Gr. ?; ko`rax crow + e’i^dos form.]

Shaped like a crow’s beak.
(Anat.) Pertaining to a bone of the shoulder girdle in most birds, reptiles, and amphibians, which is reduced to a process of the scapula in most mammals.

Webster’s Revised Unabridged Dictionary (1913)

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.

Stendhal at Hand in Vilnius

Sun, 31 Oct 2021 11:12:00 +0200

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

Stendhal might have spent the night in a building near where I live.

There is a plaque on the wall of the building — a bookstore now, specializing in French literature — memorializing the night that Stendhal is said to have stayed there.

With its bilingual inscription and bas relief portrait of the artist, the plaque brings some kind of life to that corner, projecting a line clear to a far side of Europe.

Something of French culture once comforted itself here, if you can imagine.

—————

You’ll have to imagine.

The plaque does not cite its sources. It does not quote from the writer. It does not paint a picture of an event, a time, or a place.

ŠIAME NAME … BUVO APSISTOJES … STENDALIS

DANS CETTE MAISON STENDHAL … FIT ETAPE

Where would one look if one were inclined to dig up the truth of what may or may not have happened in this or another place at this or that time so many decades, centuries since?

But then, who would care to doubt these chiseled records?

—————

All told, the plaque is less a statement of fact than one of values.

“Draw this place closer, in your mind, to what you might already know well,” it says.

“Comfort yourself, that you are not so far away, so disconnected, as you thought—as you might have feared.”

—————

In some letters Stendhal notes his passing, while marching with Napoleon’s army, through various cities and towns in the region. His remarks are spare, revealing an experience of dismal early winter and little else.¹

Antanas Vaičiulaitis, “Stendhal in Lithuania,” trans. M. Vasiliauskas, Lituanus: Lithuanian Quarterly Journal of Arts and Sciences 22, no. 2 (1976). ↩︎

Drafting, Beyond MS Word

Sat, 30 Oct 2021 12:56:00 +0300

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

There is no good way to write an essay.

But there are several bad ways.

Too common, I think, is the impulse to open up a fresh document in Microsoft Word — or Google Docs, or LibreOffice¹ — and begin banging away at whatever process has worked in the past.

That process — whether it be freewriting, or transcribing, or listing, or outlining — might be effective, or it might not.

But the forum in which that process takes place all-too-often — the blank white simulated piece of paper — is certainly not doing you any favors.

I once saw the great Ted Nelson² give a talk (screed) in a library, in which he denounced (railed against) the usage of the term “desktop” in personal computing.

How many desktops, he asked (shouted), are positioned vertically in front of you?

Similarly: do you really need to type out your essay’s fledgling stages on something that looks like a piece of paper³ just because that’s the particular physicality that your essay will take on later?

Let’s be honest, though — your essay will never take on the physicality of a piece of paper.

Because you’re not going to print your essay out on paper.

You’re just going to email it to someone, who is also not going to print it out on paper.

So, what else can you do? Where else can you write?

Do me a favor:⁴

Open TextEdit (on MacOS) or Notepad (on Windows).
Start your essay-writing process, whatever that might entail.
Reflect.

How does it feel to be writing in a space ungoverned by the arbitrary geometries of the US Letter or A4 sheet?⁵

Do you feel liberated? No? Well, give it a minute.

If you’ve enabled “Word Wrap” (Notepad) or “Wrap to Page” (TextEdit) try resizing the window so you can only see the few sentences you’re working on. How does that feel?

Liberating? No? Then try something else.

The point here is not to prescribe a way of writing but rather to prompt the shaking loose of the notion of prescription.

There is no straight line through the production of an essay and, accordingly, no good reason why a process as messy and full of switchbacks as writing tends to be should take place on the image of a facsimile of a white piece paper.

In any case, you can always paste your draft into Word later.

A free and open-source (FOSS) alternative to MS Word: https://www.libreoffice.org/ ↩︎
https://en.wikipedia.org/wiki/Ted_Nelson ↩︎
https://en.m.wikipedia.org/wiki/Skeuomorph#Virtual_examples ↩︎
Do yourself a favor. ↩︎
https://en.wikipedia.org/wiki/Paper_size ↩︎

Textual Encounters of the Worthwhile Kind

Wed, 23 Jun 2021 22:07:00 +0300

Reading without taking notes is as good as not reading at all.

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

Think of the last text you read — a book, a chapter, an article, a blog post.

What do you remember about it?

What do you remember more clearly:

                    a) The text itself.
                    b) The circumstances in which you read it.
                    c) The feeling of accomplishment that came over you when you finished reading.

I, for one, do not remember the last book I read. (Or the last article, chapter, or blog post.)

Maybe I remember a title, a general topic, an author’s name — sometimes more.
But that one anecdote on such-and-such a page? The footnote with all the citations that seemed so promising? The statement of argument a third of the way through the introduction?

They’re gone. Like they never existed. And like we, therefore, never encountered each other.

But we did encounter each other…

So what was it all for?

—————

Whenever I am reading something that I find to be of significant moment — something compelling, inciting, good — I make a text file on my computer.

In that file, I take notes on whatever strikes me about what I am reading. Beside each note, I write a page number. It ends up looking something like this:

[40]: Crusoe arrives on the island.
[72]: RC can’t believe there’s corn growing.
[75]: Can we consider this an immaculate corn-ception?

Sometimes I type direct quotes from the text. But often I only describe, in a few words, what is being discussed on a given page: analysis of a primary or secondary source, discussion of a concept, definition of a key term.

Later when I need to recall some details about something I’ve read, I’ve got a clear and easily accessible record of my reading.¹

—————

What makes this process distinct, noteworthy, worthy of note? The following precept, which I try as hard as possible to adhere to:

Do not make any notes in the text itself.

That’s right. No underlining, no highlighting, no notes in the margins.

This is not in the interest of keeping a clean original document, digital or otherwise.

No — it is to prevent me from feeling like some work has been done when, in reality, no work has been done.

Underlining and highlighting feel great. They are easy. They feel like an accomplishment. But once you close a book or pdf, what do you have? Quickly fading memories.

Sure, you have books and pdfs full of marks. But to get to those marks, you’ll have to go back to the books/pdfs themselves — if you can find them.

And then, what do those marks really mean?

You’ll have to read the underlined/highlighted portions of text again in order to understand them.

And then, if you’re like me — and I assume you are — you will wonder half the time why you thought a passage was worth underlining/highlighting in the first place.

—————

Why do a lot of extra work later when you can do a little extra work now?

I know the answer to this question, of course. It’s because you’re the now you, and you don’t care about the later you, and all the work that they may or may not have to do. Let them figure it out.

They’re going to be so mad…

Where do I keep these notes? What kind of files are they? How do I title them? How do I search through them? What if I want to refer to another note? Or to another text? Questions, questions… ↩︎

The Wise Man of Švarco

Fri, 12 Feb 2021 16:24:00 -0500

There is a man who looks at me where I walk my dog in the park.

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

Near the French embassy, up the street from the university, he stands in a long black coat and hat, peering over a significant beard, maintained with care for decades, or so one can deduce from its stately sweep.

He is a painting on a wall. Less a mural or a portrait than an icon.

The wall marks the boundary of what was the Jewish ghetto in Vilnius, established during the Nazi occupation.¹

This representation, notably greater than life-size, is rendered in a stenciled style. It was placed here as a reminder of the kinds of lives that used to pass not just behind, through, around, and in front of walls like the one it appears on, but also—and perhaps most importantly—with no special regard for such things: unheeded and undetermined by the barriers such walls would become.

This painting—one of many in the area—has been given a nickname: “The Wise Man.” His arms are folded, his hands are tucked into opposing sleeves, his head is tilted knowingly. His posture is one of forbearance, as much as wisdom, or anything else. One feels suffered to look, but not to linger.

I pass him with the briefest acknowledgment and return home. He does not follow me.

—————

This man’s likeness, it turns out, was drawn from an archival photograph.²

Upon learning this, I started to feel whatever life, wisdom, forbearance, and otherwise that the painting purported to represent drain out of that static, flattened artifact.

What of the real man, himself? Did he live in this sector? Or in this city? Was he wise? Did he, in his life, stand for what he has been made to stand for, now? And how, and to whom, did he convey whatever wisdom he might might have possessed?

Of what is this painting a reminder? Perhaps only a reminder to remember — which may be enough, and plenty, for a given moment.³

For the record: https://en.wikipedia.org/wiki/Vilna_Ghetto ↩︎
I have opted not to include any photos here, though one should be easy to find, if not the other. The project behind this work is called “Sienos prisimena,” or “Walls that Remember.” ↩︎
A perhaps more thorough resource, if less public and immediate. ↩︎

About

Mon, 01 Jan 0001 00:00:00 +0000

This is the about page. It’s where you would find out what this page is about.

The posts here are written by me, about which more can be found there.

feed

Mon, 01 Jan 0001 00:00:00 +0000

Place

Mon, 01 Jan 0001 00:00:00 +0000

DONE

2025-09-26

DONE Ežerų Dugne

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

“But nature is a stranger yet”

— — — — —

on view at MO until March 30, 2025,
as part of an exhibition on solastalgia
—

DONE To Carve Something Meaningful

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

DONE Stendhal at Hand in Vilnius

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

Stendhal might have spent the night in a building near where I live.

There is a plaque on the wall of the building — a bookstore now, specializing in French literature — memorializing the night that Stendhal is said to have stayed there.

With its bilingual inscription and bas relief portrait of the artist, the plaque brings some kind of life to that corner, projecting a line clear to a far side of Europe.

Something of French culture once comforted itself here, if you can imagine.

—————

You’ll have to imagine.

The plaque does not cite its sources. It does not quote from the writer. It does not paint a picture of an event, a time, or a place.

ŠIAME NAME … BUVO APSISTOJES … STENDALIS

DANS CETTE MAISON STENDHAL … FIT ETAPE

Where would one look if one were inclined to dig up the truth of what may or may not have happened in this or another place at this or that time so many decades, centuries since?

But then, who would care to doubt these chiseled records?

—————

All told, the plaque is less a statement of fact than one of values.

“Draw this place closer, in your mind, to what you might already know well,” it says.

“Comfort yourself, that you are not so far away, so disconnected, as you thought—as you might have feared.”

—————

DONE The Wise Man of Švarco

There is a man who looks at me where I walk my dog in the park.

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

He is a painting on a wall. Less a mural or a portrait than an icon.

The wall marks the boundary of what was the Jewish ghetto in Vilnius, established during the Nazi occupation.³

I pass him with the briefest acknowledgment and return home. He does not follow me.

—————

This man’s likeness, it turns out, was drawn from an archival photograph.⁴

Upon learning this, I started to feel whatever life, wisdom, forbearance, and otherwise that the painting purported to represent drain out of that static, flattened artifact.

Of what is this painting a reminder? Perhaps only a reminder to remember — which may be enough, and plenty, for a given moment.⁵

Steven Hoelscher, “Place,” in The Wiley-Blackwell Companion to Human Geography, ed. John A. Agnew and James S. Duncan (Chichester, West Sussex: Malden, MA : Wiley-Blackwell, 2011), 256–57. ↩︎
Antanas Vaičiulaitis, “Stendhal in Lithuania,” trans. M. Vasiliauskas, Lituanus: Lithuanian Quarterly Journal of Arts and Sciences 22, no. 2 (1976). ↩︎
For the record: https://en.wikipedia.org/wiki/Vilna_Ghetto ↩︎
I have opted not to include any photos here, though one should be easy to find, if not the other. The project behind this work is called “Sienos prisimena,” or “Walls that Remember.” ↩︎
A perhaps more thorough resource, if less public and immediate. ↩︎

. 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'

Ežerų Dugne

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

To Carve Something Meaningful

"What should I read next?"

Notetaking: What are you after?

My Starting Points

The “Inbox” Note

The “Literature” Note

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

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

Chthonophagia

Citekeys: For Better Research / Life

Citekey Basics

Your Bibliographic Database

Key Rule: Be Consistent

Citekeys In Use

Bonus: PDF Management

Coracoid

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.

Stendhal at Hand in Vilnius

Drafting, Beyond MS Word

Textual Encounters of the Worthwhile Kind

The Wise Man of Švarco

About

feed

Place

DONE

DONE Ežerų Dugne

DONE To Carve Something Meaningful

DONE Stendhal at Hand in Vilnius

DONE The Wise Man of Švarco