Posts with "Programming" tag on Take on Rules

Serializing Somewhat Large Emacs Alists

jeremy@takeonrules.com (Jeremy Friesen) — Tue, 23 Dec 2025 08:47:49 -0500

In my Mythic Bastionland Emacs package I’ve been populating an Emacs 📖 alist with information related to the state of the map for my Forged from the Worst campaign.

I have 14 top-level keys in that alist: barriers, curses, dwellings, escalations, hazards, holdings, known-hexes, locations, monuments, myth, omens-revealed, rivers, ruins, and sanctums. Most of those entries have 3 to 6 associated elements, with rivers, locations, and barriers having more.

Along the way, I found that when I went to persist the alist to a file, I was getting trailing ... characters in a few places. The process was truncating my data. Which meant data loss when I went to load the persisted alist.

No worries, due to the nature of the package, I could rebuild the map data and it would be true to the state of play (though the non-revealed information would be different). However, I wanted to solve this persistence issue.

I spent an evening searching and exploring the use of prin1 and (setopt eval-expression-print-level nil) but Emacs seemed to insist that when I went to print the full variable out, it would truncate.

So I set about writing out chunks of the data. Then reassembling those chunks.

Writing the Data Out in Chunks

Below is my mythic-bastionland-map-write function available at Sourcehut. What the code does is:

Create a feature called mythic-bastionland-map, which we’ll write as a loadable package.
For each association in the map:
- Chunk that data into groups of 8 and write each sub-group into a variable with name based on the association’s car and incremental suffix.
- Store those incremental variable names in another variable.
Store the name of each association’s car rendered in yet another variable.

(defun mythic-bastionland-map-write (&optional map)
  "Write the MAP into a re-loadable format.

Emacs is truncating things so I need to jump through some hoops."
  (setq mythic-bastionland-map (or map (mythic-bastionland-map)))
  (with-temp-buffer
    (let ((features nil))
      (insert ";;; mbm ---  -*- lexical-binding: t -*-\n")
      (cl-loop for (feature . values) in mythic-bastionland-map do
               (let (;; In my experience somewhere around 10 elements
                     ;; and we start seeing truncation.  So let's be
                     ;; under that.
                     (size 8)
                     ;; This will be a list of the variable names that,
                     ;; when reassembled, will be the values.
                     (segment-names nil))
                 (cl-pushnew feature features)
                 (dotimes (i (+ 1 (/ (length values) size)))
                   (let (;; Name of variable that will hold a segment
                         ;; of the values.
                         (segment-name
                          (format "mbm--data-%s-%d" feature i)))
                     ;; Track this segment's variable name.
                     (push (intern segment-name) segment-names)
                     ;; Grab a subset of values for this segment and
                     ;; store it in the variable with name that is the
                     ;; value of the segment.
                     (insert (format "(defvar %s '" segment-name))
                     ;; Yes yes, this is likely less effecient as I'm
                     ;; always reading the list.  But it was quick
                     (prin1 (seq-take
                             (nthcdr (* i size) values) size)
                            (current-buffer))
                     (insert ")\n")))
                 ;; Now track all of the segment names associated with
                 ;; this feature.
                 (insert (format "(defvar mbm--data-%s-list '" feature))
                 (prin1 segment-names (current-buffer))
                 (insert ")\n")))
      ;; Last track all feature names so we may reassemble them.
      (insert (format
               "(defvar mbm--features \"%s\")\n"
               (mapconcat (lambda (e) (format "%s" e))
                          features " "))))
    (insert "(provide 'mbm)\n"
            ";;; mythic-bastionland-map.el ends here\n")
    (write-file mythic-bastionland-map-state-file)))

Reading the Data Back In

