Erik L. Arneson — Writer and Software Developer

Emacs as the Freelancer's Command Center

2026-04-10T00:00:00+00:00

Freelancing for small businesses and organizations leads to a position where you are juggling a number of projects for multiple clients. You need to keep track of a number of tasks ranging from software development to sending emails to project management. This is a lot easier when you have a system that can do a bunch of the work for you, which is why I use Emacs as my freelancer command center.

I would like to share some of the tools and workflows I use in Emacs to help me keep on top of multiple clients’ needs and expectations.

Organization with org-mode

It should be no surprise that at the center of my Emacs command center is org-mode. I have already written about it a lot. Every org-mode user seems to have their own way of keeping track of things, so please don’t take my organizational scheme as some kind of gospel. A couple of years ago, I wrote about how I handle to-do lists in org-mode, and I am still using that method for to-do keywords. However, file structure is also important. I have a number of core files.

`Freelance.org`

This top-level file contains all of my ongoing business tasks, such as tracking potential new clients, recurring tasks like website maintenance and checking my MainWP dashboard. I also have recurring tasks for invoicing, tracking expenses, and other important business things.

This file is also where I have my primary time tracking and reporting. Org-mode already supports this pretty nicely, I just use the built-in clocktable feature.

`Clients/*.org`

Clients that have large projects or ongoing business get their own file. This makes organization a lot easier. All tasks associated with a client and their various projects end up in these individual files. The important part is making sure that these files are included in the time-tracking clock table and your org-mode agenda, so you can see what is going on every week.

References and Linking

I have C-c l bound to org-store-link and use it all the time to link to various files, directories, URLs, and even emails. I can then use those links in my client notes, various tasks in my to-do list, and so on. This helps me keep my agenda organized even when my filesystem and browser bookmarks are a bit of a mess.

Email with mu4e

I have been reading and managing my email in Emacs for over 25 years. There have been a few breaks here and there where I have tried out other software or even web mail clients, but it has always been a headache. I return to Emacs! Long ago, I used VM (which seems to have taken on new life!), but currently I use mu4e.

This gives me a ton of power and flexibility when dealing with email. I have custom functions to help me compose and organize my email, and I can use org-store-link to keep track of individual emails from clients as they relate to agenda items. I even have a function to convert emails that I have written in Markdown into HTML email, and one that searches for questions in a client email to make sure I haven’t missed anything.

The ability to write custom code to both process and create email is extremely powerful and a great time saver.

Writing Code

I don’t know what else to say about this, I use Emacs for doing all of my software development. I make sure to use Eglot whenever there is a language server available, and I try to leverage all the fancy features offered by Emacs whenever possible. The vast majority of projects for clients are PHP (thanks WordPress), Go, JavaScript, and TypeScript.

Writing Words

Previously, I have shared quite a bit about writing in Emacs. I like to start everything in org-mode, but I also write quite a bit in Markdown. Emacs has become a powerful tool for writing. I use the Harper language server along with Eglot to check grammar and spelling.

Track All Changes with Magit

Version control is essential, a lesson I have learned over 30+ years of software development. While Git is not part of Emacs, the software I use to interface with Git is. Magit is a Git user interface that runs entirely in Emacs. I use it to track my writing, my source code, and even all of my org-mode files. Using version control is so essential that I have a weekly repeating agenda task reminding me to check all of my everyday files to make sure I have checked-in my changes for the week.

Thinking Music with EMMS

I like to have some soothing background music when I am programming, writing, or otherwise working on my computer. However, if that background music has lyrics, it can be really distracting. It is easy to make a playlist for various suitable SomaFM channels to load into EMMS (the Emacs Multimedia System) using the command M-x emms-play-playlist.

Try saving the following into playlist.el somewhere, and using it the next time you are writing:

 ;;; This is an EMMS playlist file Play it with M-x emms-play-playlist
 ((*track* (type . url) (name . "https://somafm.com/synphaera.pls"))
  (*track* (type . url) (name . "https://somafm.com/gsclassic.pls"))
  (*track* (type . url) (name . "https://somafm.com/sonicuniverse.pls"))
  (*track* (type . url) (name . "https://somafm.com/groovesalad.pls")))

And make sure to check out SomaFM’s selection to find some good background music that suits your tastes!

And the tools I have missed

There are undoubtedly Emacs tools that I have missed in this brief overview. I have been wracking my brain as I write, trying to see what I have forgotten or overlooked. Frankly, Emacs has become such a central part of the organization for my freelancing that there are probably many tools, packages, and processes that I use every day without thinking about it too much.

Emacs makes it possible for me to freelance for multiple clients and small businesses without losing my mind with organization and task management. The tools it provides allow me to stay on top of multiple projects, handle client relationships, and keep track of years worth of tasks, communications, and projects. Without it, I’d be sunk!

What Emacs tools are you using to manage your freelance business? I am always looking for ways to improve or streamline my process.

The featured image for this post comes from Agostino Ramelli’s Le diverse et artificiose machine (1588). Read more about it on the Public Domain Review.

An Emacs Application Launcher for Regolith

2025-11-19T00:00:00+00:00

I run the Regolith Desktop Environment on my laptop, which I love because it provides a convenient GNOME wrapper and interface for the i3 tiling window manager. Regolith relies on a program called ilia for application launching, and sometimes ilia gets caught in some kind of CPU-churning state that locks up my whole system. I have not been able to figure out what is causing it, so I (of course) turned to Emacs for a solution.

Turning to `consult-omni`

Armin Darvish has created a powerful Emacs package called consult-omni, which provides a wrapper around consult for searching through any number of information sources. I believe consult-omni was originally intended to query web search engines and document databases, but Darvish has also provided a search mode for your local desktop applications, and can act as an application launcher.

Darvish provides an example application launcher in his consult-omni YouTube tutorial. The source code is straightforward, but I wanted to tweak it just a little. You can view his original on the project’s wiki on GitHub. You can watch him explain his technique below.

After a few tweaks, here is what I came up with.

