notes from /dev/null - dev

Automatically adjusting Emacs to macOS switches in appearance

2023-06-04T11:36:00-07:00

Count me among those who likes using the Auto setting when adjusting the appearance in macOS to either light or dark. Native macOS apps that are coded accordingly can automatically adjust as well, and it turns out that the Yamamoto Mitsuharu fork of Emacs (aka emacs-mac-app) can do this too. But with emacs-mac-app, just because it can detect the appearance change doesn’t mean that all the themes or faces will adjust accordingly too. As such it is typically up to the user to write a pair of custom light and dark mode functions to invoke when the appearance change happens.

For quite some time I’ve been calling these appearance mode functions manually like an animal. Then I recently learned that mac-effective-appearance-change-hook is a thing.

This hook gets invoked upon a macOS appearance change, so it becomes straightforward to write a hook function that tests for the :appearance property returned by
(mac-application-state).

(defun cc/reconfigure-nsappearance ()
  (let ((appearance (plist-get (mac-application-state) :appearance)))
    (if (string-equal appearance "NSAppearanceNameDarkAqua")
        (cc/dark-mode)
      (cc/light-mode))))

(add-hook 'mac-effective-appearance-change-hook 'cc/reconfigure-nsappearance)

A caveat though: the above code will only work with the Yamamoto fork of Emacs for macOS. As of now there seems to be no consensus on how to handle OS-level appearance changes by Emacs core. That said, if the above works for you, then no more manual appearance change calls!

References

Elisp code for cc/reconfigure-nsappearance
Where to get emacs-mac-app:
- MacPorts
- Homebrew

My Emacs Config Repo

2023-05-26T18:06:00-07:00

Emacs configs are always bespoke to its user, but as so much of what I've got configured I've gotten from other Emacs users, here's my config repo to help pay it forward for others interested in using it. Probably what's most notable in my config is its aggressive usage of context-menu-mode. Feel free to peruse, crib, or even critique. Such things are always a work-in-progress.

kickingvegas/cclisp: Emacs configuration files for Charles Choi

Captee 1.1.0 update now available on the App Store

2023-05-22T13:55:00-07:00

There's a big update to Captee (v1.1.0) now available on the App Store. This is a major release for the app, with significant improvements to its user interface and support for converting formatted macOS text to Markdown and Org markup.

If this is your first time hearing about it, hello and welcome! Captee is an app that makes marking up a link (both URL and title) to Markdown or Org a one-step operation straight from the macOS Share menu. Results are stored in the system clipboard for pasting into your favorite editor.

Learn more about Captee at http://yummymelon.com/captee.

Introducing Captee alpha, looking for testers

2023-03-10T14:31:00-08:00

This past February, I started building a macOS app to help me work with Org mode for Emacs It lets you share links and content from another app (typically Safari) via the macOS Share menu and format it in Org markup. It can also support Markdown links so you can work with other editors too. The app is called Captee and here’s a video that demonstrates it at work:

Note that Captee is very much in an alpha/proof-of-concept/bleeding-edge state of polish right now. You’ll get the best results for Captee if you use the macOS Yamamoto Mitsuharu port of Emacs (MacPorts, Homebrew). It supports Org Protocol out of the box, otherwise you will have to use the system clipboard to share content.

To capture selected text via org-protocol you’ll need to define a capture template on the Emacs side first before you use Captee. Here’s an example capture template that uses the placeholders described in the Org capture protocol.

(setq org-capture-templates
      '(
        ("a" "Captee Capture" entry
         (file+headline "~/org/captee.org" "Captee Captures")
         "* %:description\\n%:annotation\\n%i\n%?" :empty-lines 1)
        ))

Okay with all that said, I’m looking for testers. If you’re interested, you can get an alpha build of Captee via this TestFlight link. Please provide feedback via the TestFlight app. Also, I highly recommend you do a deep-read of the release notes before installing or using Captee.

Beautifying Org Plot with YASnippet and Context Menus

2023-01-27T20:15:00-08:00

In using Org tables, it is a natural desire to visualize the data captured in them. Org Plot is a built-in feature in Org to do just that without having to leave Emacs. That said, a couple of caveats with using Org Plot out of the box:

Without configuration, Org Plot output is ugly.
Making Org Plot attractive requires a lot of boilerplate code with unmemorable syntax.

Given the above, it seems easier to punt and export your table data to a spreadsheet to make plots. But why bother with two sources of truth when you can just work with one? This post endeavors to show that you can have beautiful and easy to make plots with Org Plot.

Unconvinced? Come back after watching the video demo below.

Want to know more? Read on…

Background

Under the hood, Org Plot uses gnuplot to generate a graphic plot.

gnuplot is, like Emacs, a robust and highly configurable program. But like Emacs, gnuplot has many default settings that are less than desirable. The net result of this is that gnuplot without configuration produces ugly output. Don’t take my word for it - others say it here, here, here, and here.