I use the mythic-bastionland-map-read to reassemble that segmented data. When done I call (unload-feature 'mbm) to remove the fragmented variables, leaving only the mythic-bastionland-map variable.

(defun mythic-bastionland-map-read ()
  "Load the unduly complicated encoding of the map."
  (unless (f-file-p mythic-bastionland-map-state-file)
    (user-error "No file found at %s"
                mythic-bastionland-map-state-file))
  (require 'mbm mythic-bastionland-map-state-file)
  (let ((map nil))
    ;; Our serialized map has a variable mbm--map-features; we use that
    ;; to start our loading of data.
    (dolist (map-feature (s-split " " mbm--features))
      (let* ((values nil)
             ;; The name of each of the variables that houses a segment
             ;; of the feature's data.
             (segment-names
              (symbol-value
               (intern (format "mbm--data-%s-list" map-feature)))))
        (dolist (segment-name segment-names)
          (dolist (value (symbol-value segment-name))
            (cl-pushnew value values)))
        ;; Now that we've reassembled (in reverse order) the values for
        ;; this feature, add them to the underlying map.
        (cl-pushnew (cons (intern map-feature) values) map)))
    ;; With all features and their values loaded, we assign the map to
    ;; something more durable.
    (setq mythic-bastionland-map map))
  ;; And last clean up all those variables we used for reassembly.
  (unload-feature 'mbm))

Perhaps Another Way?

It seems a bit odd that this is how I could reliably read and write the data. And I’m open for other approaches. However, I felt it worth sharing this bespoke method as it might help others.

If you know of another way, please contact me.

Structured Data and Iterating

While working on my Mythic Bastionland Emacs package, I have been very pleased with the malleability of the alist, and their ease of testing; in part because of the Read-eval-print loop (REPL 📖) but also because of the nature of Lisp.

I can easily grab a portion of the syntax tree and reliably mash on that in the REPL . Think about other programming languages, if you want to use a portion of the inner logic of a function, what steps do you need to take to use it?

Due to the primacy of the alist there are fantastic functions for working with them.

Segmenting the data was a bit odd, I was hoping to simply dump the alist to a file. However, with the problems I encountered, I started exploring other options. Maybe write to JSON and load from JSON. But then I would’ve needed to establish a mechanism for describing that transformation.

Dec 23, 2025 update

Reader’s rallied and submitted some options. The following refactor works in place of the previous implementations.

(defun mythic-bastionland-map-write (&optional map)
  "Write the MAP into a re-loadable format."
  (setq mythic-bastionland-map (or map (mythic-bastionland-map)))
  (with-temp-buffer
    (let ((print-level nil)
          (print-length nil))
      (prin1 mythic-bastionland-map (current-buffer)))
    (write-file mythic-bastionland-map-state-file)))

(defun mythic-bastionland-map-read ()
  "Load the persisted map."
  (if-let ((file mythic-bastionland-map-state-file))
      (if (f-file-p file)
          (progn
            (setq mythic-bastionland-map
                  (read (with-temp-buffer
                          (insert-file-contents file)
                          (buffer-string))))
            (message "Loaded mythic-bastionland-map from %s" file))
        (user-error "No file found at %s"
                    mythic-bastionland-map-state-file))
    (user-error "'mythic-bastionland-state-file is nil")))

Extending Core Emacs Bookmark Package

jeremy@takeonrules.com (Jeremy Friesen) — Wed, 10 Dec 2025 21:01:36 -0500

Yesterday I wrote Extending Emacs to Play Mythic Bastionland and as I thought about it, I realized that I was coming very close to re-implementing bookmarks. What I had worked. But lacked the elegance of the bookmark ecosystem when adding to the PDF list.

And for those who took heart of what I did yesterday, read on, I found some bugs and fixed them.

So with time to think about it, I set about exploring how I might open a PDF to a random page (from a list of possible pages). Also, how I could capture that I want this bookmark to be a random page.

I also thought about how I might generalize my “starting and stopping” game play. After all, I have a few solo games that I might pick up.

Bookmarks

What follows almost completely replaces the previous implementation; except I don’t have a nifty re-roll a random table keybinding.

I had previously written a bookmark handler, so set about writing another one.

First, we should understand the structure of a PDF bookmark in Emacs 📖 :

 ("Tangled Seer"
(filename . "~/mythic=bastionland--core-rules__rules_systems.pdf")
(position . 1)
(last-modified 26934 62792 320522 78000)
(page . 104)
(slice)
(size . fit-page)
(origin 0.0 . 0.0)
(handler . pdf-view-bookmark-jump-handler))

The pdf-view-bookmark-jump-handler:random function first checks if there’s an associated pages value. If so, it picks one at random, sets the page value and passes it along to the pdf-view-bookmark-jump-handler.

  (defun pdf-view-bookmark-jump-handler:random (bmk)
    "A handler-function implementing interface for bookmark PDF BMK.

When the handler has a 'pages property, which is assumed to be a list,
pick one from that.  Otherwise fallack to the 'page property.

See also `pdf-view-bookmark-jump-handler' and
`pdf-view-bookmark-make-record'."
    (let ((pages
            (bookmark-prop-get bmk 'pages)))
      (bookmark-prop-set bmk 'page
        (or (seq-random-elt pages) (bookmark-prop-get bmk 'page)))
      (pdf-view-bookmark-jump-handler bmk)))

To test, I backed-up my bookmarks, and manually changed the handler to and added a pages attribute. I reloaded that file, and everything worked. Next, how could I avoid manually editing the file?don’t

I don’t want to always have my PDF bookmarks to be random tables. So I figured I would again repurpose the existing PDF bookmark making. This time with using an advising function.

First, I call the original pdf-view-bookmark-make-record; then if I have enabled 1) prompting for random pages and 2) said I want to specify the pages, then I prompt for the pages to use in randomization (yup, I had to manually enter those pages…or at least generate that list of pages programmatically, add it to the kill ring, then yank it into the prompt).

Once I had the list of pages, I change the handler from pdf-view-bookmark-jump-handler to pdf-view-bookmark-jump-handler:random. And returned the modified bookmark.

  (defun pdf-view-bookmark-make-record:with-randomizer (&rest app)
    "Conditionally randomize which page we'll open in a PDF.

See `pdf-view-bookmark-make-record:prompt-for-random'."
    (let ((bmk
            (apply app)))
      (if (and
            pdf-view-bookmark-make-record:prompt-for-random
            (yes-or-no-p "Specify Random Pages?"))
        (let* ((attributes
                (cdr bmk))
               (integers-as-string
                 (split-string
                   (read-string "Enter pages (comma-separated): "
                     (format "%s," (alist-get 'page attributes)))
                   "[,; ]+" t "[[:space:]]+")))
          ;; We clobber the existing handler replacing it with one of
          ;; our own devising.
          (setcdr (assoc 'handler attributes)
            'pdf-view-bookmark-jump-handler:random)
          (add-to-list 'attributes
            (cons 'pages
              (mapcar #'string-to-number integers-as-string)))
          ;; We need to return an object of the same form (e.g. a `cons'
          ;; cell).
          (cons (car bmk) attributes))
        bmk)))

  (advice-add #'pdf-view-bookmark-make-record
    :around #'pdf-view-bookmark-make-record:with-randomizer)

  (defvar pdf-view-bookmark-make-record:prompt-for-random
    nil
    "When non-nil, prompt as to whether or not to create a bookmark
that is randomization.")

Next, I wanted to continue popping those pages into a dedicated side window. Enter some more advice. This time, advising the bookmark-jump. Reading that implementation, I was surprised that the default wasn’t a variable; which might have made things easier.

(defvar default-bookmark-display-function
  nil
  "When non-nil, favor opening bookmarks with this function.")

(defun bookmark-jump-with-display (fn bookmark &optional display-func)
  (let ((display-func
          (or display-func
            default-bookmark-display-function
            (when current-prefix-arg 'switch-to-buffer-side-window))))
    (funcall fn bookmark display-func)))
(advice-add #'bookmark-jump :around #'bookmark-jump-with-display)

And last, a little bit of glamour. I visually show that the bookmark will be randomized by showing a the 6-face of a die with the word PDF.

;; Show that I'll be opening this PDF to a random page.
(put 'pdf-view-bookmark-jump-handler:random 'bookmark-handler-type "⚅PDF")

Starting and Stopping

With the new bookmark handling, I set about rethinking the implementation. As I needed to and unset more values, the lambda approach seemed cumbersome and repetitive. Also, in my experimentation, I wasn’t properly changing bookmarks files. The result was a steady appending to my default bookmarks.

What follows addresses that issue. First a variable of no significant insight.

(defvar playing-a-game nil
  "When non-nil, indicates that I'm playing a game.

See `playing-a-game-candidates' and `start-playing'.")

Next, I define what it means to start and stop playing my Forged from the Worst; using keywords.

(defvar playing-a-game-candidates
  `(
     ("Forged from the Worst (Mythic Bastionland)" .
       ((start .
          ((bmk-display-func . switch-to-buffer-side-window)
            (bmk-prompt-for-random . t)
            (bmk-file . "~/forged=from=the=worst--bookmarks.el")))
         (stop .
           ((bookmark-display-function . nil)))))
     )
  "Possible games I might be playing via Emacs.  A game you are playing
should have both a 'start' and 'stop' property.")

And then the function that prompts for the game played and applies the configuration; first stopping the previous game.

(defun start-playing (game)
  "Start playing the GAME; stopping any currently played game.

A GAME has a 'start' and 'stop' property, that is an alist.  That alist
has the following properties:

- 'bmk-file' :: what file we'll find our working bookmarks.
- 'bmk-display-func' :: the function we use to display bookmarks.
- 'bmk-prompt-for-random' :: if we'll prompt for possible random pages
  in PDF bookmarks.

When a property is not provided, \"suitable\" defaults are assigned."
  (interactive
    (list
      (let ((handle
              (completing-read "Start Playing: "
                playing-a-game-candidates nil t)))
        (alist-get handle playing-a-game-candidates nil nil #'string=))))
  ;; Stop playing what we were playing...if anything
  ;; Then start playing what we are playing...if anything
  (dolist (config (list playing-a-game (alist-get 'start game)))
    (when config
      (let ((file
              (or
                (alist-get 'bmk-file config)
                fallback-bookmark-file)))
        (setq default-bookmark-display-function
          (alist-get 'bmk-display-func config))
        (setq pdf-view-bookmark-make-record:prompt-for-random
          (alist-get 'bmk-prompt-for-random config))
        (bookmark-save)
        (setopt bookmark-default-file file)
        (bookmark-load file t nil t))))
  ;; Last register how to stop playing.
  (setq playing-a-game (alist-get 'stop game)))

And for symmetry and ease of thinking, I have added the related stop-playing.

(defun stop-playing ()
  "Stop playing a game."
  (interactive)
  (start-playing '("Nothing" . nil)))

Conclusion

Consolidating file lookup functions feels like the correct path. That is reduce the number of ways I’m opening up files. And extending existing functionality. Also learn a bit more about that implementation.

Extending Emacs to Play Mythic Bastionland

jeremy@takeonrules.com (Jeremy Friesen) — Tue, 09 Dec 2025 19:11:23 -0500

For playing Mythic Bastionland 📖 , I’ve been using or building out tooling. First, I’m leaning on my random-tables package. Next, while playing, I manually swapped out my baseline Emacs 📖 bookmarks for game specific bookmarks. Last, I began thinking about flipping to random PDF pages for inspiration.

Swapping Out Bookmarks

What I posted in Forged from the Worst: Session 1 worked, but I started thinking about how I might alter Emacs while running/playing the game. At first, this felt akin to turning on a minor mode. But the more I thought about it, it was more equivalent to using org-clock.

A quick brainstorm, and I realized that while playing:

I wanted different bookmarks.
Additional snippets (for my knight and squires name).
An indicator that I was playing the game.
And depending on how I organize my campaign world notes, maybe I’d start a clock on the headline associated with my world notes.

I haven’t yet implemented the world notes, but I have made adjustments for the others. Here’s what I have:

First, I establish a variable to track the state of “playing/not playing.”

(defvar playing-forged-from-the-worst nil
  "When non-nil, indicates that I'm playing Forged from the Worst.")

Then I created a command to toggle that on and off:

(defun toggle-forged-from-the-worst ()
  "Begin or end playing Forged from the Worst."
  (interactive)
  (load "jf-mythic-bastionland.el")
  (setq playing-forged-from-the-worst
    (not playing-forged-from-the-worst))
  (bookmark-load
    (if playing-forged-from-the-worst
      "~/SyncThings/source/forged-from-the-worst/forged=from=the=worst--bookmarks.el"
      "~/emacs-bookmarks.el")
    t nil t))

The command loads my random tables for the campaign. Toggles state. The loads the correct bookmarks based on state.

To indicate that I’m “playing”, I then added a variable that I could use with my modeline:

(defvar-local jf/mode-line-format/playing-fftw
    '(:eval
       (when (and (boundp playing-forged-from-the-worst)
               playing-forged-from-the-worst
               (mode-line-window-selected-p))
         (concat
           (propertize " 🎲 " 'face 'mode-line-highlight) " "))))

I add the variable into my mode-line-format:

(setq-default mode-line-format
    '("%e" " "
       jf/mode-line-format/timeclock
       jf/mode-line-format/org-clock
       jf/mode-line-format/vterm
       jf/mode-line-format/kbd-macro
       jf/mode-line-format/narrow
       jf/mode-line-format/playing-fftw
       jf/mode-line-format/buffer-name-and-status " "
       jf/mode-line-format/major-mode " "
       jf/mode-line-format/project " "
       jf/mode-line-format/vc-branch " "
       jf/mode-line-format/flymake " "
       jf/mode-line-format/eglot
       jf/mode-line-format/which-function
       ))

And ensure that I mark that variable as a risky-local-variable:

(dolist (construct '(
                        jf/mode-line-format/buffer-name-and-status
                        jf/mode-line-format/eglot
                        jf/mode-line-format/flymake
                        jf/mode-line-format/kbd-macro
                        jf/mode-line-format/playing-fftw
                        jf/mode-line-format/major-mode
                        jf/mode-line-format/misc-info
                        jf/mode-line-format/narrow
                        jf/mode-line-format/org-clock
                        jf/mode-line-format/timeclock
                        jf/mode-line-format/project
                        jf/mode-line-format/vc-branch
                        jf/mode-line-format/vterm
                        jf/mode-line-format/which-function
                        ))
    (put construct 'risky-local-variable t))

With that, when I’m playing the game, I see a little dice in my mode-line and have access to game specific bookmarks. That clock part is going to gnaw at me, so I assume I’ll work through that once I’ve published this post.

Flipping to Random PDF Page in Emacs

In Mythic Bastionland Session Reflection, I thought about the fact that I now had the PDF bookmarked and could quickly, I assume, access the oracular information at the bottom of the Knight/Seer and Myths pages.

My first pass was “what was the minimum viable command to open a random page in a PDF.” This involved reading the pdf-view-bookmark-jump-handler code and then setting about making it happen.

What I’m presenting is not the first nor second pass, but instead a third iteration that introduces a bit more utility. But I digress.

The algorithm I wanted was:

Prompt for whether I wanted a Seer/Knight or a Myth page.
Open the PDF in a dedicated window.
Go to a random page based on selection.

There are 72 Seer/Knight pages and 72 Myth pages. On a spread, the left page is a Seer/Knight and the right page is a Myth. The Seer/Knight starts on page 28.

The random function started as:

(+ (if seer-knight 28 29)
   (* (random 72) 2))

That is pick a number between 0 and 71, multiple that by 2, then add 28 or 29 depending on Seer/Knight or Myth.

I would then use find-file and in that buffer call pdf-view-goto-page. It was inelegant but was quick to verify general behavior.

Then I set about creating a better user experience. Below is the random-pages to choose from, and their relevant information of what file and how to pick a page.

(defvar random-pages
  '(("Knights/Seers" .
     (:file
      "~/Documents/RPGs/Mythic Bastionland/mythic=bastionland--core-rules__rules_systems.pdf"
      :callback
      (lambda () (pdf-view-goto-page (+ 28 (* (random 72) 2))))))
    ("Myths" .
     (:file
      "~/Documents/RPGs/Mythic Bastionland/mythic=bastionland--core-rules__rules_systems.pdf"
      :callback
      (lambda ()
        (pdf-view-goto-page (+ 29 (* (random 72) 2)))))))
  "An alist where `car' is the label and `cdr' is a plist with :file and
optional :callback.

We'll open the :file, then if a :callback is present, we'll run that
callback on the newly opened file.")

Next up is the function to open the random page in a dedicated window; with the happy little “bind g to pick a new random page.”

(defun random-page (&optional label set)
  "Open the file from SET with given LABEL.

SET is assumed to be an alist with `car' as the label and `cdr' a plist
with :file and :callback.  See `random-pages' for more information."
  (interactive)
  (let* ((set
           (or set random-pages))
          (label
           (or label
             (completing-read "Source: " set nil t)))
          (source
            (alist-get label set nil nil #'string=))
          (file
            (plist-get source :file))
          (display-buffer-mark-dedicated
            t)
          (buffer (or
                    (find-buffer-visiting file)
                    (find-file-noselect file))))
    ;; We'll pop open a dedicated side window with ample space for
    ;; viewing a new file.
    (pop-to-buffer buffer '((display-buffer-in-side-window)
                             (side . right)
                             (window-width 72)
                             (window-parameters
                               (tab-line-format . none)
                               (mode-line-format . none)
                               (no-delete-other-windows . t))))
    (with-current-buffer buffer
      ;; As a courtesy let's bind "g" to refresh re-invoke the
      ;; random-page using the same label.
      (local-set-key (kbd "g")
        (lambda () (interactive)
          (random-page label)))
      ;; I envision that not every random-page would have a callback.
      ;; Which highlights that perhaps the function name 'random-page'
      ;; is a misnomer based on my nascent understanding of what this
      ;; could be.
      (when-let ((callback
                   (plist-get source :callback)))
        (funcall callback)))))

What the above does is pop open a window on the right, with plenty of space to view the whole page. That window gets focus and I can close it q or re-roll with g. It also does the work to re-use a buffer if it already exists.

An animated GIF demontsrating the functions along with a list of commands called.

M-x consult-bookmark to show starting bookmarks.
M-x jf/mode-line-format/playing-fftw to start playing “Forged from the Worst.”
M-x consult-bookmark show a list of the game specific bookmarks.
M-x random-page REG Seer/Knight RET to pop open a random Knight/Seer page from the Mythic Bastionland rule book.
Then g a few times to pick a new random Knight/Seer page each time.

Conclusion

I love the virtuous cycle of playing a game, having a tool to support that game-play, and knowing that I can extend the tool to facilitate play. The result tends towards a generative feedback loop.

And both my during play moments of reflection as well as after play write-ups helped me consider what might be interesting to add to my tool chain. Which fed into exploring existing functionality and implementation to craft something just a bit new.

Now to think about my next session of Forged from the Worst. And attending to how I write up campaign notes while running. See what’s missing, maybe work and clocking time there. That would mean I’d have access to capture content to that clock, and could leverage more native Org-Mode 📖 functionality.

Managing Light/Dark Scheme in MacOS and Linux

jeremy@takeonrules.com (Jeremy Friesen) — Fri, 05 Dec 2025 21:04:34 -0500

On my personal machine I’m using Debian 📖 with the Gnome 📖 desktop. And my work machine runs MacOS. I have written an Emacs 📖 function (M-x jf/dark) that toggles between light and dark for either my personal machine or work machine. You can find the code up on Github.

First we have the general function (and associated alias for ease of typing):

(defun jf/color-scheme-system-toggle ()
  "Toggle system-wide Dark or Light setting."
  (interactive)
  (funcall
    (intern
      (format "jf/color-scheme-system-toggle:%s" system-type))))

(defalias 'jf/dark 'jf/color-scheme-system-toggle)

I’m opting to use a dispatch pattern, in which I dynamically construct the function name(s) to call based on the system-type variable. A disadvantage of this approach is that I’m defining functions for an Operating System (OS 📖) that is not relevant to the machine.

It would be simple to refactor, but for reasons of the example, I’ll keep them separate.

For themes I have the following:

(defvar jf/themes-plist
  '(:dark ef-owl :light ef-elea-light))

And I use the following command to set the theme based on the color scheme:

(defun jf/color-scheme:emacs (&optional given-scheme)
  "Function to load named theme."
  (let ((scheme
         (or given-scheme
             (funcall
              (intern
               (format "jf/color-scheme-func:%s" system-type))))))
    (modus-themes-select (plist-get jf/themes-plist scheme))))

For MacOS

I have the following:

(defun jf/color-scheme-system-toggle:darwin ()
  "Toggle the darwin system scheme."1’
  (shell-command
   (concat "osascript -e 'tell application \"System Events\" "
           "to tell appearance preferences "
           "to set dark mode to not dark mode'"))
  (jf/color-scheme-set-for-emacs))

To determine the MacOS color scheme:

(defun jf/color-scheme-func:darwin ()
  "Determine MacOS preferred/current theme."
  (if (equal "Dark"
             (substring
              (shell-command-to-string
               "defaults read -g AppleInterfaceStyle") 0 4))
      :dark :light))

For GNU/Linux with Gnome

The command for Linux and Gnome is as follows:

(defun jf/color-scheme-system-toggle:gnu/linux ()
  "Toggle the gnu/linux system scheme."
  (let* ((target_scheme
          (plist-get '(:dark :light :light :dark)
                     (jf/color-scheme-func:gnu/linux))))
    ;; Instead of all of the shelling out, we could assemble the shell
    ;; commands into a singular command and issue that.
    (dolist (setting jf/color-scheme-commands:gnu/linux)
      ;; In essence pipe the output to /dev/null
      (shell-command-to-string
       (format (plist-get setting :template)
               (plist-get setting target_scheme))))
    (jf/color-scheme:emacs target_scheme)))

The list of settings to change are as follows:

(defvar jf/color-scheme-system-toggle/gnome-settings
  '((:template "gsettings set org.gnome.settings-daemon.plugins.color night-light-enabled %s"
               :light "false" :dark "true")
    (:template "gsettings set org.gnome.desktop.interface color-scheme %s"
               :light "default" :dark "prefer-dark")
    (:template "gsettings set org.gnome.desktop.interface gtk-theme %s"
               :light "default" :dark "prefer-dark"))
  "A list of plists with three parts:

- :template :: command to run.
- :dark :: what the setting should be to be in \"dark\" mode.
- :light :: what the setting should be to be in \"light\" mode.")

To determine the current color scheme in Gnome:

(defun jf/color-scheme-func:gnu/linux ()
  "Determine Gnome preferred/current theme."
  (if (equal
        "'prefer-dark'"
        (s-trim
          (shell-command-to-string
            "gsettings get org.gnome.desktop.interface color-scheme")))
    :dark :light))

Automating Adding Books to My Org-Mode Document

jeremy@takeonrules.com (Jeremy Friesen) — Thu, 17 Apr 2025 17:41:43 -0400

The “Problem”

I have a lot of books and I want to keep track of what I “own.” I also have an Org-Mode 📖 document that has a set of books that I:

have highlighted one or more quotes
are on my shopping list
are books I’ve read or am reading

However, I didn’t really have a concept of “and I own this book.” To address that issue, I set about the process of using a mobile application to track books I owned.

However, that meant I had two conceptual sources of data. Ownership and “a book of interest” if you will.

The Spark

Yesterday I saw A Book Tracking Package for Emacs by Lars Ingebrigtsen. In that post Lars shares his book tracking solution. It involves a bar code scanner and Emacs 📖 .

Curious, I set about getting that code working. And with a few adjustments, namely ignoring playing audio files during workflow steps, I was able to get it working.

The Pivot

I spent a bit of time hacking on it, but paused as I considered that what I wanted was a different.

Namely, given an International Standard Book Number (ISBN 📖) , I wanted to get the associated book information and either add the book to my Org-Mode document or update the entry in that document.

Also, I myself had a bar-code scanner, and wanted to use that as the thing that typed the ISBN into the buffer. I also considered that I wanted to intervene during the workflow; namely once I had retrieved the book information from the ISBN , I needed to decide if I added the book or updated an existing entry.

Establishing a Workflow

Given that I needed to make a decision, I reconsidered my workflow. Namely, I would grab a pile of ten or so books, and scan their ISBNs into a buffer. Then, with that pile, I would reconcile each book.

The idea being two-fold:

It is a lot of fun to rapidly point and shoot a bar-code scanner.
Looking at a list of ISBNs with no other context doesn’t tell me much.

Therefore, build a manageable list of ISBNs then flip to the other task. Namely reconciling the remote information with what I have.

Implementation

I drew some inspiration from Lars’s isbn.el; but ultimately set about my own implementation. Let’s walk through that.

Defining the Structure

I defined the jf/book structure. I would use this to create a common mapping for the data retrieved via ISBN process and my bibliography.

(require 'request)
(require 's)

(cl-defstruct jf/book
  "A basic representation of a book as it relates to my personal
bibliography.

Slots:
- label:     Used for comparing to labels from my bibliography; expected
             to conform to `jf/book-make-label' function.
- title:     The ubiquitous human readable identifier of a work.
- author:    The author(s) of the book; separated by \" and \".
- subtitle:  Usually the words after the colon of a title.
- tags:      A list of tags for the book; these are internal values.
- isbn:      The ISBN for the given book.  One of the unique
             identifiers.
- custom_id: The `org-mode' headline CUSTOM_ID property, used for
             helping find the headline."
  label
  label
  title
  author
  subtitle
  tags
  isbn
  custom_id)

Caching That Which I Already Have

Given that I had an existing set of books already stored locally, I wanted to cache that information for processing multiple ISBNs . I use my-cache-of-books to store that information.

(defvar my-cache-of-books
  (make-hash-table :test 'equal)
  "We use this as a cache of my bibliography entries that are books,
reprsented as an alist, and for each pair the `car' is a
`jf/book-label' (as formated by `jf/book-make-label') and the `cdr'
being an instance of `jf/book'.

See `my-cache-of-books/populate' for details on populating
this structure.

Normally I'd prefix this kind thing with \"jf/\", however I like how
this variable reads.")

Avoiding Magic Strings

As a matter of practice, I tend to avoid using “magic strings”, instead favoring defined values.

(defconst jf/bibliography/tag-own
  "own"
  "The tag used to indicate ownership of a work.")

(defconst jf/bibliography/tag-books
  "books"
  "The tag used to indicate that a work is book.")

Populating the Cache

As I was working through adding a book via ISBN , I didn’t want to rebuild a list of all of my books. The my-cache-of-books/populate function handles this logic.

  (defun my-cache-of-books/populate (&optional clear-cache)
  "Populates `my-cache-of-books' with my current books.

When CLEAR-CACHE is non-nil, clobber the cache and rebuild."
  (when clear-cache (clrhash my-cache-of-books))
  (when (hash-table-empty-p my-cache-of-books)
    (save-excursion
      (with-current-buffer
          (find-file-noselect jf/filename/bibliography)
        (org-map-entries
         (lambda ()
           ;; For some reason the org-map-entries is not filtering
           ;; on only items tagged as books.  Hence the
           ;; conditional.
           (when-let* ((tags
                        (org-element-property
                         :tags (org-element-at-point)))
                       (_
                        (member jf/bibliography/tag-books tags)))
             (let* ((title
                     (org-element-property
                      :title (org-element-at-point)))
                    (author
                     (org-entry-get
                      (org-element-at-point) "AUTHOR"))
                    (subtitle
                     (org-entry-get
                      (org-element-at-point) "SUBTITLE"))
                    (label (jf/book-make-label
                            title subtitle author)))
               (puthash label
                        (make-jf/book
                         :label label
                         :tags tags
                         :title title
                         :subtitle subtitle
                         :author author
                         :custom_id (org-entry-get
                                     (org-element-at-point)
                                     "CUSTOM_ID")
                         :isbn (org-entry-get
                                (org-element-at-point)
                                "ISBN"))
                        my-cache-of-books))))
         (concat "+level=2+" jf/bibliography/tag-books) 'file))))
  my-cache-of-books)

Fetch a Book from an ISBN

In jf/book-from-isbn I convert the ISBN into a jf/book data structure.

(defun jf/book-from-isbn (isbn)
  "Fetch the associated ISBN from Google API and return a `jf/book'.

  TODO: Instead of returning the book, consider taking a function that
  operates on the book.  There would need to be an inversion of behavior."
  (let ((book nil))
    (request "https://www.googleapis.com/books/v1/volumes"
      :params (list (cons "q" (concat "isbn:" isbn)))
      :parser (lambda ()
                (let ((json-object-type 'plist))
                  (json-read)))
      :sync t
      :success (cl-function
                (lambda (&key data &allow-other-keys)
                  (let* ((item
                          (aref (plist-get data :items) 0))
                         (volumeInfo
                          (plist-get item :volumeInfo)))
                    (setq book
                          (let ((title
                                 (plist-get volumeInfo :title))
                                (subtitle
                                 (plist-get volumeInfo :subtitle))
                                (author
                                 (s-join " and "
                                         (plist-get
                                          volumeInfo :authors))))
                            (make-jf/book
                             :isbn isbn
                             :label (jf/book-make-label
                                     title subtitle author)
                             :tags (list
                                    jf/bibliography/tag-own
                                    jf/bibliography/tag-books)
                             :subtitle subtitle
                             :author author
                             :title title)))))))
    book))

Here I Enter the ISBN

In jf/add-to-bibliography function is the entry point into this workflow. As the docstring states, I use the function to: “Append or amend to my bibliography the book associated with the ISBN.”

It is also the function where I intervene, namely determining if the given book is already in my bibliography or not.

(defun jf/add-to-bibliography (isbn &optional clear-cache force)
  "Append or amend to my bibliography the book associated with the ISBN.

When CLEAR-CACHE is non-nil, clobber and rebuild `my-cache-of-books'.

When FORCE ignore already existing ISBN; a bit of a refresh."
  (interactive (list (read-string "ISBN: ")))
  (let ((books
         (my-cache-of-books/populate clear-cache)))
    (when (or force (not (my-cache-of-books/contains-isbn-p isbn)))
      (let* ((book-from-isbn
              (jf/book-from-isbn isbn))
             (completed-value
              (completing-read
               (format "Match %s: " (jf/book-label book-from-isbn))
               books nil nil
               ;; Maybe we'll get a direct hit?
               (jf/book-label book-from-isbn))))
        (if-let ((book-from-bibliography
                  (gethash completed-value books)))
            (jf/bibliography/update-book-via-merge
             book-from-bibliography
             book-from-isbn)
          (jf/bibliography/insert-book
           book-from-isbn))))))

Insert a Book

When the book I fetched via an ISBN is not in my Org-Mode file, the jf/bibliography/insert-book function inserts a record. The inline comments describe some false starts and the why of the solution.

Restating the comments, I use the Org-Mode capture ecosystem to perform the heavy lifting of adding a book entry to the document. Namely by using variable binding and then calling org-capture; an approach that felt as though I leveled-up in my understanding of what was possible.

(defun jf/bibliography/insert-book (book)
  "Insert BOOK into bibliography.

Where BOOK is a `jf/book' struct."
  ;; NOTE: My first incarnation was to use `org-capture-string' which
  ;; meant adding to `org-capture-templates' a conceptually \"private\"
  ;; capture template.  That incarnation used \"?\" as the template
  ;; body.  However, when I'd test the behavior, I was getting an empty
  ;; entry.
  ;;
  ;; Instead I deconstructed the concise `org-capture-string' and
  ;; shifted towards binding `kill-ring' and using the \"%c\" capture
  ;; variable.  I like this approach as it eschews adding a useless
  ;; capture template while leveraging the power of the `org-capture'
  ;; ecosystem.
  (let* ((kill-ring
          (list
           (concat (jf/book-title book)
                   " :" (s-join ":" (jf/book-tags book)) ":\n"
                   ":PROPERTIES:\n"
                   ":CUSTOM_ID: "
                   (jf/denote-sluggify-title (jf/book-label book)) "\n"
                   (when (s-present? (jf/book-subtitle book))
                     (concat ":SUBTITLE: "
                             (jf/book-subtitle book) "\n"))
                   (when (s-present? (jf/book-author book))
                     (concat ":AUTHOR: " (jf/book-author book) "\n"))
                   ":ISBN: " (jf/book-isbn book) "\n"
                   ":END:\n")))
         (org-capture-entry
          '("B" "Book from ISBN Lookup"
            entry (file+headline jf/filename/bibliography "Works")
            "%c"
            :immediate-finish t)))
    (org-capture)
    (puthash (jf/book-label book) book my-cache-of-books)
    (message "Appended %s to bibliography" (jf/book-label book))))

Update a Book

When the book I fetched via an ISBN is in my Org-Mode file, the jf/bibliography/update-via-merge function merges and updates the document.

In essence, this is about finding the CUSTOM_ID and adding the own tag and ISBN to the book.

(defun jf/bibliography/update-via-merge (from-bibliography from-isbn)
  "Update a book FROM-BIBLIOGRAPHY with FROM-ISBN information.

Where both FROM-BIBLIOGRAPHY and FROM-ISBN are `jf/book' structs."
  (setf (jf/book-isbn from-bibliography) (jf/book-isbn from-isbn))
  (setf (jf/book-tags from-bibliography)
        (sort (seq-union
               (jf/book-tags from-bibliography)
               (jf/book-tags from-isbn)
               #'string=)))
  (save-restriction
    (widen)
    (save-excursion
      (with-current-buffer
          (find-file-noselect jf/filename/bibliography)
        (org-map-entries
         (lambda ()
           (let ((hl (org-element-at-point)))
             (when (string=
                    (org-entry-get hl "CUSTOM_ID")
                    (jf/book-custom_id from-bibliography))
               (progn
                 (org-set-property "ISBN"
                                   (jf/book-isbn from-bibliography))
                 (org-set-tags
                  (jf/book-tags from-bibliography))
                 (save-buffer)))))
         (concat "+" jf/bibliography/tag-books 'file))
        (message "Updated %s with ISBN %s"
                 (jf/book-label from-bibliography)
                 (jf/book-isbn from-bibliography))))))

Next Steps

In writing this, I’m thinking of a few next steps. There’s a TODO item in my docstring. Namely to refactor jf/book-from-isbn. Instead of returning a jf/book, I would pass a function which would receive a jf/book. I’d call that function on success.

Why consider that refactor? It touches back on that mobile application. I have already scanned 80 or so books. And I can export that application’s data and feed that into my process. I wouldn’t need to call the Google function but instead develop the method for creating a jf/book structure from that exported data.

And you may ask, where’s the code? It is a bit in flux. In part because I realized how trivial these next steps were. And I have this bar code scanner that demands I start “shooting books.”

Conclusion

With this new functionality, I’ve been able to add more functionality into my “bibliography.” It now serves as:

A repository of quotes associated with their source
A shopping list
A reading tracker
An inventory of my currently owned books

All in a rich, yet structured, format.

Further, the resulting workflow and functions helps me “chunk my work”, making it easier to review without simply mashing “accept.”

Postscript

I used the Emacs Read-eval-print loop (REPL 📖) to iterate on the solution. And all of the code was in my Bibliography file; usable via Org-Mode ’s tangle process.

Why do I mention this?

I found myself first writing prose, and thinking through Lars’ solution and how I might modify or extend that implementation in relation to the problem as I understood it.

Extending consult-notes Package to Add Draft Blog Post Candidates

jeremy@takeonrules.com (Jeremy Friesen) — Fri, 11 Apr 2025 16:56:13 -0400

Introduction

I’m provisionally using the consult-notes package to provide find and search functionality for the notes I write using Denote 📖 . I write provisionally as I want to explore its utility relative to other things (such as the consult-denote package.

But that is not why I’m writing this post, instead I’m writing to draw attention to an approach I took at re-using implementation details in Emacs 📖 in a way that is different from other languages. Namely scoped variable binding.

I find this important as it is a conceptually different approach from every other programming languages I’ve used (e.g., Ruby, Python, Javascript, PHP, Basic, etc.)

Let’s dig in.

Consult Notes Denote Implementation

The consult-notes-denote–source is defined as follows. Importantly, the :items property is a chunky lambda. (Sidenote: By default, I’m hiding the following code, as it is a lot to read through.)

Implementation of the consult-notes-denote--source constant.

(defconst consult-notes-denote--source
  (list :name     (propertize "Denote notes" 'face 'consult-notes-sep)
        :narrow   ?d
        :category consult-notes-category
        :annotate consult-notes-denote-annotate-function
        :items    (lambda ()
                    (let* ((max-width 0)
                           (cands (mapcar (lambda (f)
                                            (let* ((id (denote-retrieve-filename-identifier f))
                                                   (title-1 (or (denote-retrieve-title-value f (denote-filetype-heuristics f)) (denote-retrieve-filename-title f)))
                                                   (title (if consult-notes-denote-display-id
                                                              (concat id " " title-1)
                                                            title-1))
                                                   (dir (file-relative-name (file-name-directory f) denote-directory))
                                                   (keywords (denote-extract-keywords-from-path f)))
                                              (let ((current-width (string-width title)))
                                                (when (> current-width max-width)
                                                  (setq max-width (+ consult-notes-denote-title-margin current-width))))
                                              (propertize title 'denote-path f 'denote-keywords keywords)))
                                          (funcall consult-notes-denote-files-function))))
                      (mapcar (lambda (c)
                                (let* ((keywords (get-text-property 0 'denote-keywords c))
                                       (path (get-text-property 0 'denote-path c))
                                       (dirs (directory-file-name (file-relative-name (file-name-directory path) denote-directory))))
                                  (concat c
                                          ;; align keywords
                                          (propertize " " 'display `(space :align-to (+ left ,(+ 2 max-width))))
                                          (propertize (funcall consult-notes-denote-display-keywords-function keywords) 'face 'consult-notes-name)
                                          (when consult-notes-denote-dir
                                            (propertize (funcall consult-notes-denote-display-dir-function dirs) 'face 'consult-notes-name)))))
                              cands)))
        ;; Custom preview
        :state  #'consult-notes-denote--state
        ;; Create new note on match fail
        :new     #'consult-notes-denote--new-note))

I wanted to re-use the implementation details of the :items property, but specify my own consult-notes-denote-files-function. Namely one that would create a candidate list of all denote notes tagged with blogPosts but did not have an associated published URL; which in my case is a note lacking a ROAM_REFS property.

Custom Candidate Function for Draft Blog Posts

In a shell, I can query for draft blog posts as follows:

fd "_blogPosts.*\.org" /path/to/denote/dir | xargs rg "^#\+ROAM_REFS:" \
--ignore-case --files-without-match --sortr modified

Let’s break that down:

Use fd 📖 to find denote name conformant Org-Mode 📖 files with the tag blogPosts.
Pipe those files to Ripgrep 📖 selecting from that file list files that do not have a line starting with #+ROAM_REFS:.

Re-Using the Existing

My first implementation copied the logic of consult-notes-denote--source. However, that was a lot of duplicate logic. I set about what it would take to re-use much of that logic.

The following, with code available on Github, is what I settled:

(use-package consult-notes
  :config
  (require 'consult-notes-denote)
  ;; Add a draft blog post section to my consult notes.
  (add-to-list 'consult-notes-all-sources
    `(:name ,(propertize "Draft Blog Posts" 'face 'consult-notes-sep)
       :narrow ?D
       :cateogry consult-notes-category
       :items jf/consult-notes/draft-blog-posts/items
       :state  consult-notes-denote--state))
  (defun jf/consult-notes/draft-blog-posts/items ()
    "Return a propertized list of draft blog posts.

The `consult-notes-denote--source' :items value has most all of the
logic I want (encoded as a `lambda').  However, I want to provide my own
files used in generating the candidates; this is done by way of a
contextual override of `consult-notes-denote-files-function'.

By convention, a draft blog post is one that is tagged with blogPosts
but does not yet have a ROAM_REFS property (meaning I have not
associated the org-mode document with the corresponding published URL of
the document)."
    (let ((consult-notes-denote-files-function
            (lambda ()
              (split-string-and-unquote
                (shell-command-to-string
                  ;; First narrow to files with tags
                  (concat
                    "fd \"_" jf/denote/keywords/blogPosts ".*\\."
                    (symbol-name denote-file-type) "\" "
                    (denote-directory) " | "
                    "xargs rg \"^#\\+ROAM_REFS:\" -i --files-without-match --sortr modified"))
                "\n"))))
      (funcall (plist-get consult-notes-denote--source :items)))))

First, instead of my :items having that chunky lambda, I specified a function (e.g. jf/consult-notes/draft-blog-posts/items). For the context of that function’s evaluation it overwrote the definition of consult-notes-denote-files-function. Then within that context called the :items property function stored in consult-notes-denote--source.

The docstring of jf/consult-notes/draft-blog-posts/items contains much of the relevant information.

Today’s implementation might look “chunky” but much of it is defining the overriding function. Below is a theoretical refactoring that might further clarify what is happening:

(defun jf/consult-notes/draft-blog-posts/items ()
  (let ((consult-notes-denote-files-function
         #'jf/consult-notes/draft-blog-posts/files-function))
    (funcall (plist-get consult-notes-denote--source :items))))

Alternatives?

I consider this somewhat magical coming from most other languages. I might be able to accomplish this in Ruby 📖 , but this would likely not be feasible in any other languages in which I’ve worked.

Other languages might require that I pass the consult-notes-denote-files-function as a parameter (either directly or by way of a property on a scoping context).

However the variable scoping meant that I:

could re-use code
didn’t need to submit a pull request

Conclusion

I wanted to have a function to find my draft blog posts. I also wanted to minimize duplicate effort. I could’ve used the underlying completing-read to do this lookup, but I also wanted to explore tying into a package I have been using.

And in tying into that usage, I am encouraging myself to use the package and make sure it is something I want to keep; or jettison and favor something else.

Extending Org-Mode Export to Include Acronyms Section

jeremy@takeonrules.com (Jeremy Friesen) — Thu, 10 Apr 2025 22:41:49 -0400

Introduction

In Denote Emacs Configuration I wrote about adding abbr and abbr-plural link types. In short, when I exported these link types the process would render an abbreviation and its title, based on my glossary entries. At least that’s what they did for Hypertext Markup Language (HTML 📖) and plain text.

But until today, I had deferred on handling the LaTeX export. There was a rudimentary handling of it, but I figured I could do more. So I did.

Abbreviations on My Blog

First, I want to share how I handle this for my blog, as its different from other export backends.

I write my blog posts in Org-Mode 📖 and use Ox-Hugo 📖 to export into a Markdown format.

When exporting for my blog, I pass all of the acronyms through a custom my glossary Hugo 📖 short-code. (Sidenote: See Github for my glossary short-code implementation; warning this is a complicated short-code that I don’t want to touch.) During the processing, the first time I encounter a glossary entry, I render the title/name and its abbreviation. After that I use the abbr HTML tag.

Extending LaTeX Export

For LaTeX 📖 exports and thus generating Portable Document Formats (PDFs 📖) I would like similar behavior as my blog.

I had found How to generate list of abbreviations in LaTeX? (from the LaTeX Stack Exchange); which demonstrates using one of two LaTeX packages:

acro: declare the acronyms in the header and then reference throughout.
acronym: explicitly render the acronymes in their own section.

Due to my initial approach and understanding, I went with the acronym package.

Let’s look at the code changes I made. (Sidenote: Here’s the Github commit that shows the totality of changes.) There are four steps:

In summary, these described changes append a section named “List of Acronyms” that assist in untangling the acronyms I’ve used within the document.

Let’s dive in.

Register an Encountered Abbreviation

I was already handling abbreviations in LaTeX ; though they were somewhat broken in that I was rendering the associated name/title of the item.

Based on my read through of the Stack exchange suggestions, I wanted to add to a list of abbreviations I’d encountered. (Sidenote: I suppose I could’ve generated a full list of abbreviations for each LaTeX
export, but I have 400+ abbreviations and that seemed rather gross and excessive.
)

I added the following comments and code to my jf/denote/link-ol-abbr-with-property function.

;; When we encounter an abbreviation, add that to the list.  We'll
;; later use that list to build a localized abbreviation element.
(let ((abbr-links
        (plist-get info :abbr-links)))
  (unless (alist-get keyword-value abbr-links nil nil #'string=)
    (progn
      (add-to-list 'abbr-links (cons keyword-value title))
      (plist-put info :abbr-links abbr-links))))

With this, each time I encounter an abbreviation, I make not of it for later processing. The note includes the abbreviation key and its title (e.g. “PDF” and “Portable Document Format”).

Note: Based on my debugging, there is a caching layer that minimizes calls to this function. That is, we will only call the link generating function once for a given link (where the link identity is the key and description).

Conditionally Render an Acronym Section

The jf/ox/filter-body/latex function checks if we’ve encountered abbreviations. If so we append to the body of the document each encountered abbreviation (sorted alphabetically) along with its descriptive “title.”

(defun jf/ox/filter-body/latex (body backend info)
  "Conditionally add a list of acronyms to the exported LaTeX document.

To have a meaningful render, this requires using the acronym LaTeX
package.  The `jf/ox/filter-final-output/latex' handles injecting that
LaTeX package."
  (if-let ((abbr-links (plist-get info :abbr-links)))
    ;; We encountered some links, let's add a section.
    (progn
      (concat
        body
        "\n\\section{List of Acronyms}\n"
        "\\begin{acronym}\n"
        (mapconcat
          (lambda (cell)
            "Create an acro for link."
            (format "\\acro{%s}{%s}" (car cell) (cdr cell)))
          ;; Sort the keys alphabetically.  Otherwise they are rendered
          ;; in the reverse order in which they are encountered.
          (sort abbr-links :key #'car)
          "\n")
        "\n\\end{acronym}\n"))
    body))

In this case the body parameter is the inner-content of the eventual LaTeX document. It does not contain the header information nor the closing \end{document}.

Conditionally Use the Acronym Package

The purpose of this step is to ensure that we have are using the acronym LaTeX package. I could’ve updated all of my class declarations, but opted for this route.

The jf/ox/filter-final-output/latex function injects the acronym package into the final LaTeX document.

(defun jf/ox/filter-final-output/latex (body backend info)
  "Conditionally add an acronym package to exported LaTeX document."
  (if-let ((abbr-links (plist-get info :abbr-links)))
    (replace-regexp-in-string
      "^\\\\documentclass\\(.*\\)"
      (lambda (md)
        "Acronym package to matching line."
        (concat "\\\\documentclass" (match-string 1 md)
          "\n\\\\usepackage[printonlyused,withpage]{acronym}"))
      body)
    body))

In this context, the body parameter is the totality of content we will write to the interstitial tex file. That is it contains the LaTeX header information as well as the begin and end blocks.

I’m not enamored with using a regular expression, and might tinker with this a bit more.

Add Export Handling Functions

None of the above matters, until I append these filters to my LaTeX export.

The jf/org-export-change-options function and adding to the org-export-filter-options-functions ensures that we call the functions that conditionally render an acronym section and conditionally use the acronym package.

(defun jf/org-export-change-options (plist backend)
  "Conditinally add filter functions to our org-export."
  (cond
   ((equal backend 'latex)
    (if-let ((filter-body
              (plist-get plist :filter-body)))
        (progn
          (add-to-list 'filter-body jf/ox/filter-body/latex)
          (plist-put plist :filter-body filter-body))
      (plist-put plist :filter-body '(jf/ox/filter-body/latex)))
    (if-let ((filter-final-output
              (plist-get plist :filter-final-output)))
        (progn
          (add-to-list 'filter-final-output jf/ox/filter-final-output/latex)
          (plist-put plist :filter-final-output filter-final-output))
      (plist-put plist :filter-final-output '(jf/ox/filter-final-output/latex)))))
  plist)

(add-to-list 'org-export-filter-options-functions
             'jf/org-export-change-options)

The code is a bit chatty, but I wanted to ensure that I did not clobber other filter functions; instead appending to the list of possible filters.

A Bit of How I Got There

While working towards this solutions, I took a few different pathways. Ultimately, I leveraged the Emacs 📖 debugger and inline documentation of the ox package: the Org-Mode export “framework” package.

I allude to the revelatory moment in the change of the jf/denote/link-ol-abbr-with-property parameter name and doc string; changing the parameter name from protocol to info. I had carried protocol over from some other implementation; but a bit of debugging showed me that this was very much the information channel shared throughout the export.

With that knowledge, I added to the info parameter and set about finding a meaningful place to check the content.

It became a matter of reading through some source code to see how I might apply filters; something I knew existed based on previous reads of the ox package.

Why This “Vanity Project”?

Using a glossary of abbreviations is an endeavor that started with a two-fold goal:

And a third goal that has emerged over time: Untangling the Acronyms Used At Work.

Registering as Back-Links

When I was writing my posts in Markdown and directly into my Hugo project, I established back-link capabilities for glossary items. As I moved to Org-Mode for writing and first Org-Roam 📖 and then Denote 📖 , I wanted to continue to have access to back-links.

And since my abbr and abbr-plural conform to Denote ’s linking schema; using an abbreviation link registers as a back-link. Which means later on I can easily find written references to those glossary terms.

Initial Descriptions of Abbreviations

We live in a world of acronyms. Consider the three letters `RPG`:

Rocket Propelled Grenade
Role-Playing Game
Report Program Generator

All of those are terms I’ve used when I’ve typed or spoken `RPG`.

When blogging about role-playing games, I don’t want to keep writing “Role-Playing Game” over and over. I want to use the abbreviation. But the first time I introduce an abbreviation, I want to provide the full name.

In using that strategy, I hope I’m improving the accessibility of my writing. Helping the reader acclimate to the terms I’m using, while also not maintaining a verbosity that might be off-putting for readers familiar with the domain.

Untangling the Acronyms Used At Work

Since I started blogging, I have changed jobs four times. I have joined:

An academic library
An early stage start-up
A software consultancy
A new-to-me tech domain of product development/engineering

At each of these, management and other folks would use new-to-me terms. Each time, I’d clarify then write down the acronym and its “title”.

This helped me remember what we were chattering about. And in some cases, depending on the documentation maturity of the organization, I’d contribute my glossary terms back to the organization’s glossary; or my team’s glossary.

Conclusion

Given that I write via Org-Mode documents for different audiences and that I have a glossary of abbreviated terms, I think it is useful to share at least a bit about that term.

For the future, I did note that the acronym package allows for me to include a description as a third parameter to rendering the list. My glossary also includes descriptions, so at some point, I’m certain I’ll be adding that to my LaTeX output.

Tending to my Writing Ecosystem and Existing Notes

jeremy@takeonrules.com (Jeremy Friesen) — Wed, 09 Apr 2025 22:05:18 -0400

Last night I took some time to re-work my Denote 📖 structure.

Why the Re-Work?

In part I wanted to move past a pinned version of Denote ; as I had found a behavior change that introduced enough chaos in my workflow that I chose to stick with a known version.

The observed problem with my pinned version was in back-links. (Sidenote: I think there might have been another reason for pinning, but that reason is lost to me (and maybe in my Git 📖 commit history).)

Namely, Denote would find back-links, but in my version the link to those files would point to a missing file; in that the domain was treated as a sub-folder of the current note. This was not ideal, as it would mean if I followed that I’d create a new file (with the same identifier as the back-linking note).

Related to that problem was my using of an early concept of Denote Silos. I wrote about my domains of Denote in Denote Emacs Configuration. The idea of the domains was that some of my notes would travel a bit; that is my glossary would be on multiple machines, either personal or owned by my employer.

Each domain was its own git repository, allowing for synchronization between machines.

However, I decided to excise my glossary from my work machine. The shared glossary was not as useful as I thought. Which was the linchpin that held the functional need for a domain; and in removing it, the need collapsed.

With the need collapsed, I looked towards a simplification.

Towards Simplification

My plan: move all notes into the same directory. But I wanted this change to be reversible.

For each file in a domain, I added the domain as a tag to that file. I used dired and Denote ’s denote-dired-rename-marked-files-add-keywords function to apply those tags.

Once I had tagged each file, I again used dired to move those files out of the domain and into the general bucket.

I removed my domain macro and calls to that macro. With the domain macro gone, I went hunting for unused code. And tidied up how I exported a blog post from Org-Mode 📖 . (Sidenote: The Github commit 6a8bbb52493db975ab8d13b4749b474ba7ee3368 contains the changes.)

I did some quick and dirty testing, and things worked. The tags served a similar function as the domains.

Tapping into a Habit

Previously, to create a blog post, I would M-x jf/denote/create--blog-post, which I bound to H-d c b. Since creating that domain macro, I started writing a daily journal. This used an org-capture-template. And had become a habit I was sustaining. (Sidenote: See Molding Emacs to Reinforce Habits I Want to Develop for more on this habit feedback loop.)

I spent some time today creating capture templates for these previous domains. The benefit: the preliminary command I use for my note-taking habit is now the same preliminary command for composing a blog post and making a glossary entry.

Let’s look first at my Blog Post org-capture-template:

(add-to-list 'org-capture-templates
  '("b" "Blog Post"
     plain (file denote-last-path)
     (function
       (lambda ()
         (let* ((denote-use-title
                  ;; If I don't provide the title, then it'll use the
                  ;; active region as the title, and failing that list
                  ;; previous titles I've used from which to select.
                  ;; With this let clause, I'm asking for a clean title.
                  (read-string "Blog Post Title: "))
                 (denote-use-keywords
                  `(,jf/denote/keywords/blogPosts))
                 (denote-org-capture-specifiers
                   ;; When I am capturing with an active region, use the
                   ;; capture wrap; that is bring the highlighted region
                   ;; along.  Else, when I'm not capturing with an
                   ;; active region, just prompt to start writing.
                   (if (use-region-p)
                     "%(jf/denote/capture-wrap :link \"%L\" :content \"%i\")"
                     "")))
           (denote-org-capture))))
     :no-save t
     :immediate-finish nil
     :kill-buffer t
     :jump-to-captured t))

I wrote this following the “Create note using Org capture” of the Denote Manual.

I prompt for the title, set the keywords to blogPosts and have a conditional specifier. Namely, if I have a highlighted region when I invoke the capture, use that region as the baseline for the body. (Sidenote: I wrote about this in Refining My Quotation Capture Process.)

Now let’s look at my Glossary Entry org capture template:

(add-to-list 'org-capture-templates
'("g" "Glossary Entry"
   plain (file denote-last-path)
   (function
     (lambda ()
       ;; (setq-local keywords (list))
       (let* ((keywords
                `(,jf/denote/keywords/glossary))
               (title
                (read-string "Glossary Entry Title: "))
               (is-a-game
                 (yes-or-no-p "Is this a game?"))
               (is-a-tag
                 (yes-or-no-p "Is a tag for Take on Rules?"))
               (abbr
                 (read-from-minibuffer "Abbreviation (empty to skip): "))
               (key
                 (downcase (denote-sluggify-title title))))
         (when is-a-game
           (add-to-list 'keywords jf/denote/keywords/games))
         (when (s-present? abbr)
           (add-to-list 'keywords jf/denote/keywords/abbr))
         (let* ((denote-use-title
                  title)
                 (denote-use-template
                   (concat
                     "#+GLOSSARY_KEY: " key "\n"
                     (when (s-present? abbr)
                       (concat "#+ABBR: " abbr "\n"))
                     (when is-a-game
                       (concat "#+GAME: " key "\n"))
                     (when (s-present? abbr)
                       (concat
                         "#+PLURAL_ABBR: %^{Plural Abbr|" abbr "s}\n"
                         "#+PLURAL_TITLE: %^{Plural Title|" title "s}\n"))
                     (when is-a-tag
                       (concat "#+TAG: " key "\n"))))
                 (denote-use-signature
                   (when (s-present? abbr)
                     (denote-sluggify-signature abbr)))
                 (denote-use-keywords
                   keywords)
                 (denote-org-capture-specifiers
                   "%?"))
           (denote-org-capture)))))
   :no-save t
   :immediate-finish nil
   :kill-buffer t
   :jump-to-captured t))

This one is far more complicated, in part because my Glossary does a lot of work:

Defines what terms are abbreviations
If and when those abbreviations are plural
Whether or not the entry is a game
Whether or not the entry represents a tag I use for blogging
And some other stuff not captured in this capture template (e.g. when relevant, the URL(s) of the named item).

When I capture a Glossary Entry, I prompt for the relevant information and then build a conformant file.

What Are My Personal Capture Templates

With these changes, my personal capture templates are as follows:

b Blog Post: start writing a blog post (as mentioned above).
c Content Clock: capture the highlighted region to the currently clocking headline.
d Dictionary: write to my personal dictionary of discovered words.
g Glossary Entry: create a glossary entry (as mentioned above).
j Journal Entry: go to “today”, and insert a time stamp and position to just start writing. These are personal thoughts. And ones that I am comfortable printing and keeping in my house.
p Person to Quote: name a person whom I’m likely to quote; this ties into my Refining My Personal Bibliography and Epigraph Process.
q Quote: associate a quote with a source (person or work).
r Add to RSS Feed: add an item to my RSS feed; in writing this I think I should always assign the tag “provisional”.
t Task: add a task to my journal.
v Add to Today’s Private Thoughts: My journal is personal, but sometimes I have private thoughts I want to work through. These are elements I won’t print out; I haven’t used this much and consider it on probation.
w Work: a named work (e.g. a book, a song, an essay, a blog post). Used to provide context for a quote as well as manage my “shopping list” (as written about in Extending My Bibliography for an On The Go “Shopping List”)

Conclusion

My Emacs 📖 environment is a personal hobby that supports my professional, authorial, and thinking life. Seeing functional needs diminish and adjacent technical problems bubble up was my impetus to explore.

I did so with a reversible mindset, and the end result is that I merged past paradigms into a current working paradigm.

Adding Actionable Indicators to my Emacs Mode Line

jeremy@takeonrules.com (Jeremy Friesen) — Tue, 08 Apr 2025 22:07:48 -0400

I’ve long used the Typopunct Emacs package for things like “smart quotes”, em-dashes, and en-dashes. I eschew rendering minor modes in my mode-line, as this is chatty and not very helpful.

However, I often find myself toggling typopunct-mode on and off. Which prompted me to explore adding an indicator to the mode-line.

Before the Change

First, lets look at the current anatomy of my mode-line. It’s rather compact; though the buffer name, branch name, and function name can make for quite a bit of text.

While writing this document, the following is my mode-line text:

Adding Actionable Indicators to my Emacs Mode Line ¶ “Org” blog-posts  main ⨍ := Before the Change

Let’s break this down a bit:

Adding Actionable Indicators to my Emacs Mode Line: the buffer name.
¶ indicates I’m in a text-mode.
”Org” indicates the major mode is Org-Mode 📖 , and as this is wrapped in quotes means that I’ve activated typopunct-mode for this buffer.
blog-posts is the name of the projectile project.
 main indicates that the version control branch is main.
⨍ := Before the Change is the name of the “function” that contains point. In Org-Mode , that is the containing headline for point.

My mode-line conveys more conditional information, so lets look to my mode-line-format. (Sidenote: See Github for more context regarding mode-line-format.)

(setq-default mode-line-format
    '("%e" " "
       jf/mode-line-format/org-clock
       jf/mode-line-format/vterm
       jf/mode-line-format/kbd-macro
       jf/mode-line-format/narrow
       jf/mode-line-format/buffer-name-and-status " "
       jf/mode-line-format/major-mode " "
       jf/mode-line-format/project " "
       jf/mode-line-format/vc-branch " "
       jf/mode-line-format/flymake " "
       jf/mode-line-format/eglot
       jf/mode-line-format/which-function
       ))

jf/mode-line-format/org-clock: Show an indicator when I have an active Org-Mode clock.
jf/mode-line-format/vterm: Show when I’m run vterm (and allow me to quickly toggle copy mode).
jf/mode-line-format/kbd-macro: Indicate when I’m recording a keyboard macro.
jf/mode-line-format/narrow: Indicate when I’ve narrowed the buffer.
jf/mode-line-format/buffer-name-and-status: The name of the buffer and whether its read-only or not.
jf/mode-line-format/major-mode: Indicate the major-mode as well as its type (e.g. programming mode, text mode, etc).
jf/mode-line-format/project: What, if any, is the projectile project name.
jf/mode-line-format/vc-branch: What, if any, is the version control branch. I can click on it to see the Magit 📖 status.
jf/mode-line-format/flymake: When Flymake is active, show its information.
jf/mode-line-format/eglot: When eglot is active, show its information.
jf/mode-line-format/which-function: Show the name of the “function” at point.

After the Change

Yesterday, I set about updating my mode line to show me when typopunct-mode is on or off. I also set about making that indicator actionable (e.g. I can click on it).

Now when typopunct-mode is on, I wrap in smart quotes the major mode name. (e.g. “Org Mode”) and when it is off, the major mode is not wrapped (e.g. Org Mode). Further, I can click on the major mode to now toggle the typopunct-mode state.

I needed a function that would force updating the mode line when the typopunct-mode changed. (Sidenote: See Github for more context regarding the jf/toggle-typopunct-mode function.)

(defun jf/toggle-typopunct-mode ()
  "Toggle `typopunct-mode'."
  (interactive)
  (if typopunct-mode
    (typopunct-mode -1)
    (typopunct-mode 1))
  (force-mode-line-update))

To add a click action to the text, I first needed to define a mode map. (Sidenote: See Github for more context regarding the jf/mode-line-format/major-mode-map variable.)

(defvar jf/mode-line-format/major-mode-map
  (let ((map
          (make-sparse-keymap)))
    (define-key map [mode-line down-mouse-1]
      #'jf/toggle-typopunct-mode)
    map)
  "Keymap to display `typopunct-mode'.")

And then I modified the function that renders the major mode. (Sidenote: See Github for more context regarding the jf/mode-line-format/major-mode-name function.)

(defun jf/mode-line-format/major-mode-name ()
    "Render the major mode as text.

When `typopunct-mode' is active, provide an actionable indicator of its
active nature."
    (let ((fmt
            (if typopunct-mode "“%s”" "%s")))
      (propertize
        (format fmt
          (capitalize
            (string-replace "-mode" "" (symbol-name major-mode))))
        'face
        (if (mode-line-window-selected-p)
          'mode-line 'mode-line-inactive)
        'local-map
        jf/mode-line-format/major-mode-map
        'help-echo
        (concat "mouse-1: #'jf/toggle-typopunct-mode"))))

Conclusion

I want my mode-line to remain compact, yet information rich, actionable, and not chatty. I find this minor tweak to be a quality of life improvement.

On Elfeed and Backups

jeremy@takeonrules.com (Jeremy Friesen) — Wed, 22 Jan 2025 12:03:15 -0500

I’m smiling as I’m leaning into the robustness of the elfeed package 📖 .

Re-Introducing Elfeed

First, I have an Rich Site Summary (RSS 📖) feed reader. In which the “news” rolls in according to when it was published, not some capturing algorithm.

Second, as I encounter interesting links by feed entries, I can open them in Emacs Web Wowser (EWW 📖) . From there, I give it a read and if I like the general disposition, I can invoke eww-copy-alternate-url to see if there are alternate URLs (e.g. an RSS feed). And add that to my list of feeds.

Third, as I read and want to comment, I invoke org-store-link which will copy the entry’s URL and title. I start capturing my thoughts and invoke org-insert-link to past the feed entry and title. This link type is elfeed. Meaning when I click on the link, I’m taken to the cached elfeed package version of that entry.

Fourth, I extended my elfeed package link type export from Org-Mode 📖 to export the URL of the feed item. Thus when I render my notes as Hypertext Markup Language (HTML 📖) , the elfeed package link types are transformed to the well-known http://… format. I wrote about this feature in Exporting Org Mode Elfeed Links.

Fifth, is the local cache/database of elfeed package entries. All of those feed entries that have scrolled through my reader. Those, in their full text, are stored locally. (Sidenote: Writing this, I wish I would’ve started using elfeed package many years ago. But alas, those posts are lost to the ether.)

They are available for offline reading, even years past having read them. And I’ve treated these as important artifacts for me to “preserve.” And by that I mean, make sure I have regular back-up copies of that information.

Let’s review that process:

Generate an occasional copy of the cache.
Copy that copy to a few different devices.

Generate an Occasional Copy of the Cache

I have the following Emacs 📖 code, which is available on Github):

(defun jf/syncthing-aling ()
  "Synchronize files into SyncThing bucket."
  (interactive)
  ;; Ensure we have our queue and our ready location
  (mkdir (file-truename "~/SyncThings/queue") t)
  (mkdir (file-truename "~/SyncThings/source") t)
  (message "Synchronzing denote files to cloud...")
  ;; There's a 1 in 10 chance that we'll perform the sync.  Toss that d10.
  (if (= 0 (random 10))
    (progn
      (message "Syncing elfeed database...")
      ;; We tar zip into one directory (our queue) and then move that
      ;; file in its complete state into the ready directory.  As move
      ;; is instantaneous and we don't need to worry about syncthing
      ;; picking up a partially completed file.
      (shell-command
        (concat "tar -cvzf "
          (file-truename "~/SyncThings/queue/elfeed.tar.gz")
          " " elfeed-db-directory " && mv -f ~/SyncThings/queue/elfeed.tar.gz ~/SyncThings/source&")
        "*syncthing-aling*"
        "*syncthing-aling*"))
    (message "I'll get you next time Gadget")))

;; Based on the idea of habit stacking, whenever I pull down my RSS
;; feed, I'll go ahead and sync my notes.
(advice-add #'jf/elfeed-load-db-and-open :before #'jf/syncthing-aling)
(add-hook 'after-init-hook #'jf/syncthing-aling)

Let’s pull out the comments (Sidenote: I made some adjustments to the comments to improve clarity, I hope.) in the order of operation:

Based on the idea of habit stacking, whenever I pull down my RSS feed, I’ll go ahead and sync my notes; maybe.
Ensure we have our queue and our ready location.
There’s a 1 in 10 chance that we’ll perform the sync. Toss that d10.
We tar and zip into one directory (our queue) and then move that file in its complete state into the ready directory. As move is instantaneous we won’t need to worry about SyncThing 📖 picking up a partially completed file.

Key in this is building the back-up process into a daily or thrice-daily ritual of mine.

I accept that my back-up won’t be “immediately up to date” but in using this process I can more reliably see when there are errors. That is I’m putting the “logs” in a place visible during my ritual of reading my RSS feed.

Copy That Copy to a Few Different Devices

I setup SyncThing on a few different devices. And the RSS feed cache is sent to those devices as “read only.” I don’t want to fuss with multiple devices having conflicting versions of this canonical cache, hence writing them to the devices.

To restore from those backups, I’d unzip and un-tar the files. As there’s no “operational urgency” to the backup, I’d restore at my leisure and then document accordingly. In essence, reverse the process of the Emacs function.

I’ve set my synchronization rules to only run when the devices are on the same network.

Conclusion

I feel a contentedness of having a repository of things I’ve read (or at least gathered) from the Internet. It is something that I should be able to easily re-build were I to lose or replace my primary machine.

I’ve chosen to use SyncThing instead of “pushing to the cloud” in part as a low-stakes experiment on eschewing cloud storage.

Why? This little local archipelago I’m creating requires far less resources than constantly syncing to a “remote” cloud. And I have more control over how it’s used as well as how many copies are saved.

I’m also treating this as a small, concrete, yet reversible experiment with cause for reflection. That is “how might I reduce my cloud storage footprint?” And adjusting my relationship to “always available” versus “available upon request.”

And here’s the realization: I don’t need much to always be available. And, with the current process, there’s space to identify what I want available outside of a tarball and thus “readable” on one of those other devices.

For example, I’ve shifted my Shopping List to write to that ready directory, not tarred and zipped, but as a plain text file. Which I can then read on my phone.

There’s more to think (and thus write) about in regards to how I’m thinking about this SyncThing ecosystem. But for now having a personal back-up is an absolute reassuring joy.

Forking from a Step in a Stacked Habit

jeremy@takeonrules.com (Jeremy Friesen) — Sat, 18 Jan 2025 07:12:58 -0500

Ereyesterday I wrote Some Entries from My Personal Journal, mentioning that I had adopted my personal journal habit for work. For a week, I had used the same capture templates, which produced the same structure.

The experiment worked, but needed refinement. I was writing engineering journal entries, but finding that I needed to carry forward blockers. I chose to sit, for a bit, without the refinement to ensure that I was sustaining the habit.

Clarifying the Functionality

Yesterday, while waiting on some information to proceed, I started writing out how I envisioned using my work journal. I considered my past work, as mentioned in Adding a Function to Carry Forward an Org-Mode Agenda Item and Revisiting My Org-Mode Time Tracking and Laying out a Different Direction.

However, there was a substantive difference. At my past work, I was responsible for tracking my time to specific clients and projects. In which the accuracy of the time-sheet was of utmost importance. In any given week, I might have had 4 or 5 different clients to whom I was billing.

Contrast to my present situation; I don’t bill to a client and I work on a singular product (albeit with many components). Instead, I work towards the completion of quarterly goals.

I wrote the following as code comments before getting started:

At my current employer, I have quarterly managed business objectives (MBOs). These focal activities involve: initiation, tracking work, and completion (with supporting documentation).

Initiation :: Writing the stated objective with narrative around the goal, measurement, and artifacts.

Tracking Work :: As I work through these objectives, I’m recording and tracking tasks towards the larger MBO. Some tasks become blocked and I need to work towards their resolution by providing sustained energy up and out; to get help with my team.

Completion :: This involves providing documentation demonstrating the completion of the MBO. I can leverage the tracking information to provide the documentation.

The two capture template letters reflect what I’m using for my personal (non-work related) notes. So I’m hoping to piggy back on that muscle memory as I adopt these tracking approaches.

Reviewing Existing Structures

I already had my Management by Objectives (MbOs 📖) in an Org-Mode 📖 document. The structure looked as follows:

* TODO [0/3] 2025-Q1 :mbos:
** TODO Do the thing
** TODO Do the other thing
** TODO Veer left

The first line is heading level one for the quarterly goals (e.g. “2025-Q1”) tagged with mbos. It is in the state TODO with the [0/3] tracking the state of the sub-headings.

The next three lines are each heading level two. Each is in a TODO state followed by their terse name. They inherit the mbos tag from the parent heading.

Throughout the quarter, I’d rarely revisit those goals. Instead, I’d hold them in the back of my head, and towards quarter end revisit and begin assembling documentation supporting their completion.

Finding the Crease

I then set about thinking of my capture templates from my daily personal habit. I mapped j to kicking off the day and J for appending to the day.

I wanted to use the BLOCKED status for tasks. Meaning, I’d want a level 3 (or more) sub-heading, as that’s where I can easily track things in Org-Mode . I spent a bit of time mapping the previous weeks notes to this newly emerging structure.

It gave me a good perspective of what I was working on and what was blocked. And as I started adding time stamps, I could now start seeing things in the agenda view; that is I could see what my work week included and where I may have drifted away from tackling a blocker.

Make it So

I settled on a structure as follows:

* TODO [0/3] 2025-Q1 :mbos:
** TODO [1/2] Do the thing
*** DONE Step 1 :tasks:
*** TODO Step 2 :tasks:
** TODO [0/1] Do the other thing
*** TODO A different step 2 :tasks:
** TODO [0/2] Veer left
*** TODO First you turn :tasks:
*** TODO Then move :tasks:

Starting a Task

I wrote out my j capture template (Sidenote: See Capture templates (The Org Manual) for details on the structure of a capture template.) , that is start a task that maps to an MbO :

(add-to-list 'org-capture-templates
  '("j" "Journal task for MBO"
     entry (file+function
             jf/work/filename-for-mbos
             jf/work/position-at-start-of-mbo)
     "TODO %^{Task} :tasks:\n:PROPERTIES:\n:ID: %(org-id-new)\n:END:\n%?"
     :empty-lines-before 1
     :empty-lines-after 1
     :clock-in t
     :clock-resume t))

And set about writing up the positioning function:

(defun jf/work/position-at-start-of-mbo ()
  "Position point at start of MBO.

For inserting entity."
  (let* ((incomplete-mbos
           (org-map-entries
             (lambda ()
               (let* ((mbo
                        (org-element-at-point))
                       (quarter
                         (car (org-element-lineage mbo))))
                 (cons
                   (concat
                     (propertize
                       (org-element-property :title quarter)
                       'face 'org-level-1)
                     (propertize
                       " > "
                       'face 'consult-separator)
                     (propertize
                       (org-element-property :title mbo)
                       'face 'org-level-2)
                     )
                   (org-element-property :begin mbo))))
             "+LEVEL=2+mbos-noexport+TODO!=\"DONE\""))
          (mbo
            (completing-read
              "MBO: " incomplete-mbos nil t)))
    (goto-char (alist-get mbo incomplete-mbos nil nil #'string=))))

A lingering problem is that this does not account for a daily entry that does not track towards one of my MbOs ; for example helping get someone else unstuck. But I can see space for how I’d do that…make another heading level 2 node that I don’t report.

Adding to a Task

Here’s the J capture template, that is append a note to a task.

(add-to-list 'org-capture-templates
  '("J" "Journal task progress for MBO"
     plain (file+function
             jf/work/filename-for-mbos
             jf/work/position-at-end-of-mbo-task-entity)
     "%T :: %?"
     :empty-lines-before 1
     :empty-lines-after 1
     :clock-in t
     :clock-resume t))

And here’s the function to find the place to insert the note:

(defvar jf/work/org-map-entries-mbo-task-filter
  "+LEVEL=3+mbos+tasks-journals+TODO!=\"DONE\""
  "The default filter for collecting MBO tasks.")

(defun jf/work/position-at-end-of-mbo-task-entity ()
  "Position point just before content end of MBO task.

For inserting plain text."
  (let* ((incomplete-mbo-tasks
           (org-map-entries
             (lambda ()
               (let* ((task
                        (org-element-at-point))
                       (mbo
                         (car (org-element-lineage task)))
                       (quarter
                         (cadr (org-element-lineage task))))
                 (cons
                   (concat
                     (propertize
                       (org-element-property :title quarter)
                       'face 'org-level-1)
                     (propertize
                       " > "
                       'face 'consult-separator)
                     (propertize
                       (org-element-property :title mbo)
                       'face 'org-level-2)
                     (propertize
                       " > "
                       'face 'consult-separator)
                     (propertize
                       (org-element-property :title task)
                       'face 'org-level-3)
                     )
                   (org-element-property :contents-end task))))
             jf/work/org-map-entries-mbo-task-filter))
          (task
            (completing-read
              "Task: " incomplete-mbo-tasks nil t)))
    ;; The contents-end of the task is the begining of the line that
    ;; contains the next heading.  Which the capture process for a
    ;; "plain" item then interprets as "add an item to the current
    ;; heading".  Not ideal, so move point backwards one character.
    (goto-char
      (1- (alist-get task incomplete-mbo-tasks nil nil #'string=)))))

The inline comments reflect a problem I encountered and how I solved it.

Junk Drawer

In reviewing my notes, I found that some entries did not map to tasks. I could make them a task, but they were working notes. So I decided to add a new level 3 headline: “Engineering Journal”. And tagged it with journals.

The following capture template mimics the J template (example given (e.g. 📖) , append to a task):

(add-to-list 'org-capture-templates
  '("e" "Engineering Journal entry for MBO"
     plain (file+function
             jf/work/filename-for-mbos
             jf/work/position-in-mbo-journal-entry)
     "%T :: %?"
     :empty-lines-before 1
     :empty-lines-after 1
     :clock-in t
     :clock-resume t))

And the function to perform the capture leverages is:

(defun jf/work/position-in-mbo-journal-entry ()
  "Position point just before the selected journal.

Included to allow the re-use of logic for different 3rd level tasks."
  (let ((jf/work/org-map-entries-mbo-task-filter
          "+LEVEL=3+mbos+tasks+journals"))
    (jf/work/position-at-end-of-mbo-task-entity)))

I chose to separate the tasks and journal, in part to reduce the selection process. However, I might collapse these two.

Applying to the Personal

I don’t envision supplanting my personal j and J capture templates with the more detailed work templates. However, I’m going to hold space on how I might use those work steps. Maybe they can help me accomplish personal goals? Or even set them?

Adding Color and Style to HTML Elements in Emacs's SHR/EWW

jeremy@takeonrules.com (Jeremy Friesen) — Sat, 28 Dec 2024 09:44:29 -0500

In Adding HTML5 Display Block Elements to Emacs’ SHR (and EWW) Tag Rendering I wrote about handling additional Hypertext Markup Language (HTML 📖) in Emacs Web Wowser (EWW 📖) .

Yesterday I spent some time adding colors to a few elements. For this I wrote a macro that did two things:

Defined a face for the tag
Add advice around the tag function

The jf/shr-facify macro defined below does the heavy lifting. (Sidenote: See Github for my code that applies the face to an HTML tag.)

(defmacro jf/shr-facify (tag)
  "Create and apply the face to the given TAG."
  (let ((face
          (intern (concat "shr-" tag)))
         (docstring-face
          (format "Face for <%s> elements." tag)))
  `(progn
     (defface ,face
       '((default :inherit shr-text))
       ,docstring-face)
     (advice-add (intern (concat "shr-tag-" ,tag))
       :around
       (lambda (advised-function func &rest args)
         (let ((start (point)))
           (apply advised-function func args)
           (shr-add-font start (point) (intern (concat "shr-" ,tag)))))))))

(jf/shr-facify "blockquote")
(jf/shr-facify "aside")
(jf/shr-facify "cite")
(jf/shr-facify "dfn")
(jf/shr-facify "dt")

In reading the Simple HTML Renderer (SHR 📖) code, I found that when SHR encounters a node (example given (e.g. 📖) , <p>), it checks if there’s a defined SHR tag function for that name (e.g. , shr-tag-p) and calls it. Otherwise it falls back to a generic function.

In the jf/shr-facify macro, I define a face for the tag but leave it mostly “empty”.

I then customize the face as part of ef-themes-with-colors. (Sidenote: See Ef (εὖ) themes for GNU Emacs by Protesilaos Stavrou.) Below is that function. (Sidenote: See Github for my code on changing colors in ef-themes.)

(defun jf/theme-custom-faces ()
    "Set the various custom faces."
    (ef-themes-with-colors
      (custom-set-faces
        `(shr-blockquote
           ((,c :foreground ,docstring)))
        `(shr-dfn
           ((,c :slant italic :foreground ,keyword)))
        `(shr-dt
           ((,c :slant italic :foreground ,keyword)))
        `(shr-cite
           ((,c :underline nil :slant italic :bold t :foreground ,mail-cite-0)))
        `(shr-aside
           ((,c :foreground ,comment :background ,bg-alt))))))

Last, I register jf/theme-custom-faces with the after-enable-theme-hook. This means as I change themes, Emacs 📖 will update the font face colors according to the themes named colors.

(add-hook 'after-enable-theme-hook #'jf/theme-custom-faces)

Tags with Custom Faces

One thing I love about Ef themes and their sibling Modus Themes is that Protesilaos (Also Known As (aka 📖) Prot) has mapped colors to semantic concepts. I have found this helpful as I can map additional concepts to those semantics.

In the case of HTML elements, its somewhat imprecise, but it does create a conceptual consistency.

For the blockquote tag, I wanted a gentle indicator. I mapped this semantically to the docstring foreground color defined in Ef Themes.

For the aside, it is very much like a comment. For the moment, I’m also adding a background color to it. I’m not set on that color, but include it as an example.

The cite and dfn tags are often italicized in the default stylesheet; I wanted to carry that forward but also gently differentiate. The cite uses the mail-cite-0 color. And the dfn applies the keyword color. (Sidenote: I’m mixing the semantic categories, but it works out alright.)

Related to dfn is the dt, both being a definition. Hence I use the keyword color.

Conclusion

I’m loving using EWW as my primary browser. And as a bonus, changes I make to EWW rendering also ripple into my Rich Site Summary (RSS 📖) reading via the elfeed package 📖 . This little adjustments help convey the semantic intention of the author(s).

Adding HTML5 Display Block Elements to Emacs’ SHR (and EWW) Tag Rendering

jeremy@takeonrules.com (Jeremy Friesen) — Wed, 18 Dec 2024 09:28:38 -0500

This morning I made two quality of life adjustments to my Emacs Web Wowser (EWW 📖) viewing:

Add handling for HTML5 display:block elements: article, aside, footer, header, nav, section.
Add rel=home and rel=up navigation key bindings.

Without the handling adjustment, the aforementioned HTML5 elements render inline; meaning there’s no surrounding line break and the text rendering can look a bit off.

The rel=home and rel=up are analogous to the next and prev rel attributes. (Sidenote: See next rel attribute on MDN Web Docs.) (Sidenote: See prev rel attribute on MDN Web Docs.) The up and home are not documented in Mozilla Developer Network Web Docs (MDN Web Docs 📖) but up is documented on w3.org. (Sidenote: See up rel attribute docs on W3.org.) And rel=home is regarded as good Search Engine Optimization (SEO 📖) (and helpful for accessibility).

When viewing a page in EWW , I can type the following:

h to visit rel=home.
u to visit rel=up.
p to visit rel=prev.
n to visit rel=next.

Which I find to be some super convenient hot keys. Now for some code…!

Emacs Lisp Code

(use-package eww
  :straight (:type built-in)
  (defmacro shr-display-block (tag)
    "Register TAG a paragraph (in CSS parlance \"display:block;\").

See https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content"
    (let ((fname
           (intern (format "shr-tag-%s" tag)))
          (docstring
           (format "Render \"%s\" tag as paragraph." tag)))
      `(defun ,fname (dom)
         ,docstring
         (shr-ensure-paragraph)
         (shr-generic dom)
         (shr-ensure-paragraph))))

  (shr-display-block "article")
  (shr-display-block "aside")
  (shr-display-block "footer")
  (shr-display-block "header")
  (shr-display-block "nav")
  (shr-display-block "section")

  ;; The `shr-map' is being applied after `eww-mode-map'; which means that
  ;; attempts to register \"u\" for `eww-up-url' don't work.
  (unbind-key "u" shr-map)
  :bind (:map eww-mode-map
              ("u" . eww-up-url)
              ("h" . eww-home-url)))

Extending Built-In Emacs Bookmark Package

jeremy@takeonrules.com (Jeremy Friesen) — Tue, 17 Dec 2024 08:04:39 -0500

Earlier in December I wrote Monkey Patch Fix for Bookmark+ for Emacs 30. Since then, I’ve encountered problems with corrupted bookmarks. And if I undo the patch, I encounter similar problems.

As I’m using Emacs 30, which is not yet released, I can expect bugs. However, I want to stop encountering corrupted bookmarks. So I disabled the Bookmarks+ package. But that left me without some key functionality: creating an Emacs bookmark of the foreground tab of a browser such as Firefox, Safari, or Chrome.

I did some digging in Emacs Web Wowser (EWW 📖) , as that package can create Bookmarks and indicate the type as EWW.

Emacs Functions for Extending EWW

There are three functions, one for each of the browsers I might use:

jf/menu--bookmark-chrome
jf/menu--bookmark-firefox
jf/menu--bookmark-safari

Each of those functions use the Grab Mac Link package to interact with the browsers. Each then calls jf/bookmark-url which sets some variables, importantly the bookmark-make-record-function; which needs to return a list with the car as the title and cdr is a property list with the keys location and handler.

Below is my “good enough” solution to my desired functionality, with source code available on Github.

(use-package bookmark
  :straight (:type built-in)
  :config
  ;; On each machine I use, I have different bookmarks, yet they all
  ;; point to the same location.
  (setq bookmark-default-file "~/emacs-bookmarks.el")

  ;; Save the `bookmark-file' each time I modify a bookmark.
  (setq bookmark-save-flag 1)

  (defvar jf/bookmark-make-record-function/browse-url/title ""
    "Used for capturing the title from the browser current tab.")

  (defvar jf/bookmark-make-record-function/browse-url/url ""
    "Used for capturing the url from the browser current tab.")

  (defun jf/bookmark-url (url title)
    "Create a `browse-url' bookmark for URL and TITLE."
    (let* ((jf/bookmark-make-record-function/browse-url/title
            title)
           (jf/bookmark-make-record-function/browse-url/url
            url)
           (bookmark-make-record-function
            #'jf/bookmark-make-record-function/browse-url))
      (bookmark-set-internal nil title nil)))

  (defun jf/bookmark-make-record-function/browse-url()
    "Function to build the bookmark structure."
    `(,jf/bookmark-make-record-function/browse-url/title
      (location . ,jf/bookmark-make-record-function/browse-url/url)
      (handler . jf/browse-url-bookmark-jump)))

  (defun jf/browse-url-bookmark-jump (bookmark)
    "Default bookmark handler for browser."
    (browse-url (bookmark-prop-get bookmark 'location)))

  ;; In the bookmark list page, identify the type as BROWSE for those
  ;; captured by `jf/bookmark-url'.
  (put 'jf/browse-url-bookmark-jump 'bookmark-handler-type "BROWSE")

  (defun jf/menu--bookmark-safari ()
    "Create `bookmark+' for current Safari page."
    (interactive)
    (require 'grab-mac-link)
    (let* ((url-and-title
            (grab-mac-link-safari-1))
           (title
            (read-string
             (concat "URL: " (car url-and-title) "\nTitle: ")
             (cadr url-and-title))))
      (jf/bookmark-url (car url-and-title) title)))

  (defun jf/menu--bookmark-firefox ()
    "Create `bookmark+' for current Firefox page."
    (interactive)
    (require 'grab-mac-link)
    (let* ((url-and-title
            (grab-mac-link-firefox-1))
           (title
            (read-string
             (concat "URL: " (car url-and-title) "\nTitle: ")
             (cadr url-and-title))))
      (jf/bookmark-url (car url-and-title) title)))

  (defun jf/menu--bookmark-chrome ()
    "Create `bookmark+' for current Chrome page."
    (interactive)
    (require 'grab-mac-link)
    (let* ((url-and-title
            (grab-mac-link-chrome-1))
           (title
            (read-string
             (concat "URL: " (car url-and-title) "\nTitle: ")
             (cadr url-and-title))))
      (jf/bookmark-url (car url-and-title) title))))

Add Work Link Type to Org-Mode

jeremy@takeonrules.com (Jeremy Friesen) — Sat, 07 Dec 2024 15:10:02 -0500

Yesterday, I added a work link type to Org-Mode 📖 . (Sidenote: For those Samverans reading along, I thought about naming this link type “wortem”, in honor of the placeholder name used during Portland Common Data Model (PCDM 📖) discussions.) My original name for the link type was cite; however that is a link type in Org Citation ecosystem. I did not want to collide with another named link type; in case that I start writing academic papers and use that citation process.

Background

As I’ve written about lately: Refining My Quotation Capture Process and Re-Wiring My Epigraphs Functionality to Leverage My Bibliography File.

In summary, I have a single document that contains quotes and their associated person or work. I’ve written several capture templates for creating people, works, and attributed quotes.

Let’s look again at a quote that belongs to a work:

** The Annals of Imperial Rome :books:
,:PROPERTIES:
,:AUTHOR: Tacitus
,:CUSTOM_ID: 73A11F00-F727-4FDF-9FF1-27EBB59CF139
,:END:

,#+NAME: 20230121T093858
,#+begin_quote
The more corrupt the state, the more numerous the laws.
,#+end_quote

With my prior functionality, I could link to the named quote. What I wanted was to link to the work. I could link via Denote 📖 or to the Headline. However, before I chose to re-use another link type I thought about what I wanted.

Rudimentary Requirements Gathering

First, I make extensive use of the CITE-tag in my blog. Such that I have an Org-Mode macro for cite. (Sidenote: See my cite macro on Github.) And the target for most of my Org-Mode is “publishing” is my blog.

This defined a functional need:

Given that I am linking to a work,
When I export that work to HTML,
Then that work's title should be in a =CITE= tag.

I also wanted a means of quickly selecting works that I might cite. There were a couple of options:

Write a custom function to insert a Denote or Headline link.
Create a custom link type.

Were I to write a custom function, I would then want to extend/modify the associated link export function. If I created a new link type, I wouldn’t be hacking an existing function but could instead write a new one.

Re-using Denote would allow me to see backlinks. However, a simple Ripgrep 📖 would do something similar for a custom link.

Another “nice to have” functionality is rendering, in Org-Mode , the link with similar font style as that of browsers (example given (e.g. 📖) , italicized). That is very simple with custom link types.

Emacs Code

Here’s my configuration for the a work link. (Sidenote: See my configuration on Github.)

(org-link-set-parameters "work"
    ;; TODO: Allow link to specify to include author.
    :follow #'jf/org-link-ol-follow/work
    :complete #'jf/org-link-ol-complete/work
    :export #'jf/org-link-ol-export/work
    :face #'jf/org-faces-work)

I’ve defined four of the properties:

:follow: when I click on the link, jump to the work.
:complete: when I M-x org-insert-link this function fires to find the work.
:export: when I export the document to another format, this function determines what happens.
:face: italicized and colored to look visually different.

But have chosen to not implement the :store option. Why? When I’m citing something, I’m unlikely to be on the Work node but instead in some other document.

The `:follow` Function

Here’s the quick and dirty function to find the Work in my bibliography. (Sidenote: See jf/org-link-ol-follow/work on Github.) I’m using a regular expression to quickly find the work, then positioning point to the start of the headline.

(defun jf/org-link-ol-follow/work (name)
    "Follow the NAME to the work."
    (let* ((file
             jf/filename/bibliography)
            (case-fold-search
              t))
      (find-file file)
      (goto-char (point-min))
      (let ((case-fold-search t))
        (search-forward-regexp
          (format "^:custom_id:[[:space:]]+%s$" name))
        (call-interactively #'org-previous-visible-heading))
      (pulsar--pulse)))

The `:complete` Function

Here’s the function that reads my bibliography and assembles a list of works. (Sidenote: See jf/org-link-ol-complete/work on Github.) From that list I choose a work and insert the link. I add the title to the kill ring so I can easily add that title as the description for the link.

(defun jf/org-link-ol-complete/work ()
    "Prompt for a work from my bibliography"
    (interactive)
    (let* ((buffer
             (find-file-noselect jf/filename/bibliography))
            (works
              (save-excursion
                (with-current-buffer buffer
                  ;; With the given tag, find all associated headlines
                  ;; that match that tag.
                  (org-map-entries
                    (lambda ()
                      (let* ((headline
                               (org-element-at-point))
                              (title
                                (org-element-property :title headline))
                              (subtitle
                                (org-entry-get headline "SUBTITLE")))
                        (cons
                          (format "%s"
                            (if subtitle
                              (concat title ": " subtitle)
                              title))
                          (org-entry-get headline "CUSTOM_ID"))))
                    "+LEVEL=2+!people" 'file))))
            (work
              (completing-read "Citable: " works nil t)))
      (when-let ((id
                   (alist-get work works nil nil #'string=)))
        (progn
          (message "Added %S to the kill ring" work)
          (kill-new work)
          (format "work:%s" id)))))

The `:export` Function

Here’s the function for exporting the link. I handle html, md, latex, and a general fallback. (Sidenote: See jf/org-link-ol-export/work on Github.)

(defun jf/org-link-ol-export/work (link description format protocol)
    "Export the text of the LINK work in the corresponding FORMAT.

We ignore the DESCRIPTION and probably the PROTOCOL."
    (let ((buffer
            (find-file-noselect jf/filename/bibliography)))
      (save-excursion
        (with-current-buffer buffer
          ;; First we find the corresponding work and possible URL.
          (when-let* ((work
                        (car
                          (org-element-map
                            (org-element-parse-buffer)
                            '(headline)
                            (lambda (el)
                              ;; Skip un-named blocks as we can’t link to
                              ;; them.
                              (when (string=
                                      (org-entry-get el "CUSTOM_ID")
                                      link)
                                (let ((title
                                        (car
                                        (org-element-property :title el))))
                                  (list
                                    :title
                                    (if-let ((subtitle
                                               (org-entry-get el "SUBTITLE")))
                                      (format "%s: %s" title subtitle)
                                      title)
                                    :url
                                    (org-entry-get el "ROAM_REFS")))))))))
            ;; Then we create the corresponding format.
            (cond
              ((or (eq format 'html) (eq format 'md))
                (format "<cite data-id=\"%s\">%s</cite>"
                  link
                  (if-let ((url
                             (plist-get work :url)))
                    (format "<a href=\"%s\">%s</a>"
                      url (plist-get work :title))
                  (plist-get work :title))))
              ((eq format 'latex)
                (format "\\textit{%s}"
                  (plist-get work :title)))
              (t
                (format "“%s”"
                  (plist-get work :title)))))))))

The `:face` Setting

The work face inherits from link.

(defface jf/org-faces-work '((default :inherit link))
    "Face used to style `org-mode' work links in the buffer."
    :group 'denote-faces
    :package-version '(denote . "0.5.0"))

I use ef-themes-with-colors to further customize the colors, helping create visual differentiation between other links:

`(jf/org-faces-work
  ((,c :underline nil :slant italic :bold t :foreground ,mail-cite-0)))

Continued Hacking on Links

A deeper read of this work, begins to highlight how I’m using the Org-Mode ecosystem to introduce Hypertext Markup Language (HTML 📖) 5 elements. The abbr and abbr-plural map directly to the ABBR-tag. The date link maps (although incompletely) to the TIME-tag. My epigraph link is a narrow usage of the BLOCKQUOTE-tag. And my new work link is an approximation of the CITE-tag.

This also helps keep me out of mucking around with existing export functions.

Auto-Exporting My Book "Shopping List" as Part of Org Capture

jeremy@takeonrules.com (Jeremy Friesen) — Wed, 04 Dec 2024 17:50:09 -0500

Today I extracted a function that will write to my book “shopping list”. I wrote about the original function in Extending My Bibliography for an On The Go “Shopping List”.

Some Emacs Lisp

I now call the new function as part of the finalization of my Org-Mode 📖 template capture. I’ve defined the “work” capture template as follows:

("w" "Work"
 entry
 (file+headline jf/filename/bibliography "Works")
 "%^{Title} %^g\n:PROPERTIES:\n:CUSTOM_ID: %(org-id-new)\n:AUTHOR: %^{AUTHOR}\n:END:\n%?"
 :jump-to-captured t
 :after-finalize jf/bibliography/export-shopping-list)

The change I made was adding the :after-finalize property. This helps keep my “shopping list” up to date based on what I’m considering.

Serendipity and Previous Lifetime(s)

As part of my previous work, I would travel to various college towns. Invariably there would be a wonderful used bookstore. I miss perusing those shelves, looking for the esoteric books.

Jenny and I also used to take day trips to mid-sized cities, but that happens less and less. And we always prioritized visiting independent bookstores.

When we were helping to start Fables Books, Jenny and I visited numerous bookstores; looking for inspiration and to see how others were merchandising their shop. (Sidenote: See I'm Helping to Open Fables Bookshop in Downtown Goshen Indiana.)

I could order these books online (from great bookshops such as Brain Lair Books, Lowry Books, Marcus Books, and Fables Books). Or borrow them from a local library.

But I’m holding off on getting these books. First, I have a large backlog of books. But I’m also keen on creating moments of serendipity.

A few weeks ago I had read a post on The Marginalian that referenced out Albert Camus’s Lyrical and Critical Essays. A few days later, at a local bookstore, I saw “front-facing” a copy of this very book.

Serendipity! And I purchased it immediately.

What I’m feeling, with this “shopping list”, is priming myself for delayed gratification. Namely, when I find myself at a book shop, I’ll have a list of books to investigate. And in sifting through those shelves, I’m certain I’ll find other books of interest.

Refining My Quotation Capture Process

jeremy@takeonrules.com (Jeremy Friesen) — Wed, 04 Dec 2024 13:17:30 -0500

In Refining My Personal Bibliography and Epigraph Process I wrote about my capture template for Quotes.

Prior to today the positioning logic was to go to the :contents-end of the chosen headline. The problem I encountered was that I had additional sub-headings with writing and reflection…and the capture process dumped the quote at the end of that sub-heading. In other words, not where I wanted it.

I thought for a bit and my options were:

Always create a sub-node for quotations within a headline.
Put the content at the beginning of the headline node.

I chose to pursue the beginning of the headline node. In part because not all books will have quotations. But also because where I’d want to add the headline was in the same spot as the beginning of the headline node.

Meaning, I needed to “solve” the beginning of the headline problem. I experimented with using :contents-begin property. That is always the beginning of the first line following the headline.

Which was right at the point where I was storing metadata around the work. Let’s look at an example.

** DONE Power of the Powerless, The :books:
#+CLOSED: [2024-12-04 Wed 08:36]
,:PROPERTIES:
,:CUSTOM_ID: 26A608F1-70C2-4E23-9DA0-B2C978D5BB52
,:AUTHOR: Václav Havel
,:ID:       045E3F33-5D5A-49E6-A534-2EDAE3F74062
,:END:
,:LOGBOOK:
- State "DONE"       from "STARTED"    [2024-12-04 Wed 08:36]
#+CLOCK: [2024-11-28 Thu 08:45]--[2024-11-28 Thu 09:00] =>  0:15
- State "STARTED"    from              [2024-11-27 Wed 10:42]
,:END:

The :contents-begin would be the line starting with #+CLOSED. And that is not where I wanted to put the quote. I wanted it just after the last :END: in the example block.

Which lead me to the following bit of Emacs 📖 code:

(while (org-element-type-p
        (org-element-at-point)
        '(drawer property-drawer keyword planning))
  (goto-char
   (org-element-property :end (org-element-at-point))))

I call this just after moving point to the :contents-begin of the headline.

There are four elements I’m looking for:

drawer: That is the lines starting with :LOGBOOK: and it’s related :END:.
property-drawer: That is the lines starting with :PROPERTIES: and it’s related :END:.
planning: That is the line starting #+CLOSED:.
keyword: That is a “just in case” I have other keywords defined on this node.

Those four element types are automatically added and positioned by Org-Mode 📖 as part of its baseline functionality and as part of my initial “work” capture template.

To understand the nodes, I used the interactive eval-expression. Moving point to the beginning of the line then executing (org-element-at-point) to see the type. And using (goto-char (org-element-property :end (org-element-at-point))) to move point to see it’s effect.

You can read my updated function on Github.

Monkey Patch Fix for Bookmark+ for Emacs 30

jeremy@takeonrules.com (Jeremy Friesen) — Tue, 03 Dec 2024 10:42:36 -0500

Earlier this year, I started using the Bookmarks+ emacs package. And in November I upgraded to Emacs 30, at present an Alpha/Beta release of the next version.

The Problem

I’ve encountered a few hiccups, the most insidious being how Bookmark+ was losing/clobbering bookmarks.

With some sleuthing, what I found was that the read expectations for the bookmark file were out of sync with how we write the bookmark file (in Emacs 30).

I didn’t dive too deep, but hopefully this triage can provide some clues. (Sidenote: I also have not yet explored how to submit an issue for this observed problem.)

The expectations on read is that there will be a line that starts with ) (example given (e.g. 📖) , a closing parenthesis, implying the closing of a list). The write process however was adding that closing parenthesis to the prior line.

The result, the read would fail. And my bookmarks would start getting clobbered.

The Hack

After some experimentation, I think the following hack remediates most of the problems I was encountering:

  (add-hook 'bmkp-write-bookmark-file-hook
    #'jf/bookmark+/remediate-bookmark-file)

  (defun jf/bookmark+/remediate-bookmark-file (&optional file)
    "Fix FILE format to conform to `bookmark+'.

In updating to Emacs 30.x, I encountered problems with saving the
bookmark file.  What was happening is that the read format is assumed to
have a line that is only \")\".  However the writing was not doing that.

This function remediates the observed written format to conform to the
expected read format."
    (with-current-buffer
      (find-file-noselect (or file bookmark-default-file))
      (save-excursion
        (goto-char (point-max))
        (if (re-search-backward "^)" nil t)
          (message "%s already well formatted" bookmark-default-file)
          (progn
            (goto-char (point-max))
            (re-search-backward ")")
            (insert "\n")
            (save-buffer))))))

Re-Wiring My Epigraphs Functionality to Leverage My Bibliography File

jeremy@takeonrules.com (Jeremy Friesen) — Sun, 01 Dec 2024 09:09:03 -0500

I’ve been working on adjusting my epigraphs. Prior to Friday my blog used one file per epigraph. These lonely files held metadata around the quote, the text of the quote and any additional commentary I might have privately written.

Previous Epigraph

Here’s an example of that file:

#+title:      Trees are an invitation to think about time
#+date:       [2023-01-21 Sat 17:36]
#+filetags:
#+identifier: 20230121T173626

#+AUTHOR_NAME: Rebecca Solnit
#+WORK_TITLE: Orwell’s Roses

Trees are an invitation to think about time and to travel in it the
way they do, by standing still and reaching out and down.

The #+identifier of 20230121T173626 is used for creating the link to this quote.

The “Trees are an invitation to think…” is the quoted text. Orwell’s Rosesis the work, and Rebecca Solnit the author. The rest is for metadata, discoverability, and back-linking.

Updated Epigraph

The updated epigraph, which is a named quote or verse block contained within a level two headline. Here’s an example:

** STARTED Orwell’s Roses :books:
,:PROPERTIES:
,:AUTHOR: Rebecca Solnit
,:END:

#+NAME: 20230121T173626
#+begin_quote
Trees are an invitation to think about time and to travel in it the
way they do, by standing still and reaching out and down.
#+end_quote

The new NAME property is the prior IDENTIFIER. And the type of epigraph (e.g., a quote instead of verse) is indicated by the content block.

Benefits

This allows for multiple quotes from the same work. And as previously mentioned in Refining My Personal Bibliography and Epigraph Process, this allows for me to generate both my Bibliography and my Epigraphs from the same source file (as they are related).

Exploring `org-insert-link`

While typing in Org-Mode 📖 , I use M-x org-insert-link to select the type of link and the type then dictates the prompt/completion. (Sidenote: See Handling Links (The Org Manual).)

I added epigraphs to my link options as follows:

(org-link-set-parameters "epigraph"
    :complete #'jf/org-link-ol-complete/epigraph
    :export #'jf/org-link-ol-export/epigraph
    :face #'jf/org-faces-epigraph
    :follow #'jf/org-link-ol-follow/epigraph)

I’ve set 4 options for epigraphs:

:complete: prompt for which epigraph to link to.
:export: when I export the file, this function determines the exported content.
:face: I don’t want my epigraphs to look like regular links, so I’ve set the face for this link to provide a visual clue.
:follow: When I “click” on the epigraph link, this function finds the epigraph and takes me to that location.

See Adding Hyperlink Types (The Org Manual) for the documented options.

Emacs Lisp Code

The code I’m referencing can be found in my Dotemacs init.el file.

The `:complete` function

The following function reads the bibliography file, mapping the named quote-block and verse-block into a list. The list is a cons cell with the car as the first 72 characters of the block and the cdr as the name/identifier of the block.

(defun jf/org-link-ol-complete/epigraph ()
    "Find and insert an epigraph for export.

Wires into `org-insert-link'."
    (let* ((buffer
             (find-file-noselect jf/bibliography-filename))
            (candidates
              (save-excursion
                (with-current-buffer buffer
                  (org-element-map
                    (org-element-parse-buffer)
                    '(quote-block verse-block)
                    (lambda (el)
                      ;; Skip un-named blocks as we can’t link to them.
                      (when-let* ((id
                                    (org-element-property :name el))
                                   (left
                                     (org-element-property
                                       :contents-begin el))
                                   (right
                                     (org-element-property
                                       :contents-end el))
                                   (text
                                     (s-trim
                                       (s-replace "\n" " "
                                         (buffer-substring-no-properties
                                           left
                                           (if (< (- right left) 72)
                                             right
                                             (+ left 72)))))))
                        (cons text id)))))))
            (candidate
              (completing-read "Epigraph: " candidates nil t))
            (id
              (alist-get candidate candidates nil nil #'string=)))
      (when id
        (progn
          (message "Added %S to the kill ring" candidate)
          (kill-new candidate)
      (format "epigraph:%s" id)))))

When I use M-x org-insert-link and select epigraph, my completion shows the following:

1/208  Epigraph: <PROMPT>
0  Your hands are empty The streets are empty You can't control us You can'
1  Without contraries there is no progression.
2  The times are urgent let us slow down.
3  The use of truth is its communication.
4  Life is a brief encampment.
5  The map is not the territory.
6  Uncertainty is the refuge of hope.
7  Books are a uniquely portable magic.
8  Desire is movement rather than place.
9  Men have become the tools of their tools.

I can then start typing to narrow the options. Once I’ve selected the epigraph, I’m then prompted to insert the description (example given (e.g. 📖) , the visible text for the link). As a quality of life improvement, the selection process adds the selected block’s first 72 characters to the kill-ring; allowing for quick pasting.

Later, when I export the epigraph, I discard the description favoring the original text.

The `:follow` function

When I “click” on the link, I jump to the named block. The following function facilitates that behavior:

(defun jf/org-link-ol-follow/epigraph (name)
    "Follow the NAME to the epigraph."
    (let* ((file
             jf/bibliography-filename)
            (case-fold-search
              t))
      (find-file file)
      (goto-char (point-min))
      (search-forward-regexp (format "^#\\+name: +%s$" name))
      (pulsar--pulse)))

The `:export` function

I often export Org-Mode documents to Markdown, LaTeX, and HTML. I want to ensure that my epigraphs export in a meaningful format. Below is the function that facilitates that:

(defun jf/org-link-ol-export/epigraph (link description format protocol)
    "Export the text of the LINK epigraph in the corresponding FORMAT.

We ignore the DESCRIPTION and probably the PROTOCOL."
    (let ((buffer
            (find-file-noselect jf/bibliography-filename)))
      (save-excursion
        (with-current-buffer buffer
          (let* ((epigraph
                   (car
                     (org-element-map
                       (org-element-parse-buffer)
                       '(quote-block verse-block)
                       (lambda (el)
                         ;; Skip un-named blocks as we can’t link to
                         ;; them.
                         (when (string=
                                 (org-element-property :name el)
                                 link)
                           el)))))
                  (class
                    (if (eq 'verse-block (org-element-type epigraph))
                      "verse"
                      "quote"))
                  (lineage
                    (org-element-lineage epigraph))
                  (context
                    (car
                      (seq-filter
                        (lambda (el)
                          (and
                            (eq (org-element-type el) 'headline)
                            (= (org-element-property :level el) 2)))
                        lineage)))
                  (people?
                    (member "people"
                      (org-element-property :tags context)))
                  (work
                    (if people?
                      ""
                      (car (org-element-property :title context))))
                  (author
                    (if people?
                      (car (org-element-property :title context))
                      (org-entry-get context "AUTHOR")))
                  (text
                    (buffer-substring-no-properties
                      (org-element-property
                        :contents-begin epigraph)
                      (org-element-property
                        :contents-end epigraph))))
            (cond
              ((and
                 ;; This represents the logic in Take on Rules before
                 ;; <2024-11-30 Sat>.
                 ;;
                 ;; QUESTION: Am I concerned with the backlinks?  They
                 ;; are cute, but are they worth it?  Assume I persist
                 ;; the ID, I can rebuild that logic.
                 jf/exporting-org-to-tor
                 (or (eq format 'html) (eq format 'md)))
                (format "{{< epigraph key=\"%s\" >}}" link))
              ((or (eq format 'html) (eq format 'md))
                (format "<blockquote class=\"%s\">\n%s%s</blockquote>\n"
                  class
                  (if (string= class "verse")
                    (s-replace "\n" "<br />\n" text)
                    text)
                  (cond
                    ((and (s-present? work) (s-present? author))
                      (format "\n<footer>&mdash;%s, <cite>%s</cite></footer>"
                        author work))
                    ((s-present? work)
                      (format "\n<footer>&mdash; <cite>%s</cite></footer>"
                        work))
                    ((s-present? author)
                      (format "\n<footer>&mdash; %s</footer>"
                        author))
                    (t ""))))
              ((eq format 'latex)
                (format "\\begin{%s}\n%s%s\n\\end{%s}\n"
                  class
                  (if (string= "verse" class)
                    (s-replace "\n" "\\\\\n" text)
                    text)
                  (cond
                    ((and (s-present? work) (s-present? author))
                      (format "---%s, \\textit{%s}" author work))
                    ((s-present? work)
                      (format "---\\textit{%s}" work))
                    ((s-present? author)
                      (format "---%s" author))
                    (t ""))
                  class))
              ((eq format 'ascii)
                (let ((use-hard-newlines t))
                  (s-replace
                    "\n" hard-newline
                    (format "%s%s"
                      text
                      (cond
                        ((and (s-present? work) (s-present? author))
                          (format "\n\n—%s, “%s”" author work))
                        ((s-present? work)
                          (format "\n\n—“%s”" work))
                        ((s-present? author)
                          (format "\n\n—%s" author))
                        (t ""))))))
              (t nil)))))))

There’s some refactoring I could do, but what I have reads easily enough for me.

Contrast

My previous approach (e.g. , one epigraph per file) felt a bit disjointed; namely quotes from the same work were scattered amongst different files. My previous :complete function read the file names; and by convention the file name encoded the first few words of the quote.

With the new approach, the :complete function creates a more immediately legible list of options. And my quotes are contained within the larger context.

Conclusion

I wanted to share this functionality to further demonstrate using the Org-Mode Application Programming Interface (API 📖) ; in particular the org-element-lineage, as that was something that took a bit of searching and experimenting to utilize.

Extending My Bibliography for an On The Go “Shopping List”

jeremy@takeonrules.com (Jeremy Friesen) — Wed, 27 Nov 2024 21:44:49 -0500

Earlier today I wrote Refining My Personal Bibliography and Epigraph Process. And this evening I added some additional functionality. Namely writing my “shopping list” to a file in the cloud. One that I can access on my phone. Useful for used bookstores and libraries.

Here’s that code:

#+begin_src emacs-lisp :exports results :results value file :file ~/Library/CloudStorage/path-to-bibliography.txt
;; Export my “shopping list” to my Proton Drive.
(concat
  (s-join "\n"
    (org-map-entries
      (lambda ()
        ""
        (concat
          "- “"
          (org-element-property :title (org-element-at-point))
          (when-let ((subtitle
                       (org-entry-get
                         (org-element-at-point) "SUBTITLE")))
            (format ": %s" subtitle))
          "”"
          (when-let ((authors
                       (org-entry-get
                         (org-element-at-point) "AUTHOR")))
            (concat " by " authors))
          (when-let ((editors
                       (org-entry-get
                         (org-element-at-point) "EDITOR")))
            (concat " Editors: " editors))))
      "+LEVEL=2+books+shoppingLists" 'file)))
#+end_src

Refining My Personal Bibliography and Epigraph Process

jeremy@takeonrules.com (Jeremy Friesen) — Wed, 27 Nov 2024 16:45:44 -0500

Those that have explored my Take on Rules’ Site Map may have noticed my Epigraphs and Bibliography section. In Exploring the Reworking of a Blog Page, I wrote about the Bibliography and some rework I was exploring.

Anatomy of a Document

Since publishing that post, I have folded my Epigraphs into the same file as the Bibliography.

I have two main sections in that document:

Works: The “published” material that may contain a quote. I have Books, Essays, Presentations, Verses, Blog Posts, and a few other oddities.
People: These are the people whom I’ve seen/heard quotes, but to which I’m not attributing the associated work.

Below is an example of how I am organizing the information:

** A Commentary on “The Stranger” :essays:
:PROPERTIES:
:AUTHOR: Jean-Paul Sartre
:END:

#+NAME: 20230701T143902
#+begin_quote
We tumble from sentence to sentence, from nothingness to nothingness.
#+end_quote

Jean-Paul Sartre authored the essay A Commentary on “The Stranger”. And a quote from that essay is “We tumble from sentence to sentence, from nothingness to nothingness.”

The #+NAME: 20230701T143902 is a unique identifier for that quote. My eventual goal will be to use that name to extend the org link functionality to search for Epigraphs and link to them. (Sidenote: See Exporting Org Mode Elfeed Links for a reference implementation of linking and exporting elfeed package 📖 links.)

The Bibliography that I publish only includes the books I’ve read. In this new org file, a read Book is: a second level headline tagged with books and marked as DONE.

The Epigraphs that I publish grabs all of the quote (and verse) blocks, and assembles their attribution properties (e.g. Title, Subtitle, and Author).

Capture Templates

Today I wrote three Org-Mode 📖 capture templates:

Work
Quote
Person to Quote

Below is what I’ve added to my org-capture-templates variable:

("w" "Work"
 entry
 (file+headline
  "~/git/org/denote/private/20241124T080648--bibliography__personal.org"
  "Works")
 "%^{Title} %^g\n:PROPERTIES:\n:ID: %(org-id-new)\n:AUTHOR: %^{AUTHOR}\n:END:\n%?"
 :jump-to-captured t)
("q" "Quote"
 plain
 (file+function
  "~/git/org/denote/private/20241124T080648--bibliography__personal.org"
  jf/org/capture/quote-location)
 "#+begin_%^{Type|quote|quote|verse}\n%^{Text}\n#+end_%\\1"
 :prepare-finalize jf/org/capture/quote/name-that-block
 :jump-to-capture t)
("p" "Person to Quote"
 entry
 (file+headline
  "~/git/org/denote/private/20241124T080648--bibliography__personal.org")
 "%^{Name} :people:\n:PROPERTIES:\n:ID: %(org-id-new)\n:END:\n%?"
 :jump-to-capture t)

The Work and Person to Quote are very basic. The Quote is more complicated, relying on two functions.

Breaking Down the Quote Capture

When I capture a quote, I associate that quote with one of the headlines in my bibliography; namely a person or a work. I use jf/org/capture/quote-location to find the position in my Bibliography to insert the quote.

That function:

Prompts to select a tag from the Bibliography.
Prompts me to select an item from a list of entries that include that tag.
Positions the document at the end of the chosen entry.

(defun jf/org/capture/quote-location ()
  "Position to a selected “quotable” element base on prompts.

Narrow focus to a tag, then a named element."
  (let* (
         ;; Prompt to select a tag from the current org file.
         (tag
          (completing-read "Tag: " (org-get-buffer-tags) nil t))
         ;; With the given tag, find all associated headlines that match
         ;; that tag.
         (headline-alist
          (org-element-map
              (org-element-parse-buffer 'headline)
              'headline
            (lambda (headline)
              (when
                  (and
                   (eq (org-element-property :level headline) 2)
                   (member tag (org-element-property :tags headline)))
                (let ((title
                       (org-element-property :title headline))
                      (subtitle
                       (org-entry-get headline "SUBTITLE"))
                      (author
                       (org-entry-get headline "AUTHOR")))
                  (cons
                   (format "«%s»%s"
                           (if subtitle
                               (concat title ": " subtitle)
                             title)
                           (if author
                               (concat " by " author)
                             ""))
                   (org-element-property :contents-end headline)))))))
         ;; Prompt me to pick one of those headlines.
         (headline
          (completing-read
           (concat "Choose from " tag ": ") headline-alist nil t)))
    (goto-char (alist-get headline headline-alist nil nil #'string=))))

Once I’ve selected the work or person I’m quoting, I need to choose if it is verse or quote. A verse is exported such that white space matters (example given (e.g. 📖) , a poem). A quote is non-verse (e.g. , prose, dialogue, what have you).

Last, once I’ve written the quote, I name it. My old mechanism for quotes was that each quote would be a single Denote 📖 file. And Denote would assign an identifier. However, I’m moving away from that and am naming the quote based on the 8 words of the first line. I do that via the :prepare-finalize function jf/org/capture/quote/name-that-block:

(defun jf/org/capture/quote/name-that-block ()
  "Name a quote/verse block from capture block.

Use `denote-sluggify' as the naming function for the quote"
  (let* (
          ;; The evaluated text thus far.  With prompts completed.
          (template
            (plist-get org-capture-current-plist :template))
          ;; By convention the second line of the template is the
          ;; first line of the content block
          (first-line-of-block-content
            (nth 1 (s-split "\n" template)))
          ;; Derive the name of the block by leveraging
          ;; `denote-sluggify'.
          (name
            (s-join "-"
              (seq-take
                (s-split
                  "-"
                  (denote-sluggify 'title
                    first-line-of-block-content))
                8))))
    (save-excursion
      (save-restriction
        ;; Place the name of the quote just above the start of the
        ;; block.
        (goto-char (point-min))
        (insert (format "#+NAME: %s\n" name))))))

Exporting the Epigraphs

This weekend, I wrote code to loop through all of the quote and verse blocks in my Bibliography. That code then randomizes the order of the epigraphs and assembles an HTML version of that export; in part by using the quote’s lineage to get its parent headline (e.g. , a Work or a Person) and the associated metadata (e.g. , Title and Author).

When I don’t name the quote, I don’t export that quote.

The following is the Emacs Lisp 📖 that implements the previously described process. It is the inner part of a block that exports its results to a file.

;; https://lists.gnu.org/archive/html/emacs-devel/2024-09/msg00363.html
(defun seq-shuffle (sequence)
  "Shuffle the given SEQUENCE."
  (cl-assert (sequencep sequence))

  (let* ((vec (seq-into sequence 'vector))
         (length (length vec))
         (n 0)
         (seq-type (type-of sequence)))
    (while (< n length)
      (let ((i (+ n (random (- length n))))
            (tmp (aref vec n)))
        (setf (aref vec n) (aref vec i)
              (aref vec i) tmp))
      (cl-incf n))

    (seq-into vec (if (eq 'cons seq-type) 'list seq-type))))
;; TODO: Create an Epigraph’s document, it pulls from bibliography but has
;; additional text.
;;
;; Find all of the named verse and quote blocks then export accordingly.
;;
;; By convention, the second level headlines are the nodes of interest;
;; that is the person that said something or the book in which it was
;; said.
(s-join
 "\n"
 (let ((epigraphs
  (org-element-map
      (org-element-parse-buffer)
      '(quote-block verse-block)
    (lambda (el)
      ;; Skip un-named blocks as we can’t link to them.
      (when-let* ((id
       (org-element-property :name el)))
        (cons id el))))))
   (cl-mapcar
    (lambda (epigraph)
     (let* ((id
      (car epigraph))
     (el
      (cdr epigraph))
     (type
      (org-element-type el))
     (class
      (if (eq type 'verse-block) "verse" ""))
     (left
            (org-element-property
             :contents-begin el))
           (right
            (org-element-property
             :contents-end el))
     (text
      (buffer-substring-no-properties
       left
       right))
     (lineage
      (org-element-lineage el)))
       (let* ((h-node
         (car
      (seq-filter
       (lambda (el)
         (and
          (eq (org-element-type el) 'headline)
          (= (org-element-property :level el) 2)))
       lineage)))
        (people?
         (member "people" (org-element-property :tags h-node)))
        (title
         (if people?
       ""
     (car (org-element-property :title h-node))))
        (author
         (if people?
       (car (org-element-property :title h-node))
     (org-entry-get h-node "AUTHOR"))))
   (format "<blockquote class=\"%s\" id=\"%s\">%s%s</blockquote>"
     class
     id
     (let ((html
      (s-trim text)))
       ;; (org-export-string-as text 'html t))))
       (if (eq type 'verse-block)
           (s-replace "\n" "<br />" html)
         html))
     (cond
      ((and (s-present? title) (s-present? author))
       (format "\n<footer>&mdash;%s, <cite>%s</cite></footer>"
         author title))
      ((s-present? title)
       (format "\n<footer>&mdash; <cite>%s</cite></footer>"
         title))
      ((s-present? author)
       (format "\n<footer>&mdash; %s</footer>"
         author))
      (t ""))))))
    (seq-shuffle epigraphs))))

Conclusion

Consolidating the books I’ve read and the quotes I’ve gathered has helped me think about additional functionality. Namely the entire ecosystem of Org-Mode :

Agenda
Clocking
Column Views
Sparse Tree

I can also think of my bibliography as a reading list and a list of what I own, owned, am borrowing and so forth.

And as an added bonus, I can call C-u M-x org-capture; which means I walk through the file positioning process (e.g. , pick a tag, pick a tagged concept) and jump to that location.

Put another way, keep leveraging Org-Mode and its nuances. Up next, at least sometime in the future, is to export the content to my blog.

Exploring the Reworking of a Blog Page

jeremy@takeonrules.com (Jeremy Friesen) — Mon, 25 Nov 2024 08:40:40 -0500

I’m exploring the option of removing Hugo 📖 from my build process. I have a todo list of things to consider and explore. One of those is my Bibliography.

Prior to yesterday that page only existed in my Hugo site repository. Most every other page’s canonical version exists in my Denote 📖 directories. And when I publish the post, I export that page to the Hugo site repository.

Yesterday, I spent a bit of time transforming that page into an Org-Mode 📖 file. Instead of representing the entries in an Org-Mode table, I opted for sub-tree entries and a code-block to reproduce the table.

Show Me the Examples

The is as as follows:


#+ROAM_REFS: https://takeonrules.com/site-map/bibliography/

In [[table:249][Most of the Books that I've Read]], I list most of the books
that I've read.  I have chosen to exclude most [[abbr:20221009T115226][RPG]]
books; in part because there are so many.  I plan to create a Ludography; a list
of games that I've played, both [[abbr:20221009T115226][RPG]] and otherwise.

#+begin_src emacs-lisp :exports results :results value html
  (concat
   "<div class=\"table-wrapper\">\n"
   "<table id=\"table-249\" aria-labelledby=\"caption-249\">\n"
   "<caption id=\"caption-249\">\n"
   "Table 249: Most of the Books that I&rsquo;ve Read\n"
   "</caption>\n"
   "<thead>\n"
   "<tr><th scope=\"col\">Title</th><th scope=\"col\">Author</th></tr>\n"
   "</thead>\n"
   "<tbody>\n"
   (s-join "\n"
  	 (org-map-entries
  	  (lambda ()
  	    ""
  	    (concat
  	     "<tr><td><cite>"
  	     (org-element-property :title (org-element-at-point))
  	     (when-let ((subtitle
  			 (org-entry-get (org-element-at-point) "SUBTITLE")))
  	       (format ": %s" subtitle))
  	     "</cite></td><td>"
  	     (org-entry-get (org-element-at-point) "AUTHOR")
  	     "</td></tr>"))
  	  "+LEVEL=2+books+TODO=\"DONE\"" 'file))
   "\n<tbody>\n</table>\n</div>\n")
#+end_src

* Books :books:noexport:
:PROPERTIES:
:COLUMNS:  %ITEM(NAME) %AUTHOR %TODO
:END:

** DONE 1984
:PROPERTIES:
:TYPE: Book
:AUTHOR: George Orwell
:ID:       D8C4A544-993C-4C20-AB42-237267FAE4B4
:END:
** DONE Acts of King Arthur and His Noble Knights, The
:PROPERTIES:
:TYPE: Book
:AUTHOR: John Steinbeck
:ID:       C3461E8A-266B-4E6E-9627-2343CF7F72DA

There are four primary sections:

Line starting with #+ROAM_REFS:
The paragraph starting In [[table.
The Emacs Lisp 📖 code block.
And the Books tree with sub-nodes for each book read and it’s current state (e.g. started, done).

While I don’t use Org-Roam 📖 anymore, I have kept the idea of ROAM_REFS. When a document has a ROAM_REFS entry that means there’s world-wide web representation of that document.

Whenever I publish a blog post, based on configuration Hugo determines that page’s Uniform Resource Locator (URL 📖) . Then I update the underlying Denote document with the URL of that blog post. In my ongoing refactoring, I’m looking to use ROAM_REFS as the target where I’ll publish the page.

I copied the paragraph from my current Bibliography. It’s part of the text that I export.

Next is the Emacs Lisp code block. That block queries the Books section of the document for book’s I’m done reading. It then creates an Hypertext Markup Language (HTML 📖) table and writes that to the exported document.

At present that Emacs Lisp creates a direct representation of the HTML ; in the future I want to shift away from that direct representation. But what I have is an adequate proof of concept.

Reviewing the begin_src emacs-lisp :exports results :results value html line, there are two keywords:

:exports, indicating export the results of evaluating the code but not the code itself.
:results, treat the results as HTML ; meaning we don’t escape the exported value, and instead treat it as raw HTML .

Last is the Books tree. I have set this as :noexport:, meaning the contents are not exported as part of the process. (Sidenote: Instead, as mentioned earlier, the tree is queried by the Emacs Lisp code.)

Emerging Functionality

By shifting from a row in a table to a node entry, I then expose greater functionality.

I can use Org-Mode ’s todo functionality to track the state of my reading; even when I started reading it. The properties drawer allows for capturing additional metadata (such as subtitle). I have a columns view configured so I can switch to reading the entries in tabular form.

In other words, I get the full functionality of Org-Mode . Clocking time, which helps in content capture. I’m also exploring how I would move my Epigraphs into this document as well. Doing that, however, I would be concerned with the size of the file, as it is currently 3700 lines.

I’m doing this slowly as a matter of reflection and self-care; looking to remove Hugo and related scripts from my build process.

I Consider Myself a Writer Who Codes

jeremy@takeonrules.com (Jeremy Friesen) — Fri, 08 Nov 2024 18:43:43 -0500

First a Haiku

Swish swish slide my sole
Through autumn’s collapse my heart
Knows winter then spring

Words Sprout Forth

From seemingly nowhere the title I Consider Myself a Writer Who Codes spilled over my keyboard. In stress I feel urges to write; I assume a form of catharsis.

I haven’t written any novels nor white papers. Nor have I published to any journals. Yet, those words “I consider myself a writer who codes” demanded my attention.

Identity ≠ Job

For 26 years I’ve been a professional software developer. And for almost 14 years, I’ve been an active blogger. As of today, this will be my 1,050th post. (Sidenote: Interested in some writing stats? Take a look at my Post Statistics.)

In years past I didn’t want my profession to be my identity, yet I slipped into that mindset. In part driven to “provide” for my family; but also because its a path of no resistance.

American’s love to ask “what do you do?” with the quiet part—”…for work”—often left unspoken. A few years ago, I deliberately kicked that question aside. And ask other questions, like:

“What’s sparking your interest these days?”
“How are you finding joy?”
“What’s been an interesting victory you’ve recently had?”

The goal of the question is to disrupt the easy path. And when I am asked “What do I do?” I don’t answer with my career.

A Shift

A recent habit I’ve developed is sharing features I’ve developed at work. (Sidenote: Thank you Allison for prompting me to do more of this.) I do this in differing ways each week, but the end results are similar:

A screencast where I’m walking through something
An internal blog post that supplements the screencast

My personal goal: help create an inviting space for people joining my team. And provide the information in two modes so team members have a choice of how to engage with the content. (Sidenote: Note, I have no plans to do videos as part of my personal writing.)

I still code, but I’m taking more time writing documentation both on my approach but also on what I’ve delivered. Creating a bit of a “chain of custody” regarding the development process.

Fundamentally, writing to be understood.

Why Don the Mantle of Writer?

I see a contradiction in saying I am not my profession but I am a writer. Yet writing is my thinking. So I suppose I’m fundamentally ~~saying~~ writing “I’m a thinker who codes.”

And again, there’s this aspect of writing to be understood. By the compiler and/or interpreter.

I also chose to keep the kicker “writer who codes.” Programming is very much a writing exercise. And there’s an art to it.

Art and Drudgery

Yesterday at a local pub a friend and I started talking software languages. For her job she’s possibly going to be learning Go Lang 📖 .

The gist of my perspective is as follows:

I dislike reading Go Lang it’s neither beautiful nor poetic. It reminds me of reading one run-on-sentence after another.

Yet I love working in Go Lang because the tooling is amazing.

But I hate writing it, in that it isn’t as “expressive” instead favoring a dry verbosity paired with mental gymnastics to conform to its type system.

And stuff I’ve written is discoverable yet a bit more rigid. Refactoring requires a different approach.

Ultimately, what I’ve settled on is: Ruby 📖 is to kennings as Go Lang is to sentences/phrases stitched together by a heavy dose of “…and then…”.

Despite All My Rage

Yet in all of my vocalizations and damnation of Go Lang , it’s simply a tool. A means of shaping a solution to a problem. And there’s not much use in cursing at your tools. They don’t care.

But there’s also a matter of discerning both the right tool for the job and keeping your tools well maintained.

I write to help in all of that. To explore my understanding and push against it. But also recognize that the tools, like the jobs that deploy them, can create cages.

Conclusion

I want and need my life filled with art and mystery. I have previously taken an easier path in which I conflated aspects of identity with my profession; though now I’m striving to eschew those sirens’ calls of efficiency and homogeneity.

Yet, due to my current situation I’m more isolated than at other times in my life. (Sidenote: It will pass.) And I recognize this as a potentially precarious state. (Sidenote: Authoritarianism works towards isolation.)

So I’m taking a writer’s route: engaging with conversations that are happening across space and time. I’m reading essays, poetry, fiction, and forewards. (Sidenote: I cannot express how much I love reading forewards of most any book. Show me, tell me, how this thing was made.) I’m cultivating my public and private Rich Site Summary (RSS 📖) feed, helping to broaden my inputs.

I’m trying to ask questions that aren’t the ones spewed forth by auto-pilot. And I’m remember Le Guin, Camus, Butler, and many more are here with me. I, and you, are not alone.

Guarding Against Hugo's Breakage

jeremy@takeonrules.com (Jeremy Friesen) — Tue, 05 Nov 2024 17:21:28 -0500

Today, as I was working/exploring removing Hugo 📖 from my site build chain, I stumbled upon the following:

The primary reason why I redesigned the site was simple:

I hate Hugo.

It is a pain in the ass. It’s fast but keeps breaking to such an extent that just the thought of updating the hugo binary is anxiety-inducing.

—A bit of a redesign

I have a series of Rake 📖 tasks that audit my site’s built files. Why? Because Hugo kept breaking things. So I feel Baldur’s pain, and have worked to guard against it.

I pair this auditing, with something someone told me a few years ago; namely that I’d eventually move towards publishing directly from Org-Mode 📖 .

On Sunday I started thinking about what this might mean.

Why?

Because my build was breaking…and my audits weren’t adequate. So I added more audits, and so long as I use Hugo , I’ll keep doing that.

However, the broken build and the mind-worm of yesteryear started me thinking. First I started thinking about porting more of my build from Rake to Go Lang 📖 commands.

But that mind worm took root, could I remove Hugo from my build? Yes…but I had work to do. I spent time thinking and writing about what that might look like.

It’s not something I’m moving towards quickly, but am instead writing to think through what I need and am willing to set aside.

Regardless, I definitely feel Baldur’s “I hate Hugo.” But for the moment, it does the job.

Adopting Gomponents for Work Project

jeremy@takeonrules.com (Jeremy Friesen) — Fri, 01 Nov 2024 18:19:20 -0400

At work, I’ve been writing a web application powered by Go Lang (Go 📖) . This week I switched from the ginview package found in go-simple-tpl to Gomponents 📖 .

Switching…

Why? Because I began working on the User Interface (UI 📖) , and thinking about these aspects:

Breadcrumbs
Navigation header
Side bar
Internationalization (i18n 📖)
Conditional logic

The simple templating system was going to creak and moan. I know, because it’s in the same lineage of my blog’s templating system.

Documenting the Decision

I wrote the following in my decision:

Let’s look at the inadequacies of the templating:

It’s clumsy to compose a page from different conceptual components; in part because you must bring a consistent albeit non-enforced mindset to those templates.

When a template is broken, there’s a logged error, but the rending engine is still quite happy to kick up to the requesting browser all of the Hypertext Markup Language (HTML 📖) up to the breaking point; while also keeping the initial rendering status.

Pair those two things, and we had two potent ingredients for broken pages and functionality; with a bit of silence of what was broken.

Pivoting to Gomponents

The pivot involved swapping out one template with one page. And getting that to work “as is.” It was quick work mapping the rendered HTML to the function calls to generate an identical HTML document.

With the alternate in place, I started developing the aforementioned UI components (e.g., navigation header, breadcrumbs and side bar). As this was in Go , instead of the simple template language, I could create structs and initializer logic that would make things easier.

Turns out the breadcrumbs and side bar used the same structure with a different initializer.

Leaning on the Compiler

I’ve worked in applications that mixed templates and conditional rendering for authorization and authentication; that crap can get obnoxious to track down.

Using the same tooling for generating pages as the functions meant I could rely on Go and the surrounding ecosystem. For example, with the Language Server Protocol (LSP 📖) tracking called functions in a page gets much easier.

Contrast with a template, in which the editor can’t tell me what got me to that point as well as what’s available.

Put another way, my experience (both immediate and from years of this stuff) tells me that the templating approach will be more brittle.

Bonus Emacs Content

Below is a sample of what could be the inner logic of a function to generate a page’s body.

Body(
        Header(
                Nav(
                        A(Aria("current-page", "true"),
                                Href("/"), Text("Home"),
                        )),
        ),
        Article(
                H1(Text("Welcome Home")),
                P(Text("It's where we put our feet up")),
        )
)

Given that I have these possibly long running nested nodes, I configured my use of the scopeline package 📖 to add call_expression to the scopeline-target variable for Go mode.

Now for those chonky nodes, I can see what is the “opening” tag. A constant need of anyone working in HTML .

What About Huge Tracks of Html?

Turns out as I was building out more pages, I wanted the ability to have chunks of trusted HTML that I could load into the document. Very simple: Raw(varWithRawHtml) did the trick.

Now, where to get that HTML ? Templates!?! Raw files? I thought for a moment, and decided to go the route of i18n . (Sidenote: Via the go-i18n package.) It could address my immediate need while also preparing me for a possible future need.

I did some research, and my assessment on implementation time was about the same. (Sidenote: And in doing so, I uncovered another crease in the application that helped in the conceptual refactor.)

Conclusion

For decades, I’ve used Ruby on Rails 📖 ’ view templates; they are great and quick to use. Until you have a lot of them, and then it starts to hurt. You can introduce helper methods and objects to assist, which is yet another effective strategy.

There’s definitely a tension between the simplicity of a template and the utility of page “objects.”

Ruby on Rails has a very mature and well thought out template-orienting rendering approach. What I found with Go is frustratingly naive and fragile and not all that opinionated; meaning you better be prepared to bring your opinions and implement them.

So I swung towards page objects, appreciating that my compiler can provide guardrails to my UI development. It feels like the alternative would have been to introduce a test that checked every route (and some non existent ones) to see if the page fully rendered.

And there’s probably something I could do in Go to attempt a render then send along the successful document. But for a language that loves its error handling, this silent error was particularly vexing.