The journey that counts

My Emacs package Orgox to publish my notes

Sun, 28 Dec 2025 00:00:00 +0000

Currently you’re reading a note from a repository of notes I maintain on GitHub, swinkels/notes. Each note is an Org file and because GitHub has some support for org-mode, the notes are rendered “ok-ish” when you view them in your browser. To also have a more “professional” presence in the blogosphere, earlier this year I published my notes at my blog.journeythatcounts.nl using the static website generator Hugo. This note introduces the Emacs package I developed to convert the notes to the Markdown files that Hugo expects, named Orgox.

Automate a developer workflow in Emacs

Sun, 23 Mar 2025 00:00:00 +0000

During development of an application, multiple times I had to reset a process that the application depended. This reset required a cumbersome sequence of steps both in and outside of my IDE, Emacs. This note describes how I reduced that workflow to a single call to an Emacs Lisp function.

Introduction

For one of my clients I’ve been working on an application that creates a report in the form of a static website. The application retrieves data from several sources, processes it and reports the results through Markdown files, PNG files for plots and HTML files for tables. The static website generator Material for MkDocs, MkDocs for short, builds a static website from these files.

Spacemacs and ruff to sort Python imports on save

Wed, 08 Jan 2025 00:00:00 +0000

Recently I introduced ruff in a Python project of a client to format the code base and to sort the imports. Most of the developers there use PyCharm, which is easy to configure to use ruff. Surprisingly, it turned out to be more difficult in Spacemacs. To cut a long story short, Spacemacs¹ does not support the use of ruff to sort Python imports on save. For this it relies on the LSP server but the official ruff LSP server also does not support it.

Looking over the fence at Doom Emacs

Sat, 28 Dec 2024 00:00:00 +0000

In May of this year I decided to have a look at another Emacs starter kit¹, Doom Emacs. It’s not that I was dissatisfied with Spacemacs, which has been my trusty day-to-day driver for years, but it can be good to look over the fence every once in a while and see what “the others” are doing.

This note describes my experience with Doom as it was in May 2024, almost half a year ago now. Since then, issues I encountered may have been resolved and new ones may have been introduced. Also, part of what this note describes is from memory and I will have forgotten some of the good and bad.

Using Emacs profiles side-by-side

Tue, 24 Dec 2024 00:00:00 +0000

This is very short note about Chemacs2, “an Emacs profile switcher, [which] makes it easy to run multiple Emacs configurations side by side”. It’s something I need to do that every now and then, for example when I want to test-drive the latest Spacemacs without affecting my main development environment.

Emacs 29 and later support the command-line option --init-directory=DIR to specify where Emacs should for its init files. Sometimes I have to use an older Emacs version which makes that solution less ideal¹. Until now I managed my Emacs profiles using stow, which is a nice tool to manage symlinks. However, its use case is not “Emacs profile switching” and that makes it somewhat cumbersome to use.

Use Guix to build & install an older Emacs version

Wed, 24 Jul 2024 00:00:00 +0000

I use Guix to manage the installation of some of my development tools, Emacs being one of them. At the time of writing, Guix gives me Emacs 29.4 but what if I need an older version? This note describes how I use Guix to install older Emacs versions next to the most-recent one.

Before I continue, a big shoutout to Steve George, whose Futurile blog contains a treasure trove of Guix documentation.

Upgrading Spacemacs

Sun, 24 Mar 2024 00:00:00 +0000

Spacemacs consists of 2 parts,

Spacemacs to manage and configure a set of third-party Emacs packags and
the third-party packages themselves.

The Spacemacs code itself is continuously updated. These update bring new features and fix bugs, or contain changes to take into account features or bugs in the third-party packages. This means Spacemacs is coupled to the state of the most-recent third-party packages. As Boromir would tell you,

To avoid any issues, I always update Spacemacs from scratch whenever I update Spacemacs. This means I have to update my Spacemacs configuration, and install the latest versions of the third-party packages. The last time I did that was than a year ago - October 19, 2022 - and it was time for an update.

What makes a design object-oriented?

Wed, 03 Jan 2024 00:00:00 +0000

On HackerNews there was a discussion about the presentation “Pitfalls of object oriented programming” (PDF). The HackerNews comments contain a thread about 4 characteristics of object-oriented programming (OOP), viz.

abstraction,
polymorphism,
inheritance, and
encapsulation.

I first encountered these characteristics in the early 2000s through the mnemonic “A PIE”. I always found it to be a fuzzy “definition” as abstraction, polymorphism and encapsulation aren’t unique to OOP. Another thread in the comments made me wonder what it is that makes a design (or implementation) “object-oriented”? This note tries to clarify that.