That said, gnuplot can be easily configured to have attractive, daresay beautiful, output.

To generate a plot, the function org-plot/gnuplot is invoked via either the key binding C-c " g or calling M-x org-plot/gnuplot. When org-plot/gnuplot is first called, the gnuplot program is initialized and communicated to via the Emacs buffer ✷gnuplot✷. From there org-plot/gnuplot will translate the #+PLOT options for a table into gnuplot commands.

Org Plot Out of the Box

Here’s an example of a table taken from the Org Plot documentation.

#+PLOT: title:"Citas" ind:1 deps:(2 3) type:2d with:histograms set:"yrange [0:]"
| Sede      | Max cites | H-index |
|-----------+-----------+---------|
| Chile     |    257.72 |   21.39 |
| Leeds     |    165.77 |   19.68 |
| Sao Paolo |     71.00 |   11.50 |
| Stockholm |    134.19 |   14.33 |
| Morelia   |    257.56 |   17.67 |

Running org-plot/gnuplot will result in a GUI window plot as shown below:

A couple of observations at this point:

All the PLOT options are put into a single line, but they don’t have to be.

Options can be enumerated over multiple lines for easier comprehension and maintainability.
The key binding for org-plot/gnuplot is quite difficult to remember.

YMMV, but I'll likely never remember C-c " g.
The rendered plot is missing basic elements such as labels for the x and y axis.

There are also no affordances to change the typeface and size for different labels.
While the resultant plot is functional, thin lines and unfilled shapes is unattractive.

In the next section, we’ll show how to address these observations to get more attractive output from Org Plot.

Objectives

Let’s sanity check the things we want to achieve with this post:

Support quick creation of plots from an Org table that you can use and share with colleagues without embarrassment.
Support line and column (called histogram in gnuplot) style plots.
Support configuring basic plot features:
- plot title
- x and y axis labels
- typeface and sizes of the above
Use context-menu-mode as the primary UI to Org Plot.
Not require associative recall of gnuplot commands and options to achieve the above.

Prerequisites

An understanding of Org Plot
A basic understanding of gnuplot
An understanding of YASnippet

Beautifying Org Plot

Set the typeface, and typeface size

Org Plot provides a pass-through interface for the gnuplot command set, which is used to set a multitude of gnuplot options. The line below shows how the typeface and typeface size can be configured via the <typeface> and <typeface-size> parameters. Setting these values will apply to all labels used in the plot.

1	`#+PLOT: set:"termoption font '<typeface>,<typeface-size>'"`

For my taste, I’ll use Futura for <typeface> and 12pt for the <typeface-size>.

Alternately, one could configure the gnuplot terminal and set graphic device, size, and font in a single command. For example on macOS:

1	`#+PLOT: set:"term aqua size 846, 594 font 'Futura,12'"`

Setting the <typeface> and <typeface-size> for the x and y axis labels are done via the gnuplot options xtics and ytics respectively.

#+PLOT: set:"xtics font '<typeface>,<typeface-size>'"
#+PLOT: set:"ytics font '<typeface>,<typeface-size>'"

If <typeface> is omitted, then the current font option value will be used.

Set the histogram (column) style

We’ll configure the style of the histogram with the following code. Refer to the gnuplot documentation on histograms for more detail on syntax.

#+PLOT: set:"style histogram clustered gap 2"
#+PLOT: set:"style fill solid 1.0 border -1"

Set the Legend

The gnuplot option key controls how the legend is rendered. Refer to the gnuplot documentation on key placement and key for more detail on syntax.

1	`#+PLOT: set:"key right top"`

Set the Axis Labels

The options xlabel and ylabel can be set with the appropriate string values for the plot at hand. Replace <xlabel> and <ylabel> accordingly.

#+PLOT: set:"xlabel '<xlabel>'"
#+PLOT: set:"ylabel '<ylabel>'"

Bring it all together

The following code brings all of the above together. The output result from running org-plot/gnuplot is shown below.

#+PLOT: title:"Citas"
#+PLOT: set:"term aqua size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"style histogram clustered gap 1"
#+PLOT: set:"style fill solid 1.0 border -1"
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel 'Cities'"
#+PLOT: set:"ylabel 'Metrics'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"yrange [0:]"
#+PLOT: with:histograms
#+PLOT: ind:1 deps:(2 3)
| Sede      | Max cites | H-index |
|-----------+-----------+---------|
| Chile     |    257.72 |   21.39 |
| Leeds     |    165.77 |   19.68 |
| Sao Paolo |     71.00 |   11.50 |
| Stockholm |    134.19 |   14.33 |
| Morelia   |    257.56 |   17.67 |

Line Plot Example

If the plot is using line style, you can specify the linewidth to use. Here it is specified the value of 3 px.

