› . local author .

: notes on place, literature, history, and method :

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.

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

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

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

“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


« Older posts
Page 1
Newer posts »