Using older documentation with Dash

Sun, 17 Dec 2023 00:00:00 +0000

In note 20230116 I talked about the offline API browser Dash, a MacOS application that lets you download the HTML documentation for various software packages and search it offline. Dash doesn’t download the HTML documentation from the original package location, but from its own sites. Other clients than Dash can download these so-called docsets, but only Dash can download docsets for older versions of a software package. Other clients can only access the most recent build. This note describes how to build the docsets for older versions yourself and install them side-by-side.

Creating animated GIFs of a desktop area

Tue, 28 Nov 2023 00:00:00 +0000

In my previous note I created an animated GIF of how I used Emacs package pydor to run Python doctests, of course from Emacs. An animated GIF is a really good way to show how a tool like that works. I wouldn’t say that “an image says more than a thousand words”, but it does add a lot to a textual description.

The following two tools made it really easy to create the animated GIF:

Introducing pydor, an Emacs package to run doctests

Sun, 29 Oct 2023 00:00:00 +0000

Spacemacs configures several key bindings to run Python unit tests, such as “run test at point” and “run tests in current module”. It lacks the functionality to run doctests so I wrote a small Emacs package for that: pydor, the Python doctest runner. The following animated GIF shows how it works in Spacemacs:

The Emacs package is implemented by an Emacs Lisp file to determine the location of the docstring at point and a Python file to load and run the doctests in that docstring.

Build another Python version than Guix provides

Thu, 03 Aug 2023 00:00:00 +0000

My Guix installation¹ provides Python 3 version 3.10.7. This note describes how to use Guix to install another Python 3 version. This turned out to be much more elaborate than expected…

Management summary

To build a Python version that Guix does not provide out-of-the-box, you

find the package specification of the most recent Python version that is supported by Guix but still precedes the version you need,
create a package variant that derives from that specification and
build the variant.

To give an example, Guix repo file gnu/packages/python.scm contains the package specification of Python 3.10.7 that my Guix installation uses. I have created a package variant that inherits this specification and that overrides the parts required to build 3.10.12, see 20230803/python-3.10.12.scm. The following command builds that Python version:

Trying out Visual Studio (WIP)

Sun, 23 Apr 2023 00:00:00 +0000

For the first time in 6 years, I had to use Windows for Python development for one of my contracts. Using Windows isn’t a problem, but it turned out that using Spacemacs on Windows wasn’t as seamless an experience as I remember the use of a rather standard Emacs config was. It takes about 40 seconds to load my Spacemacs config, magit is almost unusably slow and the biggest issue: several times a week I have to kill Emacs because the helm interface locks up.

Create DataFrame from string table

Sat, 18 Mar 2023 00:00:00 +0000

You can find the code for the read_table function mentioned in this note in subdirectory 20230318.

The really handy Pandas function read_fwf creates a DataFrame from a fixed-width text table, for example:

import io

import pandas as pd

table = """
FirstName LastName FirstAppearance
Donald Duck 1934
Mickey Mouse 1928
Goofy 1932
 """

# read_fwf expects a filename, either as a string, a path object, or as the
# next line shows, a stream/file-like object
df = pd.read_fwf(io.StringIO(table))
print(df)

 FirstName LastName FirstAppearance
0 Donald Duck 1934
1 Mickey Mouse 1928
2 Goofy NaN 1932

I mostly use it in unit tests, when I need to set up DataFrame instances. They’re easier to create using read_fwf and the resulting code is more readable, more communicative.

Using dash-docs from Spacemacs

Sun, 26 Feb 2023 00:00:00 +0000

Spacemacs has a Dash layer but it doesn’t seem to add much to the functionality the dash-docs packages provides out of the box. So instead of using that layer, I’m using these packages directly and this note describes how.

Installation

To install a third-party package like helm-dash in Spacemacs, you add it to variable dotspacemacs-additional-packages. helm-dash requires dash-docs so when Spacemacs installs helm-dash, it will download dash-docs from Melpa unless it’s already installed. However, I want Spacemacs to use my custom version of dash-docs, so I need to specify that too:

Fix "cannot open" error messages when using dash-docs

Sat, 28 Jan 2023 00:00:00 +0000

Haha, initially this note described a fix I made for an issue in helm-dash and that I created a pull request to get it merged upstream. However, while writing this note I realized I implemented the wrong approach and that I had to close the pull request unmerged. Let’s describe the problem first.

The problem

In my note about helm-dash, an Emacs package to access offline documentation provided by Dash, I mentioned the *dash-docs-error* buffer opens with messages like this:

Accessing offline API documentation from Emacs

Mon, 16 Jan 2023 00:00:00 +0000

Prominent Python developer and blogger Hynek Schlawack wrote a blog post about the offline API browser Dash. Dash is a MacOS application that lets you download the API documentation of multiple software packages and search it offline. You start it with a press of a button, enter your search terms and it searches the documentation you downloaded. At the time of writing this, the Dash website states that it has the documentation of over 200+ software packages, for example C++, Pandas, Python and Qt.

Error dialog about pythoncom39.dll in conda virtualenv

Thu, 05 Jan 2023 00:00:00 +0000

At a client I had to review the code of a new Python project. I cloned the repo, used conda to create a virtualenv and finally let Poetry install all Python dependencies. This went without a hitch but after the installation of the dependencies, each subsequent Poetry command would show me an error dialog like this:

(my-venv) C:\Users\Pieter\repos\my-venv>poetry cache list --help

So each Poetry command triggered a failing search for a specific procedure in a DLL in my base conda environment. Some googling (and trial & error) lead me to this section of the README of the pywin32 package:

Poetry dependency resolution and Python versions

Wed, 04 Jan 2023 00:00:00 +0000

In a virtualenv using Python 3.9.15, a poetry install failed with the following message:

Updating dependencies
Resolving dependencies...
The current project's Python requirement (>=3.9,<4.0) is not compatible with some of the required packages Python requirement:
- numpy requires Python >=3.7,<3.11, so it will not be satisfied for Python >=3.11,<4.0

As Python 3.9.1 satisfies both the “current project’s Python requirement” and that of numpy, I wondered why the command failed. Some googling lead me to this question in the poetry FAQ:

James Shore's "Testing without Mocks"

Sun, 01 Jan 2023 00:00:00 +0000

James Shore released an update of this article “Testing without Mocks: A Pattern Language”. The article is about 40 pages long and it is accompanied by a Mastodon thread to explain it all. This note is my one-page summary of that thread.

Shore wants to avoid mocks as they have a tend to have “lots of detail about the interactions the code”. This locks in in your implementation and makes bigger refactorings really hard.

When I update version numbers

Wed, 28 Dec 2022 00:00:00 +0000

When a colleague asked me when to update the version number of a software package, and how, this is what I answered.

First of all, I strive to follow semver, even though there are scenario’s where semver is less applicable. First a recap about semver, for a version x.y.z you

increase z if there is a bug fix that leaves the new version backward-compatible;
increase y if there is new functionality that leaves the new version backward-compatible;
increase x if the new version is not backward-compatible.

Second, I only update the version number when I make a release. I go through the list of changes in the CHANGELOG and decide whether to update z, y or x. I only increment one of them and the rest I either leave as-is or reset to 0. To give some examples of version changes:

GitHub fine-grained personal access tokens

Mon, 26 Dec 2022 00:00:00 +0000

If you need to push a commit to a GitHub repo over HTTPS and you don’t want to provide a username & password, a GitHub “fine-grained personal access token” is the way to go¹. The owner of the repo can create that token and configure (1) to which repo(s) it provides access and (2) the kind of access it allows to these repo(s), the repository permissions. The following screenshot shows some of these permissions:

Git for Windows protocol error when using Pageant

Thu, 08 Dec 2022 00:00:00 +0000

On Windows I use the SSH agent pageant to manage my keys for Git. This allows me to use the same agent process from Windows and MSYS2 Zsh sessions. But after I switched to pageant on a workstation that previously used the Git Credential Manager, Git commands that accessed a remote, failed:

C:\Users\Pieter\repos\my-repo> git pull
fatal: protocol error: bad line length character: logi
FATAL ERROR: Error reading from console: Error 109: The pipe has been ended.

The first hit by Google was this question on StackOverflow, Git Remote: Error: fatal: protocol error: bad line length character: Unab. Most answers pointed in the direction of pageant and plink, where plink replaces the ssh command as it can talk to pageant. Was pageant running? Were the keys loaded? Those all checked out so I focussed on plink.

Let Git for Windows use Pageant as SSH agent

Tue, 29 Nov 2022 00:00:00 +0000

If you want Git for Windows to use Pageant as an SSH agent, you have to set environment variable GIT_SSH to the path of the Plink executable. Here,

GIT_SSH “is a program that is invoked instead of ssh when Git tries to connect to an SSH host”¹, and
Plink is a Windows command-line tool to establish an SSH connection and comes with the Putty suite of tools.

So Git for Windows will use Plink to connect to the repo server and Plink will query a running Pageant instance for the SSH key-pair.