1	`#+PLOT: with:"lines linewidth 3"`

Adjusting the PLOT header accordingly, the source and resultant plot output is shown below.

#+PLOT: title:"Line Example"
#+PLOT: set:"term aqua size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel 'Some x metric'"
#+PLOT: set:"ylabel 'Some y metrics'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"yrange [0:]"
#+PLOT: ind:1 deps:(2 3)
#+PLOT: with:"linespoints linewidth 3 pointsize 2.0"
| x | y | z |
|---+---+---|
| 0 | 0 | 8 |
| 1 | 3 | 2 |
| 2 | 8 | 3 |
| 3 | 7 | 9 |
| 4 | 2 | 8 |
| 5 | 4 | 8 |

So much boilerplate to type. Can we do something about that?

So at this point we have the desired control and aesthetics but at the cost of a lot of boilerplate PLOT statements. To alleviate typing, we'll use YASnippet, a template system that supports dynamic expansion. Among the key features it provides is the ability to prompt the user to choose different values and based on that value dynamically generate the expanded output.

For the histogram example above, the YASnippet template can be as follows:

# -*- mode: snippet -*-
# name: org-plot histogram
# --
#+PLOT: title:"${1:Line Example}"
#+PLOT: set:"term `(cond ((or (eq (window-system) 'mac) (eq (window-system) 'ns)) "aqua") ((eq (window-system) 'x) "x11") ((eq (window-system) 'w32) "windows"))` size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"style histogram ${2:$$(yas-choose-value '("clustered" "rowstacked"))}${2:$(when (equal yas-text "clustered") " gap 1")}"
#+PLOT: set:"style fill solid 1.0 border -1"
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel '${3:x label}'"
#+PLOT: set:"ylabel '${4:y label}'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"yrange [0:]"
#+PLOT: with:histograms
#+PLOT: ind:${5:1} deps:(${6:2})$0

The above snippet has logic to 1) dynamically choose the terminal type (term), 2) tab key to different fields to populate the plot’s title, axis labels, and histogram style, and 3) define which table column is independent (ind) and which columns are dependent (deps).

Note that different YASnippet templates can be created for different plot types. For this post we’ll only concentrate on variants of lines and histograms.

# -*- mode: snippet -*-
# name: org-plot lines
# --
#+PLOT: title:"${1:Line Example}"
#+PLOT: set:"term `(cond ((or (eq (window-system) 'mac) (eq (window-system) 'ns)) "aqua") ((eq (window-system) 'x) "x11") ((eq (window-system) 'w32) "windows"))` size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel '${3:x label}'"
#+PLOT: set:"ylabel '${4:y label}'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"yrange [0:]"
#+PLOT: ind:${5:1} deps:(${6:2})
#+PLOT: with:"${7:$$(yas-choose-value '("lines" "linespoints" "impulses"))} linewidth 3${7:$(when (equal yas-text "linespoints") " pointsize 2.0")}"$0

At this point we have some snippets but have yet to define a way to invoke them. I don’t intend to frequently make plots but for the times that I do I want it to be easy. Context menus (aka right mouse button menus) offer low cognitive load so let’s go with that.

Integrating Org Plot with Context Menu Mode

Introduced in Emacs 28, context-menu-mode provides built-in conventions for using and customizing right mouse button menus. For this post, I’ll just capture the Elisp that I used to integrate Org Plot into context menus. For further elaboration on how customizing context menus works, please read up my earlier post on it.

Here’s a screenshot showing my Org Plot context menu at work.

At the top level, the menu items are:

The cell reference the pointer is in

Selecting this item will put the cell reference (in this case the string @4$2) into the kill ring.
A sub-menu labeled Insert Plot
Run gnuplot which invokes org-plot/gnuplot

Note that the Org Plot context menu is only shown if the pointer is within the bounds of a table.

Make the Keymap for Insert Plot sub-menu

The following code-snippet illustrates how the sub-menu for Insert Plot is implemented. The keymap variable cc/insert-org-plot-menu holds the menu-item instances, each of which holds a reference to the function that inserts the desired snippet.

(defvar cc/insert-org-plot-menu (make-sparse-keymap "Insert Org Plot"))

(define-key cc/insert-org-plot-menu [lines-interactive]
  '(menu-item "Lines - GUI" cc/org-plot-insert-lines-plot
              :help "Insert lines, linespoints, or impulses style chart for GUI interaction"))

(define-key-after cc/insert-org-plot-menu [lines-timestamp-interactive]
  '(menu-item "Lines Timestamp - GUI" cc/org-plot-insert-lines-timestamp-plot
              :help "Insert lines, linespoints, or impulses style chart with timestamps for GUI interaction"))

(define-key-after cc/insert-org-plot-menu [columns-interactive]
  '(menu-item "Histogram - GUI" cc/org-plot-insert-histogram-plot
              :help "Insert histogram (column) style chart for GUI interaction"))