(defun consult-launcher ()
  "A launcher suitable for use from a window manager."
  (interactive)
  (let* ((width (floor (* 0.6 (display-pixel-width))))
         (height (floor (* 0.6 (display-pixel-height))))
         (left (floor (* 0.2 (display-pixel-width))))
         (top (floor (* 0.2 (display-pixel-height))))
         (params `((name . "omni-launcher")
                   (width . ,(cons 'text-pixels width))
                   (height . ,(cons 'text-pixels height))
                   (left . ,left)
                   (top . ,top)
                   (minibuffer . only)))
         (frame (make-frame params)))
    (with-selected-frame frame
      (select-frame-set-input-focus frame)
      ;; If i3 is running and there is a control socket, let's tell
      ;; it we are a floating frame.
      (if (getenv "I3SOCK")
          (call-process "i3-msg" nil nil nil
                        (format "[id=%s] floating enable"
                                (s-trim (shell-command-to-string "xdotool getactivewindow")))))
      (unwind-protect
          (progn (consult-omni-apps-static ".*" (propertize "> " 'face 'consult-omni-path-face))
                 nil)
        (progn
          (when (frame-live-p frame) (delete-frame frame))
          nil)))))

I made two changes to get this to work nicely with i3. First, I removed the yequake dependency. Second, I added a call to i3-msg that sets the launcher frame as floating, which makes it much nicer to use. Like Darvish’s version, you can run this from the command line:

emacsclient -e '(consult-launcher)'

Adding an `ilia` fallback

Don’t tell all the other Emacs users, but I don’t have Emacs set up to launch automatically when I start my computer and log into X11. I probably should, huh? Also, there are times when I (gasp!) shut down Emacs, usually to restart it or fix something that I have broken. When those times happen, I want to be able to launch applications, so I need a failsafe in case consult-launcher isn’t available!

To solve this, I created a simple shell wrapper script, which looks like this:

#!/bin/bash

# Check if Emacs server is running by looking for the server socket
# Default server name is "server", but you can change this if needed
SERVER_NAME="${EMACS_SERVER_NAME:-server}"
SERVER_FILE="${XDG_RUNTIME_DIR:-/tmp}/emacs/${SERVER_NAME}"

if [ -S "$SERVER_FILE" ]; then
    # Emacs is running, use emacsclient to launch your application
    emacsclient -e '(consult-launcher)'
else
    # Emacs is not running, fall back to ilia
    ilia -p apps
fi

If you want to use this, the important part is that SERVER_FILE points to the socket that your Emacs server uses. Make sure that emacsclient and ilia are both in a reasonable location so your shell can find them, then bind this command to whatever you usually use to launch ilia.

By the way, if you are using Regolith’s normal method of launching ilia, you can add your shell script to your Regolith configuration pretty easily. Open $HOME/.config/regolith3/Xresources in your text editor, and add the line:

wm.program.launcher.app: /path/to/your/launcher.sh

You can then run xrdb -override $HOME/.config/regolith3/Xresources and it should work! Good luck.

Drawbacks

One of the nice things about ilia is that it keeps track of applications your run frequently, so they tend to bubble up to the top of its application listing. The Emacs method doesn’t do that. I don’t mind so much, I always end up typing in application names. It is fun to use Emacs as an application launcher, and I hope that it helps me avoid the CPU-churn problem that ilia has been experiencing far too often.

Have I come up with a clever solution, or a lazy workaround? I’m looking forward to hearing your thoughts.

Interviewed on "Prot Speaks"

2025-08-18T00:00:00+00:00

Well-known Emacs package creator Protesilaos Stavrou interviewed me for his video podcast series, “Prot Asks.” We talked about a wide variety of topics, from Emacs to podcasting to Portland to public transit. I thought it was a great time, and perhaps you will like it, too!

You can read and view the video on Prot’s website and blog, or you can go straight to YouTube, or you can watch it embedded here below.

Note that Prot is looking for people to talk to on this series! You can join in by signing up on his website.

P.S. In the video, I promised that I would do another Emacs Carnival blog post, and I will, I swear! It is in my org-mode to-do file.

Writing Experience (Emacs Carnival)

2025-07-07T00:00:00+00:00

This is my contribution to month two of Greg Newman’s Emacs Carnival. The topic this month is “Writing Experience,” which is perfect, since I write in Emacs all the time. In fact, I am writing this blog post in Emacs right now!

Emacs Writing History

I do not know how long I have been writing in Emacs, but I have documents written in LaTeX from the early 2000s that were definitely written in Emacs, and I know those weren’t the first. I guess what is interesting about my writing experience in Emacs is how it has developed over the years. Where I originally wrote everything in plain text or LaTeX, over time I moved to org-mode and Markdown.

Writing LaTeX in Emacs taught me to view documents and writing the same way I view source code. Since all of my writing was in text formats, I could easily use version control software to store archives full of text. I began by using Concurrent Versions System (CVS), but eventually moved to Git. I have a few Git repositories with writing, but my biggest dates back to 2009. Those early commits are all LaTeX and plain text files.

commit c64500897e2509bc3316d252cda10a9119384933
Author: Erik L. Arneson <pXXX@XXX.XXX>
Date:   Sat Dec 5 10:51:06 2009 -0800

    Initial import of an old repository.

The oldest org-mode file in my writing repository dates to December 27th, 2010, and is titled “Beer and Pizza.” The commit message indicates that I pulled some writing over from another repository in this commit, so obviously I had been writing with org-mode for quite a while. I know, for instance, that “Beer and Pizza” was an article that I wrote for an early incarnation of Southern Oregon Magazine, and my notes are dated back to February of that year.

Org-mode Is A Life-changer

You have probably read other people’s experience with writing in org-mode in Emacs, so instead of sharing an exhausting list of all the life-changing, writing-improving things that it has brought me, here are a few bits that I really love about it.

It is fantastic at organizing writing projects. From being able to shift around headings and blocks of text, to combining to-do lists with writing projects, to being able to create macros and include different files—all of these things make org-mode perfect for working on medium and large projects. I write everything from blog posts to podcast scripts to books in org-mode, and it helps me stay organized.

I do not have to write in Word or Google Docs. The export functions in org-mode do a great job creating Word files, ODT files, HTML files, and all kinds of formats. If org-mode’s export abilities aren’t good enough, it can also interface with pandoc to cover all the other cases! This means I get to use all of my familiar tools and processes when writing, and I don’t have to worry about awful word processing software!

Everything I need to write can happen in org-mode! I have several websites that are built entirely out of org-mode. When I need to create slides for a lecture, I do it in org-mode. When I write adventures for Dungeons & Dragons, I do it in org-mode. When I need to whip up a spreadsheet to handle my household budget, I do it in org-mode. When I need to write a formal letter, I do it in org-mode. Frankly, it is so expressive and flexible, that I don’t need to use other tools for writing. It’s all Emacs and org-mode.

Emacs Can Be Distraction-Free

I have a hotkey connected to writeroom-mode, which plonks me right into a full-screen, distraction-free writing mode. Easy as pie! This means that when I really need to get down to business and get a lot of writing done, I don’t need to switch to a new app, leave my familiar tools behind, or go through any extra trouble. It’s just right here, built in.

No Going Back

I’ve been writing with Emacs for decades. It is my comfortable writing spot. I honestly cannot see myself abandoning it for another writing tool, because it works for me. I just used a couple of commands to check my three biggest writing repositories, and I have approximately 630,000 words written in org-mode between them. That’s a commitment!

I am aware that there are a lot of people out there using Emacs for writing, so I am excited to see what others share. I’m very pleased with Greg Newman’s choice for this second writing topic.

Edit: I realized that what I was calling my second biggest writing repository was actually my third biggest. I updated some numbers to reflect another 130,000 words of writing I found.

Configuring Orgzly Interaction with Directory Local Variables

2025-01-28T00:00:00+00:00

I use Orgzly Revived on my phone to capture to-do items, tasks, writing ideas, and projects. Its files are then synced with an ownCloud server. Those same files are also constantly open in Emacs on my computer, which means there can be some gnarly issues with things getting out of sync. It took me a while to figure out a good way to manage this, and in this brief blog post, I would like to share my solution.

Setting up a remote storage system is outside the scope of this server. Orgzly Revived works well with Dropbox, ownCloud, and nextCloud, though support for the other two is nicer as it can support automatic syncing in more situations. The Orgzly Revived documentation has an excellent description of how that configuration works.

Note that to keep things simple, I keep my Orgzly Revived files and only those files in a directory on my remote server. On my computer, the location for these files is ~/org/orgzly/, which is how I shall refer to it later on.

Configuring Orgzly Revived Auto-sync

To configure the auto-sync capabilities in Orgzly Revived, go to the settings screen in the app and then navigate to Sync > Auto-sync. Ensure that the following options are toggled on:

Auto-sync
Note created
Note updated or deleted
App started or resumed

This ensures that Orgzly Revived is constantly checking your remote storage and both fetching and uploading changes.

Configuring Emacs and Org-mode

On my computer, I want any changes that Orgzly Revived has updated to be automatically loaded into Emacs. Since I always leave Emacs running, that means it needs to detect changes on the disk for those particular files. I use two different methods to do this. First, in my init file, I have the following piece of code:

(setq orgzly-directory (expand-file-name "~/org/orgzly/"))
(add-to-list 'revert-without-query (rx bol 
                                       (eval orgzly-directory) 
                                       (+ (not "/")) ".org" 
                                       eol))

This uses the rx macro to easily create a regular expression that matches any filename ending in ".org" in the directory containing Orgzly Revived files. You may need to play around with the regular expression to get the right match. By adding those files to revert-without-query, Emacs will not bug you with extra questions and confirmations when changes are detected. However, this only works when auto-revert-mode is enabled!

At first, I thought there may be a way to enable auto-revert-mode on a file-by-file basis, but quickly realized that this could cause too many problems with creating new files in the Orgzly Revived app. Eventually, I realized that the solution would be to make a .dir-locals.el file in ~/org/orgzly/. Open that file in Emacs, and stick the following in it.

((nil . ((eval . (auto-revert-mode 1)))))

That ensures that any file in that directory will have auto-revert-mode enabled.

Once you have done this, you can add task files or inbox files in ~/org/orgzly to your org-agenda-files variable, and they will show up in your agenda views as usual.

Hopefully these instructions work for you. Please let me know if you can see any improvements or problems with the way I have implemented this. Happy task tracking!

Examining To-Do Lists in Org-mode

2024-10-22T00:00:00+00:00

When you are self-employed, you need to be very well organized. There is never anybody looking over your shoulder, reminding you of everything on your to-do list. You don’t have a project manager reminding you of every step in your big projects. I use Org-mode in Emacs to manage all of my tasks, to-do lists, and projects.

Many people have already written about why Org-mode is a good choice for this, so I am not going to. I will just mention that many years ago, perhaps around 2007, I read Getting Things Done by David Allen and got inspired to implement something like it in Org-mode. The system has slowly evolved over the years, but it has also become unweildy.

For the past few years, I had been tagging my tasks with the states TODO, NEXT, and DONE, primarily. I had some extra states sitting around for things that got canceled or delegated, and at some point I added a WAITING tag for when I needed somebody else to finish something, first. But the problem was, the TODO items really piled up. They became uncomfortable to sort through.

Inspired by a blog post by Sacha Chua earlier this week, I cleaned up my to-do states. I added STARTED and SOMEDAY, then went through the big list of outstanding items and re-evaluated their proper states. SOMEDAY won in 80% of cases, which really cleaned up the list. Now I can begin my day with a custom agenda command that looks for just NEXT and STARTED tasks, so I know what is most important. And I can end my day looking at TODO tasks to see if any should be switched to NEXT.

Here is what my configuration looks like now. First, I configure org-todo-keywords to handle the various states that my to-do items need. I am hoping that someday I’ll pare this down, but for now, this works.

(setq org-todo-keywords 
      '((sequence "TODO(t)" "NEXT(n)" "STARTED(s!)" "WAITING(w@/!)" "|" "DONE(d!)")
        (sequence "SOMEDAY(o)" "|")
        (sequence "|" "DELEGATED(g@/!)" "CANCELLED(c!)")))

I then added a “daily driver” command to my agenda to let me see the most important tasks today. This would probably be a good place for add-to-list instead of setq, but it’s just an example!

(setq org-agenda-custom-commands
      '(("n" "Next tasks" ((todo "STARTED")
                           (todo "NEXT")))

Next, after Sacha suggested it in a post on Mastodon, I configured to-do items to automatically switch to the STARTED state when I clock-in to them.

(setq org-clock-in-switch-to-state "STARTED")

Finally, I have been playing around with configuring org-stuck-projects to be more useful. I tag all of my projects with a @project tag, and then have my to-do entries underneath them as keywords. I do not think that this works as intended yet. I don’t think I will be able to figure out the proper settings here until I have another stuck project; let’s hope that never happens, and I never need this report.

(setq org-stuck-projects '("+@project/-DONE-SOMEDAY"
                          ;; Keywords to identify non-stuck projects
                          ("TODO" "NEXT" "STARTED")
                          ;; Keywords to identify stuck projects.
                          ("WAITING")
                          ""))

The only lesson that I can really hope to share with you, dear reader, is that it is a good idea to examine your task management system regularly to fine-tune it to your needs. What I have noticed is that I can come up with great task management plans, but the implementation rarely survives contact with the real world.

If, upon reading this, you have questions or suggestions, especially for org-stuck-projects, I would love to hear about it in the comments, or on Mastodon. Thank you for reading!

Many Posts of Interest for January 2024

2024-01-18T00:00:00+00:00

Once again, I have collected far too many links over far too long a period of time. Anyhow, here is a collection of blog posts and links from around the web that I found to be good reading over the past couple of months. Is it too late in January to say Happy New Year?

2024 has been a pretty weird year for me so far. I spent the first couple weeks of the year in isolation, and then Portland got hit with a Snowpocalypse (I love how that’s a regular thing now), followed by freezing rain. This is the third day in a row that the sidewalk outside my front door is basically an ice skating rink. That means it’s a great time to do some reading!

Security

Privacy is Priceless, but Signal is Expensive [Security] I really appreciate this incredible breakdown of Signal’s costs and how they use donations. Signal is cool. You should be using it. For real.
Breaking Laptop Fingerprint Sensors (Bruce Schneier) [Security] Do people actually use their laptop fingerprint sensors? I hate mine. I just disable the dang things and use a password.
Surveillance by the US Postal Service (Bruce Schneier) [Security] To Catch a Thief, starring Cliff from Cheers.
Senator Ron Wyden of Oregon opens discussion of push notification surveillance by Apple and Google (Rick Turoczy) [Security] There is some interesting legal stuff going on around the ability of tech companies like Apple and Google to use push notifications to capture user data that could be used for nefarious purposes. Definitely a story to keep your eye on!
Holding NSA’s Feet To The Fire (jcs) [Security] Here is a second post about Senator Ron Wyden. He appears to be fighting the good fight! Go Senator Wyden!

Emacs

Transient for convenience with emms [Emacs] Tory Anderson shares a really convenient EMMS control panel that uses the new version of transient.
Talk to Emacs with a GPT4 Co-Worker [Emacs] Gallagher Pryor shares a method he has for speaking to Emacs using ChatGPT-4. This is from back in November, so perhaps he has a package now!
Jeremy Friesen: Mentoring VS-Coders as an Emacsian (Jeremy Friesen) [Emacs] I really enjoyed this talk about moving people away from VS Code and toward Emacs. The big takeaway for this talk seemed to be that demonstrating what Emacs could do was going to be more effective than just arguing. Let Emacs win just by letting it do what it does.
Jeremy Friesen: Test Driving a Campaign Status Document (Jeremy Friesen) [Emacs] This post has some superb ideas for running a TTRPG campaign from Emacs. I’ve been doing this for a while, but my documents get really messy. I need something a bit more structured.
EmacsConf backstage: Using Spookfox to publish YouTube and Toobnix video drafts (Sacha Chua) [Emacs] I love how crazy this is: using spookyfox to work with YouTube’s crappy interface to do things to videos. Go Sacha!
Charles Choi: Improving Emacs isearch Usability with Transient (Charles Choi) [Emacs] This is pretty cool. I recently learned about how rich the isearch feature set is, but I haven’t played around with it a ton yet. Another thing to add to my Emacs to-do list!
William Denton: Basic citations in Org (Part 1) (William Denton) [Emacs] This is an excellent introduction to how citations work in org-mode. There are four parts in the series so far, so keep reading!

Programming

Pike’s Rules Of Programming (jcs) [Programming] These are some good rules, even if they can make some parts of programming a little less exciting.
Variations on styling variables in SSGs (Bryce Wray) [Programming] I am still using Sass a lot more than the vanilla CSS stuff that should be replacing it. Also, I am starting to see that this is a change I’ll need to take in my future WebDev adventures.
Firefox on the brink? (Bryce Wray) [Programming] Bryce Wray is warning (or predicting?) that Firefox may be in a very dangerous spot in its loss of user share. This is really disappointing, given how evil Chrome continues to be. And it’s only going to get more evil. Convince your friends to run Firefox!
Zachary Kanfer: Numberdle! (Zachary Kanfer) [Programming] This is a really fun browser game for people who enjoy numbers more than words. Move over, Wordle!!

History

Finally, here’s something fun to share with the kids.

The Teddy Bear Was Once Seen as a Dangerous Influence on Young Children Before gifting stuffed animals to the wee ones in your life, consider that bears are dangerous!

EmacsConf 2023 Retrospective

2023-12-04T00:00:00+00:00

This past weekend was EmacsConf 2023. It was held entirely online, which was great because I could attend in my pyjamas! Since it happened on Eastern Standard Time and I live on the Pacific coast, I found the pyjama-enablement to be quite conducive to an excellent conference experience. Here are some things I learned by waking up at 5:30 in the morning this weekend!

Before getting into the good stuff, I should add that I did not spend a lot of time taking notes during the conference. Instead, I usually jumped straight into my Emacs configuration and started tinkering and fooling around. This means that I’ve probably left out some great stuff.

Emacs Advocacy

There were a couple of talks about Emacs advocacy, but the one that I paid the most attention to was Mentoring VS-Coders as an Emacsian by Jeremy Friesen. I think the big takeaway was that he got more mileage out of showing the power of Emacs than he did by trying to argue with users of other editors. Emacs users tend to already understand the power and flexibility of the tool they are using; just show it off, let it do the work.

However, another topic that was brought up in a number of talks was that having all of your projects available in the same tool seems to enable a better, richer type of thinking. Being able to both write effectively and program efficiently in Emacs helps generate more complete thoughts. It also seems to spur creativity and help people conceptualize projects better. This may be a big part of advocacy, as very few other programming editors are also good at writing and note-taking, which leads me to …

Writing

I do a lot of writing in Emacs, and I’m not the only one. James Howell gave a talk about authoring and presenting university courses with Emacs. I have also written and presented lectures and classes using just Emacs. It has the power to create slides, lecture notes, and even handouts from the same source. There were a few more great talks about writing, including another one by Jeremy Friesen (he seems to do a lot of cool stuff).

Howard Abrams talked about playing table-top role playing games (TTRPGs) in Emacs. He focused on how the pandemic had encouraged him to look into solo TTRPGs, which led him to Ironsworn. Howard then created a full Ironsworn system in Emacs that allows him to play the game on its own. I am including this under the “Writing” section because solo TTRPG play is a lot like writing fiction, it’s just that you use rules and randomness to help you figure out where the story goes. One of the best things about this talk is that the pre-recorded video was produced by his son. It looks great!

Hyper Things (Hyperbole and Hyperdrive)

I watched a talk about Hyperbole again this year. This is an Emacs package that I would really love to figure out how to use, but it just doesn’t integrate cleanly into my configuration nor my workflow. I tried it last year and got kind of annoyed at it. I gave it another try during Rob Weiner’s talk, but this time I couldn’t even get Hyperbole to properly set itself up. Anyhow, I gave up on it again. Until next year, Hyperbole!

Now Hyperdrive, on the other hand, was something new and interesting. Joseph Turner and Protesilaos Stavrou gave a talk on hyperdrive.el: Peer-to-peer filesystem in Emacs. Set up was extremely simple; it just worked. I was quickly able to share hyperdrive files and links with others. It remains to be seen what my use-case for Hyperdrive will be, but I look forward to watching this project develop.

EMMS

Yoni Rabkin gave a talk on the Emacs Multi-Media System (EMMS). I like EMMS, but I don’t use it as regularly as I should. However, Rabkin’s talk encouraged me to give it another chance. I am currently listening to Information Society in EMMS while I write this blog post. I suspect that like most people, I don’t really dig into my old MP3 collection as much as I should. This is a good excuse! Rabkin was also happy to remind the audience that EMMS can handle streaming online music sources and playing pretty much every kind of media. It’s worth exploring EMMS again!

Overall Impression

I loved EmacsConf this year. I also loved it last year. The organizers and moderators did such a great job running this conference, and it seemed to have a lot of attendees. I followed along on IRC and on Mastodon, and there was a ton of great talk happening. In addition, the Q&A sessions that I saw were filled with enriching conversation. I’m really looking forward to next year. Maybe I’ll find something on which to present!

Posts of Interest for November 2023

2023-11-16T00:00:00+00:00

I was planning to make posts like this more regularly, but I entered into a period where I was thinking, huh, I am not collecting very many links. But I was wrong, I was collecting links. I collected too many. And now look at everything you have to read! I am sure these links will keep you occupied for a while.

Security

Tech CEO Sentenced to 5 Years in IP Address Scheme (BrianKrebs) [Security] This is an interesting story: five years in prison for stealing IP addresses! I guess you shouldn’t do that.
Defense in depth: Layering your security coverage (Sue Poremba) [Security] Security isn’t just at the edge. Layers are very important, as this article reminds us.
How The Thompson Hack Worked (jcs) [Security] Aaaah! This is an amazing look at Ken Thompson’s 1983 Turing Award lecture. How can we trust software? Do we trust software? You’ll enjoy this one and it will tickle your inner computer nerd.
Pentesting vs. Pentesting as a Service: Which is better? (Josh Nadeau) [Security] What is pentesting and how does it work? Well, now you can know.

Emacs

Whatever happened to Guile-based Emacs? [Emacs, Mastodon] This thread on Mastodon has some insights into what ever happened to a Guile-based Emacs.
Andrey Listopadov: You don’t need a terminal emulator (Andrey Listopadov) [Emacs] Andrey Listopadov explains how he stopped using a terminal emulator because he’s all about that Emacs. Nice!
Emacs Line Wrapping (jcs) [Emacs] For several years, I have been dealing with a line-wrapping annoyance in Emacs that I just couldn’t figure out. It turns out it was filladapt, a package that apparently isn’t used often anymore, but I hadn’t noticed. I disabled the package and everything just works the way I want it to. Arrrgh!
Does Working From Home Damage Productivity? (jcs) [Emacs] I have mostly worked from wherever-I-want for the last 14 years, and I’d have it no other way.

Games

Kensett: A Free 19th Century Urban Cartography Brush Set for Fantasy Maps (K. M. Alexander) K.M. Alexander shares a lot of cool brush sets for creating maps for fantasy games. I have been trying to figure out how to use them, and this one really caught my eye. Check out all of their brush sets!
Lovat’s Genesis: City of Darkness (K. M. Alexander) I am once again running a D&D game, with a homebrewed campaign, so I think it will be fun to include a few RPG-related posts every once in a while. Seeing how others get their inspiration is really helpful when I need to find some of my own.

History

The Silent Treatment: Solitary Confinement’s Unlikely Origins [Pub 20231101] A very curious history of solitary confinement and its origins, presented by the Public Domain Review. This is worth a read.
What Emoji Tell Us About the History of Tea I love the strange history of tea, and the Smithsonian has managed to tie this history to tea emoji. So that’s cool.
Divide and Concur: A Radical Plan for Peace in Europe (1920) [History] This is an amazing and bizarre plan for bringing peace to Europe in the 1920s. It is worth looking at and puzzling over.

Posts of Interest for 13 October 2023

2023-10-13T00:00:00+00:00

This is the second of my “posts of interest” posts. This week, I have also included some interesting Mastodon posts, because the Emacs community on Mastodon is thriving like crazy. It is really a blast to see so much interest in Emacs and so much activity.

If Mastodon interests you, find me there!

Programming (1)

Scheme in the browser: A Hoot of a tale – Spritely Institute Yes, SCHEME IN THE BROWSER. This is pretty cool, go check it out.

Emacs (6)

Text showdown: Gap Buffers vs Ropes [Programming, Rust] Troy Hinckley has been working on building the core of Emacs in Rust. This sounds like a very difficult project, and it is informative and interesting to follow along. The latest entry in his saga involves various ways of storing and working with text buffers, along with many benchmarks. This is an interesting read!
ELPA and Emacs Zine (September 2023) The new ELPA and Emacs Zine has released its latest issue, with some pretty interesting stuff about the current state of tree-sitter and how development is progressing.
Emacs Macros [Mastodon] Emacs macros remain kind of a mystery to me, but they were presented in an interesting way recently: these are ways to provide a high level of automation in Emacs without learning how to program Emacs Lisp. Well, they are worth checking out, then!

Taking advantage of tree-sitter [Mastodon] This is a really cool Emacs function that takes advantage of tree-sitter to copy the current function. I think it might need something to detect if tree-sitter is active, and error out if not.

(defun my-copy-function-name-with-ts()
  (interactive)
  (let ((funcname
         (substring-no-properties
          (treesit-node-text
           (treesit-node-child-by-field-name (treesit-defun-at-point) "name")))))
    (kill-new funcname)
    (message "Copied name: %s" funcname)))

XMPP in Emacs [Mastodon] Fabio Natali on Mastodon reports that his XMPP usage would be more consistent if Emacs supported it better. In particular, he misses E2E encryption support. I’ve also had a lot of difficulty with moving to XMPP.
Alex Schroeder: Posting to Oddµ from Emacs (Alex Schroeder) Alex Schroeder provides a simple, straightforward way to use the url package in Emacs to post stuff to another service. In this example, he uses Oddμ.

Security (4)

C-suite weighs in on generative AI and security (Chris McCurdy) More on the adoption of generative AI and security risks. 96% of business leaders say adopting generative AI makes a security breach likely in their organization within the next three years! That’s certainly something to think about.
10 years in review: Cost of a Data Breach (Jonathan Reed) Data breaches are dang expensive! We all know that. This piece explores some of the most important factors in preventing and mitigating data breaches. There have been some changes in recent years, some of which are caused by the rise of importance in AI. That means you should probably read the article.
The fraud was in the code (Molly White) In the SBF court case, they actually used a code review to show fraud.
Bounty to Recover NIST’s Elliptic Curve Seeds (Bruce Schneier) Here is a delightful story about the history of NIST elliptic curve cryptography and how things came to be. Also, a cryptographic puzzle about where they may be going!

Posts of Interest for 6 October 2023

2023-10-06T00:00:00+00:00

This is my first attempt at using elfeed-curate to collect interesting blog posts and share them. I have also attempted to subscribe to the RSS feed for the #Emacs hashtag on Mastodon, but that doesn’t seem to be working correctly yet. I’ve seen other blogs do similar things, but is this useful for my blog? I don’t know! Let me know what you think.

Computers (4)

The intriguing announcement of Cloudflare Fonts (Bryce Wray) [Programming] Oooh, this is cool. Bryce Wray talks about the introduction of Cloudflare Fonts!
What to know about new generative AI tools for criminals (Mike Elgan) [Security] Generative AI is still a minor concern for security professionals, but the threat is rising! This is an interesting look at the state of the art and current means for addressing the threat.
Alex Schroeder: 2022-03-20 Torchbearers and bodyguards (Alex Schroeder) [Emacs] Alex Schroeder continues his exploration of running tabletop RPGs using Emacs. Check out the other blog posts in the series—they are a lot of fun. I have been playing with Emacs for running TTRPGs, as well. Someday I’ll explain my methods.
Elfeed-curate (jcs) [Emacs] Elfeed-curate sounds like a really neat package. This is my first annotation using that package, which I will soon attempt to export.

Portland (1)

Tour of Untimely Departures – SOLD OUT! (lfadmin) The Tour of Untimely Departures is an annual event at Lone Fir Cemetery in Portland. But guess what? It’s already sold out! It sold out a while back, but I didn’t notice because my RSS feed for the Friends of Lone Fir was broken.

Configuring Emacs 29.1 for Go Development

2023-08-01T00:00:00+00:00

Now that I have installed Emacs 29.1, I needed to get it set up for Go development for a project. I was interested in taking advantage of both the new Tree-Sitter integration, and the new Eglot language server client. However, they were mildly tricky to set up! Here is what I did.

Configuring Tree-Sitter for Go

If you follow the excellent How to Get Started with Tree-Sitter instructions from Mickey Peterson, you will have a great head-start on getting Tree-Sitter working for most of your favorite languages (and probably Java, too). However, those instructions didn’t cover everything I needed for Go. When I tried running M-x go-ts-mode, Emacs complained about a missing gomod module. Baffling!

I couldn’t find any information in the Emacs documentation about where to find this missing module. I looked around on the net and found Camden Cheek’s tree-sitter-go-mod, and added that to my list of recipes. My treesit-language-source-alist then looked like this:

(setq treesit-language-source-alist
 '((bash "https://github.com/tree-sitter/tree-sitter-bash")
   (cmake "https://github.com/uyha/tree-sitter-cmake")
   (css "https://github.com/tree-sitter/tree-sitter-css")
   (elisp "https://github.com/Wilfred/tree-sitter-elisp")
   (go "https://github.com/tree-sitter/tree-sitter-go")
   (gomod "https://github.com/camdencheek/tree-sitter-go-mod")
   (dockerfile "https://github.com/camdencheek/tree-sitter-dockerfile")
   (html "https://github.com/tree-sitter/tree-sitter-html")
   (javascript "https://github.com/tree-sitter/tree-sitter-javascript" "master" "src")
   (json "https://github.com/tree-sitter/tree-sitter-json")
   (make "https://github.com/alemuller/tree-sitter-make")
   (markdown "https://github.com/ikatyang/tree-sitter-markdown")
   (python "https://github.com/tree-sitter/tree-sitter-python")
   (toml "https://github.com/tree-sitter/tree-sitter-toml")
   (tsx "https://github.com/tree-sitter/tree-sitter-typescript" "master" "tsx/src")
   (typescript "https://github.com/tree-sitter/tree-sitter-typescript" "master" "typescript/src")
   (yaml "https://github.com/ikatyang/tree-sitter-yaml")))

Note that the package is named go-mod but go-ts-mode expects it to be named gomod. I wish this were documented somewhere! In any case, I was then able to use M-x treesit-install-language-grammar for both go and gomod. Finally, M-x go-ts-mode worked!

After going through this process, I found Robert Enzmann’s post about automatically using Tree-Sitter. He has created the treesit-auto package, now available on MELPA, that does most of this work for you. It is a much faster way of solving the gomod mystery, so give it a shot!

Configuring Eglot for Go

I’d been using lsp-mode for ages, but with Emacs 29.1 including Eglot, I decided to make the switch.

In my Go project, I ran M-x eglot and was immediately met with an error:

[eglot] Server reports (type=1): Error loading workspace folders (expected 1, got 0)
failed to load view for file:///path/to/my/project: err: go command required, not found: exec: "go": executable file not found in $PATH: stderr: 

I’ve got Go installed in /usr/local/go, and /usr/local/go/bin is definitely in my exec-path variable in Emacs. It looked like Eglot wasn’t propagating exec-path down to its subprocesses. How annoying! I did a quick search through the list of Eglot-related variables and the Eglot documentation and no solution seemed immediately forthcoming.

So I took the cheap way out and made a symlink. In my shell, I ran:

sudo ln -sf /usr/local/go/bin/go /usr/local/bin/go

It is a dumb trick, and I am sure there is a better way to solve it. Do you know of one? Please comment and let me know!

What Else?

My exploration has revealed that there’s a lot of work left to do in the Emacs Tree-Sitter world. There are plenty of languages major modes that don’t yet have a ts-mode equivalent, and plenty of others that still need a lot of work.

It’s too soon for me to say if this setup is preferrable to my previous configuration. But I am really looking forward to playing around with Eglot’s features and exploring the capabilities of Tree-Sitter.

Installing Emacs 29.1 on Ubuntu 22.04 LTS

2023-07-31T00:00:00+00:00

You have probably heard by now, but Emacs 29.1 has been released! Here are some reasons to upgrade and how to do so right away if you are running Ubuntu 22.04 LTS.

What’s New with Emacs?

One of the most exciting new features for me is TreeSitter support, which provides incremental parsing capabilities for programming languages and other formatted files. This means that programming support will be getting faster, more comprehensive, and even better in future Emacs packages.

Other new features include native WebP image support, pure GTK support, and the ability to use emacs -x in the first line of a script, which could lead to some fun applications of Emacs Lisp. Read all of the release notes here!

Installing on Ubuntu 22.04 LTS

I am too impatient to wait for somebody to release a packaged version, so I installed Emacs 29.1 from source. It is fairly straightforward, though you will need to do a couple of special things to get all of the features you want.

Installing the Requirements

Note: All of the commands in this post assume you are using bash.

Most of the extra libraries and packages you will need to build Emacs 29.1 are covered in the build dependencies for the stock Emacs package. However, to take advantage of some of the cool extra features now included in Emacs, you’ll need to install a few more things.

sudo apt build-dep emacs
sudo apt install libgccjit0 libgccjit-10-dev libjansson4 libjansson-dev \
    gnutls-bin libtree-sitter-dev gcc-10 imagemagick libmagick++-dev \
    libwebp-dev webp libxft-dev libxft2

Preparing to Build

In order to get native compilation (a feature added in Emacs 28) working correctly, you will need to make sure your shell instructs the build system to use gcc-10.

export CC=/usr/bin/gcc-10
export CXX=/usr/bin/gcc-10

Get the Source Code and Let’s Compile!

Download the Emacs 29.1 source code from a nearby GNU mirror and then extract it! Then follow the instructions below. Note that you might want to take a closer look at the options to ./configure. If you want native compilation, but don’t want to use the “ahead of time” option because it’s slow, you can remove the =aot. You might also want to stick Emacs in a different location using the --prefix option. For example, I used --prefix=/opt/emacs29.

cd emacs-29.1
./autogen.sh
./configure --with-native-compilation=aot --with-imagemagick --with-json \
    --with-tree-sitter --with-xft
make -j$(nproc)

The build might take a while. With the “ahead of time” compilation, I think my build took ten or fifteen minutes. But once it is complete, try running your new Emacs binary to make sure it works.

./src/emacs -Q

If it works, install it!

make install

What’s Next

You’ve got Emacs 29.1 installed and running! This is exciting. Which new features do you want to try first?

Get started with tree-sitter!
Run M-x eglot and see how cool language servers can be!
Read about other new features in Emacs 29.1!

I hope this article was helpful, and that you are enjoying the latest version of Emacs! I used it to write this blog post, so you know I am.

Update: Org to DOCX with Citations

2023-06-20T00:00:00+00:00

Last year, I wrote about converting Org to DOCX with pandoc. Well, that particular method has needed some improvements. I needed to also support converting Markdown files, and more vitally, I needed to support the new-ish org-cite citation format.

The first thing I did was update to the latest version of Pandoc. Next, I had to learn how Pandoc’s citations work. Note that you have to enable the citations extension as well.

For citations to work, you need to have a Citation Style Language (CSL) file. Zotero comes with a ton of them, so check your Zotero installation for examples.

In the updated fish shell function below, you will want to update both refdoc and csldoc to point to your reference DOCX file and your CSL file, respectively.

function org2docx --description 'Generate a DOCX file using a custom reference document'
    set -l refdoc "$PATH_TO_REFERENCE_DOCX"
    set -l csldoc "$PATH_TO_CSL"
    set -l fromfmt (string match -r '(?:org|md)$' $argv)
    set -l base (basename -s .$fromfmt $argv)

    echo Generating $base.docx ...

    pandoc --from "$fromfmt"+citations \
        --citeproc --csl $csldoc \
        --reference-doc $refdoc -o $base.docx $argv
end

And there you have it! Now you can convert both Org files and Markdown files to DOCX. And I am sorry that you have to use DOCX!

Writing and Reviewing Jupyter Notebooks

2023-05-18T00:00:00+00:00

A recent project involves delivering a finished product as a collection of Jupyter Notebooks. This process involves using Emacs for writing, Git for version control, and a slightly tricky process for enabling non-Jupyter, non-Emacs users to perform document review.

Writing—just like programming—ideally includes a review process before anything is delivered to the client. Even first drafts need at least two readers before delivery. I’ve previously discussed how I use Org Mode and Pandoc to deliver DOCX files, and DOCX or ODF files unfortunately remain the easiest way to track changes and edits among word processor users.

Since Jupyter Notebooks are basically JSON documents, the best way to keep track of changes and revisions is using some kind of version control. Here is one process using Git and GitHub.

When my notebook files are ready for review, converting them to DOCX files is pretty straightforward.

First, I use the jupyter command line tool to convert to Markdown, like this:
```
jupyter nbconvert --to markdown *.ipynb
```

Next, I use Pandoc to convert to DOCX using a reference link.

for file in *.md
    pandoc --reference-doc $path_to_refdoc -o $file.docx $file
end

Renaming files with Dired

At this point, I needed to rename all of the DOCX files and move them to the proper shared folder, so my reviewer could get to them and know what’s going on. We have a naming format for filenames that helps us track project and versions, so all of the files needed to have at least a v1 in them.

Emacs has a file manager called Dired, which contains powerful features that allow you to modify directory contents just like any other buffer. I now had a bunch of files that ended in .md.docx that needed to instead end in -v1.docx. Here is the process I used to easily rename them.

In Emacs, use M-x dired to open the directory.
Use C-x C-q to run dired-toggle-read-only.
Use M-% to run query-replace, and replace .md.docx with -v1.docx.
Finish “writing” the directory with C-c C-c.

All done! It was nice and simple. The DOCX files were finally properly named and ready for review.

Pattern Matching and Tail Recursion in Emacs Lisp

2022-11-19T00:00:00+00:00

Functional programming offers a bunch of really cool programming patterns. Two that I really enjoy are tail recursion and pattern matching, especially how they are implemented in OCaml. However, I spend a lot of time writing Emacs Lisp now, and I was wondering if I could find a way to use these patterns in that language.

It turns out that it is possible, thanks to named-let and pcase. It isn’t as pretty and elegant as OCaml, but at least I get to keep excercising those parts of my programming brain. Maybe next I’ll try to figure out currying in Emacs Lisp.

Note that this blog post includes some really dumb examples, because that’s usually how I learn these things best.

Pattern Matching with `pcase`

Most programmers will be familiar with the granddaddy of pattern matching, the switch/case construct. This is present in many, many programming languages, especially those in the ALGOL family.

However, pattern matching can be so much more! Instead of simple equality checks, pattern matching extends the switch/case concept to include testing for all kinds of patterns and conditionals.

Lisp programmers will already be familiar with cond, which can be used to sequentially test for conditionals. However, functional language programmers have probably fallen in love with a more mature and sophisticated form of pattern matching that cond doesn’t totally satisfy.

Fortunately, Emacs Lisp has pcase, the pattern-matching conditional. Here is an example of its use to duplicate car, which is the dumbest possible example I could think of.

(defun ela/car (lst)
  (pcase lst
    (`(,head . ,_)
     head)
    (_
     nil)))

You can see that pcase has a backquote syntax for matching various constructs, such as with the `(,head . ,_) piece. This matches a cons cell and binds the CAR to head while ignoring the CDR.

The next case is just _, which is a catch-all matching operator.

In the real world, you’d probably want some type checking and error correction, but I promised very simple examples. Check out the full range of matching capabilities for pcase, and then read about all of the backquote patterns you can also use.

Tail Call Optimization with `named-let`

Tail call optimization (TCO) is the programming language feature that allows efficient tail recursion without overflowing your stack. It is increasingly common in languages today, though from what I’ve seen, it always involves caveats.

In Emacs Lisp, the easiest way to use TCO that I’ve come across is the named-let macro. With it, you define a function that can get “unrolled” inside another function. For example, here is a simple function that calculates a factorial using tail recursion.

(defun ela/fact (in-num)
  (named-let rec-fact ((accu 1)
                       (num in-num))
    (pcase num
      ((guard (< 0 num))
       (rec-fact (* accu num) (- num 1)))
      (_
       accu))))

In this example, you will notice that rec-fact is the locally named function that gets called at the end of the first pcase pattern. This is a tail call! It will get optimized.

You can check this out by running something like (ela/fact 5) and getting 120 as the result. Try using a ridiculously big number and see if you get a stack overflow! You shouldn’t.

Another Example: Summing a List

This is just a nostalgic example, since it’s probably the first tail recursive pattern matching function I ever wrote when learning OCaml a zillion years ago. This function will take a list of numbers and then add them all together. There are much better ways to write this in Emacs Lisp, like with apply.

(defun ela/sum (numbers)
  (named-let sum-list ((accu 0)
                       (lst numbers))
    (pcase lst
      (`(,head . ,tail)
       (sum-list (+ accu head) tail))
      (_
       accu))))