(define-key-after cc/insert-org-plot-menu [org-plot-menu-single-separator]
  '(menu-item "--single-line"))

(define-key-after cc/insert-org-plot-menu [lines-image]
  '(menu-item "Lines - Image" cc/org-plot-insert-lines-plot-image
              :help "Insert lines, linespoints, or impulses style chart for image creation"))

(define-key-after cc/insert-org-plot-menu [lines-timestamp-image]
  '(menu-item "Lines Timestamp - Image" cc/org-plot-insert-lines-timestamp-plot-image
              :help "Insert lines, linespoints, or impulses style chart with timestamps for image creation"))

(define-key-after cc/insert-org-plot-menu [columns-image]
  '(menu-item "Histogram - Image" cc/org-plot-insert-histogram-plot-image
              :help "Insert histogram (column) style chart for image creation"))

Attach the Insert Plot sub-menu to the Context Menu

The following code shows how to hook the above menu cc/insert-org-plot-menu into the top-level context menu via the function cc/context-menu-addons. The function cc/kill-org-table-reference is used to copy the table reference into the Emacs kill-ring.

(defun cc/context-menu-addons (menu click)
  "CC context menu additions"
  (save-excursion
    (mouse-set-point click)

    (when (org-at-table-p)
      (define-key-after menu [org-table-separator]
        '(menu-item "--single-line"))
      (define-key-after menu [org-table-field-info]
        '(menu-item (format "@%d$%d"
                            (org-table-current-dline)
                            (org-table-current-column))
                    cc/kill-org-table-reference
                    :help "Table field/cell information"))
      (define-key-after menu [org-table-insert-plot]
        (list 'menu-item "Insert Plot" cc/insert-org-plot-menu))

      (define-key-after menu [org-plot-gnuplot]
        '(menu-item "Run gnuplot" org-plot/gnuplot
                    :help "Run gnuplot"))))
  menu)

(defun cc/kill-org-table-reference (e)
(interactive "e")
(kill-new (format "@%d$%d"
                  (org-table-current-dline)
                  (org-table-current-column))))

(add-hook 'context-menu-functions #'cc/context-menu-addons)

Functions to Insert Snippets

There is a general function cc/org-plot-insert-snippet which will insert an arbitrarily named snippet into the buffer at the start of an Org table. Its implementation checks to see if the pointer is within a table before inserting the snippet.

From there a number of helper functions invoking cc/org-plot-insert-snippet with a specific snippet name are defined. These helper functions are referenced by cc/insert-org-plot-menu above.

(defun cc/org-plot-insert-snippet (name)
  "Insert NAME snippet at top of the table.

If the point is not within an Org table then an error message
will be displayed."
  (if (org-at-table-p)
      (progn
        (org-backward-paragraph)
        (yas-expand-snippet (yas-lookup-snippet name)))
    (message "Error: not in org-table")))

(defun cc/org-plot-insert-lines-plot ()
  "Invoke snippet named \"org-plot lines\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot lines"))

(defun cc/org-plot-insert-lines-timestamp-plot ()
  "Invoke snippet named \"org-plot lines timestamp\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot lines timestamp"))

(defun cc/org-plot-insert-histogram-plot ()
  "Invoke snippet named \"org-plot histogram\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot histogram"))

(defun cc/org-plot-insert-lines-plot-image ()
  "Invoke snippet named \"org-plot lines image\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot lines image"))

(defun cc/org-plot-insert-lines-timestamp-plot-image ()
  "Invoke snippet named \"org-plot lines timestamp image\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot lines timestamp image"))

(defun cc/org-plot-insert-histogram-plot-image ()
  "Invoke snippet named \"org-plot histogram image\"."
  (interactive)
  (cc/org-plot-insert-snippet "org-plot histogram image"))

What about timestamps?

Org Plot has the ability to work with both Org-style and regular timestamps as the independent column. The snippet below shows how this is supported.

# -*- mode: snippet -*-
# name: org-plot lines timestamp
# --
#+PLOT: title:"${1:Line Example}"
#+PLOT: set:"term ${2:`(cond ((or (eq (window-system) 'mac) (eq (window-system) 'ns)) "aqua") ((eq (window-system) 'x) "x11") ((eq (window-system) 'w32) "windows"))`} size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel '${3:x label}'"
#+PLOT: set:"ylabel '${4:y label}'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"xtics format '${5:%Y-%m-%d}'"
#+PLOT: set:"yrange [0:]"
#+PLOT: timeind:1
#+PLOT: ind:${6:1} deps:(${7:2})
#+PLOT: with:"${8:$$(yas-choose-value '("lines" "linespoints" "impulses"))} linewidth 3${8:$(when (equal yas-text "linespoints") " pointsize 2.0")}"$0

Note that there is a current bug in Org Mode as of 9.6.1 that requires declaring the timeind option. For timestamps to work, timeind must be set to 1.

#+PLOT: title:"Weight"
#+PLOT: set:"term aqua size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel 'Date'"
#+PLOT: set:"ylabel 'Kg'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"xtics format '%Y-%m-%d'"
#+PLOT: set:"yrange [0:]"
#+PLOT: timeind:1
#+PLOT: ind:1 deps:(2)
#+PLOT: with:"lines linewidth 3"
| Date             |   Kg |
|------------------+------|
| <2010-02-21 Sun> | 95.0 |
| <2010-02-22 Mon> | 93.0 |
| <2010-02-23 Tue> | 92.0 |
| <2010-02-24 Wed> | 91.5 |
| <2010-02-27 Sat> | 91.0 |
| <2010-03-01 Mon> | 92.0 |

Here’s the resultant plot:

Writing to SVG, JPEG, or PNG

The above snippets are configured to output to a gnuplot GUI terminal. The snippet below is tuned to write a file to either a SVG, JPEG, or PNG format.

# -*- mode: snippet -*-
# name: org-plot histogram image
# --
#+PLOT: title:"${1:Line Example}"
#+PLOT: set:"term ${2:$$(yas-choose-value '("svg" "jpeg" "png"))} size 846, 594 font 'Futura,12'"
#+PLOT: type:2d
#+PLOT: set:"style histogram ${3:$$(yas-choose-value '("clustered" "rowstacked"))}${3:$(when (equal yas-text "clustered") " gap 1")}"
#+PLOT: set:"style fill solid 1.0 border -1"
#+PLOT: set:"key right top"
#+PLOT: set:"xlabel '${4:x label}'"
#+PLOT: set:"ylabel '${5:y label}'"
#+PLOT: set:"xtics font ',10'"
#+PLOT: set:"ytics font ',10'"
#+PLOT: set:"yrange [0:]"
#+PLOT: with:histograms
#+PLOT: ind:${6:1} deps:(${7:2})
#+PLOT: file:"${8:image}.${2:$(cond ((equal yas-text "svg") "svg") ((equal yas-text "jpeg") "jpg") ((equal yas-text "png") "png"))}"$0

Concluding Thoughts

Org Plot can be made much more attractive and usable with YASnippet and context menus.
The code examples (particularly the snippets) above can be refined to be both more generalized and richer in capability.
For Org Table users, one less reason to leave Emacs for a spreadsheet program. 😏

Acknowledgments

Thanks to yantar92Orgcontr on the #org-mode IRC channel for the assistance in identifying the issue with timeind.

References

How I Personally Use Mobile Computing in 2023

2023-01-23T15:23:00-08:00

Not necessarily profound, but some personal thoughts/checkpoints on how I use “mobile” computing in 2023. Motivated by following up with this post I made back in January 2010.

By far, an iPad with an external keyboard has become my primary and preferred means of communication.

Text messages, email, video, and even voice calls: I do all these things through my iPad nearly all the time. It has been this way for the past four years.
With cloud based messaging services, my bias is to use a mobile phone as a read-only device whenever I'm dealing with text.

Most of my communication writing is done on the iPad using an external keyboard.
Emotionally, I don’t think of a laptop as a “mobile” device anymore.

My 90% use case is to run it as a docked system connected to a monitor, keyboard, and mouse. This is the case regardless if I’m at home or at work. It’s basically a desktop (albeit portable) computer to me now.
- That said, the option to run it as a laptop is still a great win for the cases when I need to. I’d still observe that these are exceptions to my day-to-day behavior.
Related to the above, whenever I need mobile access (via iPad or iPhone) to my laptop’s files, I use a terminal emulator.

I got an iPad 2nd generation on the day of its release in 2011, and for most of its life I found it great for consuming media but not much else. It was far from being a system I could do work with which entails a lot of writing, both of software and its documentation, journaling, and project planning. After a couple of years it went into the bookcase, unused.

Around 2018 I refreshed and got a 6th gen iPad. As a media consumption device, it was still great. But I was still concerned that I couldn't use it to create in the ways I was interested in. Then I learned about Blink shell, a terminal emulator that launched in 2017. Running a Blink on an iPad with an attached external keyboard turned it into the best 80’s-style thin client that could never have existed back in the 80’s. Coupled with mosh and tmux, as long as I had an internet connection, I could do work. An aside: I'd also observe that my dependency on Blink shell is co-mingled with using Emacs and in particular emacsclient over the years.

Since then, it’s a rare day that I don’t use my iPad.
Noted with chagrin that with the above, I’ve turned my laptop into a server.
Outside of some file data, most all the data state that I work with is “cloud”-based.

I rarely deal with manual data sync (outside of git repos) across multiple clients (laptops, desktops, tablets, phones). Most all of the data sync I use is automatically managed at the application level.