You can then call it like this:

(ela/sum (list 1 2 3))

And you will end up with exactly the result you expect. I was amused to see that the documentation page for named-let has a different implementation of this function that doesn’t use pcase.

Oh heck, let’s get fancy and rewrite apply using this approach.

(defun ela/apply (fn &rest arguments)
  "Apply FN to each element of ARGUMENTS and return the accumulated result."
  ;; Set up accumulator to the right type.
  (let* ((arguments-flat (flatten-list arguments))
         (initial-value (pcase (car arguments-flat)
                          ((pred integerp) 0)
                          ((pred stringp) "")
                          (_ nil))))
    (named-let apply-rec ((accumulator initial-value)
                          (input-list arguments-flat))
      (pcase input-list
        (`(,head . ,tail)
         (apply-rec (funcall fn accumulator head) tail))
        (_
         accumulator)))))

I am certain this version of apply has bugs, but it works for + and concat, so that’s good enough for a simple example. And it uses pcase twice!

Hopefully this has been a useful blog post for somebody out there. Let me know in the comments if there are other fun things you have done with TCO and pattern matching in Emacs Lisp!

New MELPA Package: ddate

2022-11-01T00:00:00+00:00

I recently wrote an Emacs Lisp package to support the ddate command, a classic command-line utility to display dates from the Discordian calendar.

The package is now available on MELPA! That means that if you have use-package installed, you can get ddate easily like this:

(use-package ddate :ensure t)

Once you have the ddate package installed, you can use it to add the Discordian date to your dashboard with code like this:

(defun ela/dashboard-insert-ddate (list-size)
  "Insert the Discordian date into the dashboard."
  (let ((ddate-string (ddate-pretty)))
    (dashboard-center-line ddate-string)
    (insert ddate-string)))

(use-package dashboard
  :init (dashboard-setup-startup-hook)
  :config
  ;; Add the ddate item provider to the list.
  (add-to-list 'dashboard-item-generators
               '(ddate . ela/dashboard-insert-ddate))

  ;; Set up your items with ddate at the top.
  (setq dashboard-items '((ddate)
                          (recents   . 5)
                          (bookmarks . 5)
                          (registers . 5))))

You can view the source code for ddate on Sourcehut.

An Org-mode to DOCX Pipeline

2022-10-26T00:00:00+00:00

Freelance writers need to deliver documents in the format requested by clients. However, frequently the requested format is not the writer’s preferred working format. I like to write in Org Mode, but many clients prefer delivery in Microsoft Word’s DOCX format.

This is how I generate DOCX files for my clients.

What is Org Mode?

Org Mode is an Emacs package for writing and working with Org files. Org files are highly structured plain text files that may appear to be a text outline, but can do so much more. Org Mode is incredibly versatile, and can be used to track projects, manage schedules, write outlines, and even create documents.

Choosing between Org Export and Pandoc

Org Export runs inside Emacs and is capable of converting Org files to a variety of other formats. While it is very powerful, it also has its idiosyncrasies. For instance, when converting Org files to DOCX files, it uses its own style names such as “Org Title” and “Org Heading 1”.

A second option for converting Org files to DOCX files is Pandoc. Pandoc prides itself on being the Swiss army knife of document format conversion. It handles an impressive variety of document formats and handles a dizzying collection of configuration options.

Since the DOCX files that I create need to be shared with other writers, editors, and reviewers, I need to make sure that they are easy to work with. This influenced my decision. Since Pandoc uses more standard style names, I decided to use it for Org conversion.

Setting up Pandoc

To use Pandoc to generate nice looking DOCX files, you will need to configure a template document. The recommended method for doing this is to generate a default template using Pandoc, and then edit it in Word. I used LibreOffice Writer for this, and it worked just fine.

Install the latest Pandoc using these instructions.

Run the following command to generate reference.docx

pandoc -o custom-reference.docx --print-default-data-file reference.docx

Open reference.docx in your word processor and edit the styles so they meet your needs.

Converting from Org to DOCX

One option for running the conversion is to take advantage of the ox-pandoc package for Emacs. If you will always be using the same configuration for your exports, this is a great option.

However, I need to use a number of different configurations for converting documents, so I tend to run Pandoc from the command line. Recent versions of ox-pandoc support passing options via Org headers, but I still haven’t bothered to set that up. It should be very easy to template this using Yasnippet, though.

I use a custom fish shell function that looks like this:

function org2docx --description 'Generate a DOCX file using a custom reference document'
    set -l refdoc "$PATH_TO_REFERENCE_DOCX"
    set -l base (basename -s .org $argv)
    echo Generating $base.docx ...
    pandoc --reference-doc $refdoc -o $base.docx $argv
end

From my fish shell command line, I can then just run org2docx whatever.org to generate whatever.docx.

I have not found a level of automation that makes my converted DOCX files completely perfect, unfortunately. After conversion, I always open the new file in my word processor to make final tweaks and fixes.

Have fun converting files!

The method I’ve outline in this blog post is straightforward and fits my needs. There are definitely improvements to be made, such as using templates to pass the proper options to Pandoc. Switching to ox-pandoc would mean one fewer reason to leave Emacs, after all.

In recent years, more and more clients are asking for files to be delivered via Google Docs. So far, I have yet to find a good conversion pipeline to get Org files into Google Docs easily. My method right now takes too many manual steps. That’s a problem I would love to solve.

Do you have a conversion pipeline for documents that works for you? Leave me a comment and let me know!

Yasnippet and Emacs for Writing

2022-09-28T00:00:00+00:00

As a freelance writer, I need to be ready to deliver high quality copy in a timely fashion. My editor of choice for writing is Emacs. I have found that Yasnippet templates have streamlined my writing process.

What is Yasnippet?
Installing Yasnippet
Markdown and Jekyll
- Bonus Snippets
Org Mode Templates
- org2blog and Podcast Show Notes
- More Bonus Snippets
Writing Faster is Writing Smarter

What is Yasnippet?

As a templating system for Emacs, Yasnippet is well known by programmers. It can quickly expand function definitions, control structures, and other templates into blocks of source code. Source code is just text.

Since most of my writing originates in text format, templates are great for speeding up document creation and avoiding common errors and omissions.

Installing Yasnippet

With use-package, you can get started quickly with Yasnippet by including the following in your Emacs init file.

(use-package yasnippet
  :ensure t
  :config
  (yas-global-mode 1))

(use-package yasnippet-snippets
  :ensure t
  :after yasnippet)

For more detailed installation instructions, check the Yasnippet documentation.

Markdown and Jekyll

This blog is primarily written in Markdown for Jekyll, which means that each file needs a YAML block at the top with specific information. I have a template that looks like this:

# -*- mode: snippet -*-
# name: blogtop
# key: blogtop
# --
---
title: ${1:Title}
author: "Erik L. Arneson"
layout: post
permalink: `(format-time-string "/%Y/%m/")`$2
comments: ${3:$$(yas-choose-value '("true" "false"))}
tags:
    - $4
---

$0
<!--more-->

Not only does this template save me from needing to remember the format of the YAML block, but it ensures that frequently forgetten items are included, such as the permalink setting and the  tag.

Bonus Snippets

The official snippet collection contains a bunch of extra Markdown templates. Check them out here.

Org Mode Templates

My Org Mode files are more complex. Many writing clients expect deliveries in Microsoft Word files, but I also frequently find myself needing to produce OpenDocument files, HTML, and even Markdown. The headers for these files need to support all of these options.

I use the following template to support all of the Org Mode configuration and options I require.

# -*- mode: snippet -*-
# name: header
# key: header
# --
#+TITLE: $1
#+LANGUAGE: ${2:en}
#+AUTHOR: ${3:$$(yas/choose-value '("Erik L. Arneson" "Some Other Name"))}
#+EMAIL: ${4:$$(yas/choose-value '("list-of-email-addresses"))}${5:
#+DESCRIPTION: $6}${7:
#+KEYWORDS: $8}
#+OPTIONS: num:nil toc:nil
#+ODT_STYLES_FILE: ${9:$$(yas/choose-value '("list-of-template-files"))}
#+bibliography: /path/to/MyLibrary.bib
#+cite_export: csl ${10:$$(yas/choose-value '("chicago-fullnote-bibliography.csl" "modern-language-association.csl" "apa.csl"))}
#+WWG: ${11:$$(yas/choose-value '("0" "250" "500" "1000"))}

$0

org2blog and Podcast Show Notes

I also use Org Mode to publish to WordPress websites using org2blog. For one of these websites, I write show notes for podcast episodes. I use a template that looks like this.

# -*- mode: snippet -*-
# name: podcast
# key: podcast
# --
* $1
  :PROPERTIES:
  :POST_TAGS: $2
  :BLOG:      arnemancy
  :CATEGORY:  Podcast
  :POST_DATE: `(format-time-string "[%Y-%m-%d %a %H:%M]" nil nil)`
  :END:

$0

** Links

** Credits

#+begin_export html
Support me on Patreon: <a rel="payment" href="https://www.patreon.com/arnemancy">https://www.patreon.com/arnemancy</a><br>
#+end_export

This template reminds me of important items I need to include in all show notes, like links, credits, and a Patreon link.

More Bonus Snippets

The official snippet collection also contains a bunch of Org Mode snippets. Here is the whole list. Since Org Mode contains so many complicated structures like source blocks and optional keywords, these are great time savers. There are also snippets for supporting org-reveal.

Writing Faster is Writing Smarter

Don’t let your tools get in the way of your writing. Frequently, Emacs is portrayed as cumbersome and filled with obscure keybindings and weird commands. However, I have found that it is an excellent tool for writing. Yasnippet templates let me get started on new documents quickly without fretting over different syntaxes for configuration.

And Yasnippet is just one of the tools I use when writing with Emacs. I will discuss more of these tools in the future.

Some Great Fish Shell Plugins

2022-09-23T17:44:00+00:00

As a long-time Linux user, I am pretty comfortable with command line interfaces. However, as I started learning more about automation and how important it is to get your computer to do more work for you, I leaned toward wanting my command line shell to do more. Eventually I switched to fish shell, a very user-friendly shell with excellent scripting capabilities that is far more readable and less obscure than bash.

Plugins for fish

There have been a few plugin managers over the years, but the one that seems to be the best maintained and most usable is fisher, created by Jorge Bucaran. It allows you to easily install plugins straight from GitHub repositories, while updates can be executed with a simple fisher update on the command line.

z

One of the greatest command-line time savers ever is the z command. Originally a bash script, it has been ported to fish and, frankly, I love it.

What does it do? z provides shorthand for visiting directories based on a combination of frequency and recency—or "frecency".

If you frequently visit the /opt/calibre directory, a z calib command will allow you to jump straight there.

If you already have fisher installed, just use fisher install jethrokuan/z and start playing around with z.

You can read more about z here.

pisces

Your IDE has been handling your parenthesis for ages. Now your shell can do the same! The pisces plugin has automatic matching symbol management for parenthesis, braces, quotes, and others.

Install it with fisher using the command fisher install laughedelic/pisces and be matching parens in seconds!

plugin-emacs

Automation can help you interact with your editor from your shell. The Emacs plugin for fish was originally written for an unmaintained plugin manager called Oh My Fish. However, I wanted the plugin to work with fisher, so I made my own fork.

How does it work? This plugin adds easy commands like ef and ed that allow you to open files and directories in Emacs quickly.

Install it quickly using the command fisher install pymander/plugin-emacs and read more about it here.

vfish

Emacs users have probably heard of vterm, which is the Emacs package that interacts with libvterm. It is a powerful terminal emulator that runs in an Emacs buffer. I wrote a fish plugin called vfish that simplifies using fish in vterm.

How does it work? Inside a vterm session, this plugin adds fish commands like vf and vd to open files and directories quickly. It mirrors the Emacs plugin.

Install it using the command fisher install pymander/vfish and read more about it here. Note that it will require some code to be added to your Emacs startup file.

apt

For Debian and Ubuntu users, the Oh My Fish apt plugin works seamlessly with fisher.

What does it do? The apt plugin adds a wrapper around the apt and apt-get commands that simplify package management from the command line.

Install this plugin quickly with fisher install oh-my-fish/plugin-apt and then read more about it.

What's your favorite fisher plugin?

I love finding plugins that can help me automate more of my everyday tasks and workflows. What's your favorite fisher plugin?

Leave a comment below and let me know! Be sure to include a link.

Typing Chinuk Wawa in Emacs

2021-10-11T17:01:00+00:00

Back in 2015, I took a course in being an ally for local Native American communities from the Portland Underground Grad School (PUGS). One suggested action was learning the local language, but it proved difficult to find opportunities. When the pandemic forced school closures, though, Lane Community College began offering classes online. I found out about this thanks to the Kaltash Wawa blog, and this fall I signed up to take a remote Chinuk Wawa class through Lane Community College.

What is Chinuk Wawa?

Chinuk Wawa originated as a type of creole or pidgin trade language in the Pacific Northwest, incorporating loan words from more than a dozen indigenous and European languages. Though it has a small lexicon, it is an interesting language with an impressive array of new phonemes for me to learn. There are 12 different variations on “k”, for instance! As you can imagine, with this variety, it is pretty difficult to type Chinuk Wawa using the standard Latin alphabet. I am learning the Grand Ronde dialect, which uses an IPA-based alphabet.

Keyman for Linux

Under Linux, the easiest way to add an IPA-based input method is using the IPA (SIL) keyboard for Keyman. This integrates nicely under GNOME 3 with Ubuntu 20.04. However, I’m a Dvorak typist, so having to switch back to a QWERTY-style keyboard is frustrating, and was slowing me down. Instead, I came up with this method for inputing Chinuk Wawa compatible IPA using Emacs.

Emacs Input Methods

Emacs has an easy method for switching between input methods, which you can read more about in the Emacs manual. It comes with a number of IPA input methods, and after taking a look at all of them, I chose ipa-x-sampa, as it seemed to have the best coverage of symbols needed by Chinuk Wawa. However, it was missing a way to input the character “x̣”, which was needed by one of the first words I learned, “yax̣al”!

I added the following code to my startup file to remedy this. This adds the ability to type x_. to get x̣ and ?/ to get ?, both of which make typing Chinuk Wawa much easier for me.

(defun chinuk-wawa-quail-rules ()
  "Add Chinuk Wawa rules to the `ipa-x-sampa` input map."
  (interactive)
  (if (string-equal "ipa-x-sampa" (quail-name))
      (quail-define-rules
       ((append . t))
       ("_." #x0323)   ;; allows for x with dot beneath
       ("?/" "?"))     ;; allows for ? character 
    ))

(add-hook 'quail-activate-hook 'chinuk-wawa-quail-rules)

As you can see, this method allows plenty of additional characters to be added to ipa-x-sampa, so if it turns out I missed anything, I can expand on it later.

The biggest downside of this is that I can only input Chinuk Wawa easily in Emacs, but since I do most of my work there—including writing this blog post—it doesn’t feel that bad to me. It’s definitely better than typing QWERTY!

aɬqi!

Erik L. Arneson — Writer and Software Developer

Emacs as the Freelancer's Command Center

Organization with org-mode

Freelance.org

Clients/*.org

References and Linking

Email with mu4e

Writing Code

Writing Words

Track All Changes with Magit

Thinking Music with EMMS

And the tools I have missed

An Emacs Application Launcher for Regolith

Turning to consult-omni

Adding an ilia fallback

Drawbacks

Interviewed on "Prot Speaks"

Writing Experience (Emacs Carnival)

Emacs Writing History

Org-mode Is A Life-changer

Emacs Can Be Distraction-Free

No Going Back

Configuring Orgzly Interaction with Directory Local Variables

Configuring Orgzly Revived Auto-sync

Configuring Emacs and Org-mode

Examining To-Do Lists in Org-mode

Many Posts of Interest for January 2024

Security

Emacs

Programming

History

EmacsConf 2023 Retrospective

Emacs Advocacy

Writing

Hyper Things (Hyperbole and Hyperdrive)

EMMS

Overall Impression

Posts of Interest for November 2023

Security

Emacs

Games

History

Posts of Interest for 13 October 2023

Programming (1)

Emacs (6)

Security (4)

Posts of Interest for 6 October 2023

Computers (4)

Portland (1)

Configuring Emacs 29.1 for Go Development

Configuring Tree-Sitter for Go

Configuring Eglot for Go

What Else?

Installing Emacs 29.1 on Ubuntu 22.04 LTS

What’s New with Emacs?

Installing on Ubuntu 22.04 LTS

Installing the Requirements

Preparing to Build

Get the Source Code and Let’s Compile!

What’s Next

Update: Org to DOCX with Citations

Writing and Reviewing Jupyter Notebooks

Renaming files with Dired

Pattern Matching and Tail Recursion in Emacs Lisp

Pattern Matching with pcase

Tail Call Optimization with named-let

Another Example: Summing a List

New MELPA Package: ddate

An Org-mode to DOCX Pipeline

What is Org Mode?

Choosing between Org Export and Pandoc

Setting up Pandoc

Converting from Org to DOCX

Have fun converting files!

Yasnippet and Emacs for Writing

What is Yasnippet?

Installing Yasnippet

Markdown and Jekyll

Bonus Snippets

Org Mode Templates

`Freelance.org`

`Clients/*.org`

Turning to `consult-omni`

Adding an `ilia` fallback

Pattern Matching with `pcase`

Tail Call Optimization with `named-let`