Customizing the Emacs Context Menu

2023-01-03T00:53:00-08:00

Addendum - Tuesday March 31, 2026

Most of the Elisp in this post is now available as a package named Anju. Read more about it in the post "Announcing Anju".

Summary

(best played full screen, no audio)

Novice Elisp programmer (me) succeeds in customizing Emacs right mouse button menu behavior. Uses this knowledge to copy common actions seen in native (in particular macOS) applications.

This post captures how I got here.

Background

Context menus triggered by a right mouse button event are a commonly used GUI pattern. Emacs provides support for this via context-menu-mode which was introduced in version 28. Customizing context-menu-mode requires some understanding how menus are structured. I won’t go into too much detail describing how Emacs menus work here, but hopefully will impart enough about it to get you going.

What I Did

Requirements

Context menu should only show menu actions based on context. Different criteria for context are enumerated below and can be used in combinatorial fashion for a particular action.
- buffer mode (major and minor)
- region is selected (active) or not
- buffer-file-name is version controlled

Preconditions

My customized context menu relies on these packages being installed. YMMV. Also, you must use Emacs version ≧ 28.

osx-dictionary - Dictionary lookup using the macOS-installed dictionary
google-this - Search for term in Google
reveal-in-folder - Reveal current file in native OS folder.
Export an Org Region to RTF - Elisp snippet for using macOS command line utility textutil to convert Org markup to rich text format
ox-slack - Exports Org markup to Slack markup
- ox-gfm - dependency required by ox-slack

Turn on `context-menu-mode`

I’ve got context-menu-mode turned on in both prog-mode-hook and text-mode-hook which should cover most all my programming (Python, ObjC, Swift, Elisp, C, etc.) and text (Org, Markdown) modes via inheritance. It is also turned on for dired and shell modes.

(add-hook 'text-mode-hook 'context-menu-mode)
(add-hook 'prog-mode-hook 'context-menu-mode)
(add-hook 'shell-mode-hook 'context-menu-mode)
(add-hook 'dired-mode-hook 'context-menu-mode)

At this point, you should be able to right mouse button click anywhere on a buffer see a menu. But that menu is quite unexciting. We’ll address this next.

Let’s Make a Menu

A common context menu action is to take selected text and either capitalize, upper, or lower case it, as illustrated below.

We’ll implement the above as a sub-menu with the user-defined variable cc/transform-text-menu whose value is a sparse keymap. The code below illustrates how this is implemented.

;; Transform Text
(defvar cc/transform-text-menu (make-sparse-keymap "Transform Text"))

(define-key cc/transform-text-menu [tranform-text-uppercase]
  '(menu-item "Make Upper Case" upcase-region
              :help "Upper case region"))

(define-key-after cc/transform-text-menu [tranform-text-lowercase]
  '(menu-item "Make Lower Case" downcase-region
              :help "Lower case region"))

(define-key-after cc/transform-text-menu [tranform-text-capitalize]
  '(menu-item "Capitalize" capitalize-region
              :help "Capitalize region"))

Note that the actual commands to execute the transformations (upcase-region, downcase-region, capitalize-region) are invoked in each menu-item call.

Note that at this point cc/transform-text-menu only defines the sub-menu but it is not attached to anything yet.

Let’s Make a Menu, Part 2

Let’s make another sub-menu with the user-defined variable cc/org-emphasize-menu, this time to format (emphasize) selected text in Org-mode as shown below.

The source to achieve this is described below. Note that the actual emphasis commands (cc/org-emphasize-bold|italic|code|…) in this menu are built on-top of org-emphasize, which generalizes what type of emphasis (bold, italic, code, etc.) to use as a function argument.

;; Org Emphasize
(defvar cc/org-emphasize-menu (make-sparse-keymap "Org Emphasize"))

(define-key cc/org-emphasize-menu [org-emphasize-bold]
  '(menu-item "Bold" cc/org-emphasize-bold
              :help "Bold"))

(define-key-after cc/org-emphasize-menu [org-emphasize-italic]
  '(menu-item "Italic" cc/org-emphasize-italic
              :help "Italic"))

(define-key-after cc/org-emphasize-menu [org-emphasize-code]
  '(menu-item "Code" cc/org-emphasize-code
              :help "Code"))

(define-key-after cc/org-emphasize-menu [org-emphasize-underline]
  '(menu-item "Underline" cc/org-emphasize-underline
              :help "Underline"))

(define-key-after cc/org-emphasize-menu [org-emphasize-verbatim]
  '(menu-item "Verbatim" cc/org-emphasize-verbatim
              :help "Verbatim"))

(define-key-after cc/org-emphasize-menu [org-emphasize-strike-through]
  '(menu-item "Strike Through" cc/org-emphasize-strike-through
              :help "Strike through"))

(define-key-after cc/org-emphasize-menu [org-emphasize-reset]
  '(menu-item "Reset" cc/org-emphasize-reset
              :help "Remove emphasis"))

;; Convenience functions to emphasize by type
(defun cc/org-emphasize-bold ()
  (interactive)
  (org-emphasize ?*))

(defun cc/org-emphasize-italic ()
  (interactive)
  (org-emphasize ?/))

(defun cc/org-emphasize-code ()
  (interactive)
  (org-emphasize ?~))

(defun cc/org-emphasize-underline ()
  (interactive)
  (org-emphasize ?_))

(defun cc/org-emphasize-verbatim ()
  (interactive)
  (org-emphasize ?=))

(defun cc/org-emphasize-strike-through ()
  (interactive)
  (org-emphasize ?+))

(defun cc/org-emphasize-reset ()
  ;; org bug: this won't work when org-hide-emphasis-markers is turned on.
  (interactive)
  (org-emphasize ?\s))

With the above source, we now have a variable cc/org-emphasis-menu that holds the emphasis sub-menu. We are ready to hook this into the context menu!

Customizing the Context Menu

Customizing the context menu requires:

Defining a new function (in this case cc/context-menu-addons) to capture the customized context menu behavior.

Hooking that new function (cc/context-menu-addons) into the variable context-menu-functions via the add-hook function.

(defun cc/context-menu-addons (menu click)
  "CC context menu additions"
  (save-excursion
    (mouse-set-point click)
    (define-key-after menu [open-in-finder]
      '(menu-item "Open in Finder" reveal-in-folder-this-buffer
                  :help "Open file (buffer) in Finder"))

    (when (region-active-p)
      (define-key-after menu [osx-dictionary-lookup]
        '(menu-item "Look up" osx-dictionary-search-word-at-point
                    :help "Look up in dictionary"))

      (define-key-after menu [occur-word-at-mouse]
        '(menu-item "Occur" occur-word-at-mouse
                    :help "Occur")))

    (when (and (bound-and-true-p buffer-file-name)
               (vc-registered (buffer-file-name)))
      (define-key-after menu [vc-separator]
        '(menu-item "--single-line"))

      (define-key-after menu [magit-status]
        '(menu-item "Magit Status" magit-status
                    :help "Magit Status"))
      (define-key-after menu [ediff-revision]
        '(menu-item "Ediff revision…" cc/ediff-revision
                    :help "Ediff this file with revision")))

    (when (region-active-p)
      (define-key-after menu [transform-text-separator]
        '(menu-item "--single-line"))
      (define-key-after menu [tranform-text]
        (list 'menu-item "Transform" cc/transform-text-menu)))

    (when (and (derived-mode-p 'org-mode) (region-active-p))
      (define-key-after menu [org-emphasize]
        (list 'menu-item "Org Emphasize" cc/org-emphasize-menu))

      (define-key-after menu [org-export-to-slack]
        '(menu-item "Copy as Slack" org-slack-export-to-clipboard-as-slack
                    :help "Copy as Slack to clipboard"))

      (define-key-after menu [copy-as-rtf]
        '(menu-item "Copy as RTF" dm/copy-as-rtf
                    :help "Copy as RTF to clipboard")))

    (when (region-active-p)
      (define-key-after menu [google-search]
        '(menu-item "Search with Google" google-this-noconfirm
                    :help "Search Google with region"))))
    menu)

;; hook into context menu
(add-hook 'context-menu-functions #'cc/context-menu-addons)

Note that the implementation of cc/context-menu-addons has logic to query context information such as buffer mode, whether text is selected (region-active-p), and source control (vc-registered) to determine if a menu-item is to be rendered.

Extras: Clean up Ediff UX

IMHO, Ediff has terrible UX out of the box, especially when quitting where it leaves a bunch of buffers strewn about. The code below helps mitigate some of that behavior thanks to this posted comment in StackExchange.

;; Pass buffer-file-name into Ediff
(defun cc/ediff-revision (e)
  "Invoke ediff-revision with buffer-file-name."
  (interactive "e")
  (ediff-revision buffer-file-name))

;; Fix Ediff quit UX behavior by closing all buffers
(defvar my-ediff-last-windows nil)

(defun my-store-pre-ediff-winconfig ()
  (setq my-ediff-last-windows (current-window-configuration)))

(defun my-restore-pre-ediff-winconfig ()
  (set-window-configuration my-ediff-last-windows))

(add-hook 'ediff-before-setup-hook #'my-store-pre-ediff-winconfig)
(add-hook 'ediff-quit-hook #'my-restore-pre-ediff-winconfig)

Also note that my Ediff variables are set as follows:

'(ediff-keep-variants nil)
'(ediff-split-window-function 'split-window-horizontally)
'(ediff-window-setup-function 'ediff-setup-windows-plain)

Observations

Going through this exercise, a couple of observations:

Customizing an Emacs menu requires a lot of boilerplate. Maybe because I’m naive to Elisp and Emacs conventions, there might be a cleaner implementation, but it seems like I gotta work too hard (both learning and implementing) to customize a menu.
I tried to implement context-dependent logic in the :visible property documented in Extended Menu Items in the function cc/context-menu-addons. Didn’t work. Elisp experts, definitely would like your feedback.
Having the function cc/context-menu-addons hooking into a global variable content-menu-functions seems like a very monolithic design. Maybe there’s a cleaner pattern here?
Embark looks awesome, but sometimes you just want a mouse.
Beyond thrilled to have gotten here. Hope you feel likewise!

Acknowledgments

Thanks to Philip Kaludercic’s post that helped considerably in my understanding of how to customize a context menu.

Thanks to deaddyfreaddy for providing informal code review on Reddit for an earlier version of this post. This current post has been amended to reflect his feedback.

References

Introducing regfmt

2022-10-25T11:31:00-07:00

Sometimes a project you've had in the mental back burner for decades calls to you again, but this time you pay attention. So it is with regfmt, a command line utility that I spent this past month working on.

Backstory

While I was in grad school back in the early 1990's the department had prescribed using the AT&T troff tools for writing papers. Among those tools was one called dformat, which enabled you to easily draw out control register-style data formats using a domain specific language (DSL).

dformat was a great tool for its time but over the years got consigned to bit rot and ultimately forgotten by many. Among the reasons for it being forgotten was that it only supported the troff specific pic drawing language and used a make-shift DSL for its input.

Today

The world moved on and settled on other tools for writing and drawing. That said, the fundamentals of computer design haven't changed and control registers are still a thing, so the need to draw them out is still a thing, and drawing them by hand is still painful.

In the intervening time from the early '90s to 2022, I've run into times when I wished I had something like dformat but modern to use for writing technical documentation. What's modern you say? How about having:

a common vector graphics file format output such as SVG which can then be easily converted to a raster format (png, jpg, etc.).
an input specification that is based on a common data serialization language.

In the early summer of 2022, I got to thinking about dformat and how it could be re-imagined for today and realized wow, all the pieces I needed were there:

Use SVG for the output format
Use YAML for the input format
Use CSS to style the output
Implement in Python which has support for all of the above.

In October 2022, I found the cycles to go to work on this.

Announcing regfmt

regfmt is a Python command line utility to generate SVG diagrams for control register-style data formats. It is inspired by the dformat command from the troff family of tools, however re-imagined using contemporary (circa 2022) file formats.

Python installation: PyPI: https://pypi.org/project/regfmt/

Source Repository: GitHub: https://github.com/kickingvegas/regfmt

Example output of regfmt

Features

SVG output
Modern configuration input file formats
- YAML for register configuration
- CSS for styling SVG output

Try it out!

If you need a tool like this, please take the time to try it out. Any feedback would be appreciated!

Requirements

Python: ≧ 3.9

Installation

regfmt supports installation via PyPI. Is is recommend that you do this in a Python virtual environment.

$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) pip install regfmt

Sweeping dust and cobwebs

2022-09-22T15:18:00-07:00

Dang, time passes - it's been over two years since I posted to this blog. Thinking about being more active here, but making no promises. That said, took the better part of today updating the blog software (https://getpelican.com) to be current. Surprisingly easy.

notes from /dev/null - dev

Automatically adjusting Emacs to macOS switches in appearance

References

My Emacs Config Repo

Captee 1.1.0 update now available on the App Store

Introducing Captee alpha, looking for testers

Beautifying Org Plot with YASnippet and Context Menus

Background

Org Plot Out of the Box

Objectives

Prerequisites

Beautifying Org Plot

Set the typeface, and typeface size

Set the histogram (column) style

Set the Legend

Set the Axis Labels

Bring it all together

Line Plot Example

So much boilerplate to type. Can we do something about that?

Integrating Org Plot with Context Menu Mode

Make the Keymap for Insert Plot sub-menu

Attach the Insert Plot sub-menu to the Context Menu

Functions to Insert Snippets

What about timestamps?

Writing to SVG, JPEG, or PNG

Concluding Thoughts

Acknowledgments

References

How I Personally Use Mobile Computing in 2023

Customizing the Emacs Context Menu

Summary

Background

What I Did

Requirements

Preconditions

Turn on context-menu-mode

Let’s Make a Menu

Let’s Make a Menu, Part 2

Customizing the Context Menu

Extras: Clean up Ediff UX

Observations

Acknowledgments

References

Introducing regfmt

Backstory

Today

Announcing regfmt

Example output of regfmt

Features

Try it out!

Requirements

Installation

Sweeping dust and cobwebs

Turn on `context-menu-mode`