Karl Bartel's Website

Can We Make Simpler Software With LLMs?

2026-02-28T19:20:48+01:00

Can We Make Simpler Software With LLMs?

Growing numbers of abstraction layers, vast amounts of dependencies and general complexity are what annoy me most about modern software development. LLMs are powerful tools, but in practice they often lead to even larger, more complex projects with even more dependencies. Can we use them for the opposite: small, simple software without dependencies? I tried this recently when I wanted a specific piece of software to do simple calculations inside short texts. Not all the approaches I tried are ones I'm convinced are a good idea, but I intentionally wanted to experiment a bit.

The Project

calced is a notepad calculator. You write natural-looking text with math in it, and calced evaluates the expressions and appends results. It supports things like variables, percentages (200 + 15%), unit conversions (100 km in miles), date arithmetic (2025-01-15 + 3 weeks), different number formats and custom conversion rates.

I wanted two implementations: a Python CLI to work on local files and a web version. The typical approach today would involve TypeScript, a bundler and lots of npm dependencies for the web version; maybe Pyodide to run the Python version in the browser and some React UI around it. Instead, I tried to use the LLM to do it in a more primitive way without spending a lot of time handcrafting code I don't care too much about.

No Dependency Management

The web version uses big.js for arbitrary-precision math. Instead of using npm and a bundler, I had the LLM inline the library directly into the HTML file. Same for the logo SVG. The result is a single 52KB HTML file that works offline.

The Python CLI is even simpler: a single 47KB file using only the standard library. Although I prefer click for the nicer API, I used argparse instead, since the LLM can easily generate the more verbose but dependency-free version. The same is true for many similar decisions.

No Build System

With dependencies either inlined or avoided, there is nothing left that needs a build system. No TypeScript, no bundler, no transpiler, no node_modules, no minifier. Just a single HTML file with plain JavaScript for the web version. For small projects, TypeScript is not necessary anyway, but when the LLM writes most of the code, the benefit becomes tiny (at least for the user, it might help the LLM). So let's just use JS directly! And without big dependencies the code is small enough to serve as is.

Both the JS and the Python versions can be run exactly as they are stored in version control, even when downloading just that single file.

Two Implementations Without Transpilation

Instead of running the Python implementation in the browser via Pyodide or transpiling one version into the other, I simply asked the LLM to write and maintain both versions. To make this work, I needed a proper test setup: 18 markdown files serve as integration tests using git diff, where calced processes them and the test verifies the output has not changed. Both implementations run against the same files, so any behavioral difference between Python and JavaScript is caught immediately. Shared JSON fixtures cover additional cases that don't fit this specific testing pattern. As long as the test fixtures are shared and cover enough of the functionality, I can use the LLM to keep both versions in sync.

Another (probably more sane) approach would have been to use JS for the CLI version too. But

I personally prefer python
Python has a better stdlib, requiring fewer dependencies
the UI/CLI part needs to be done separately anyway
having implementations in different languages prevents me from accidentally relying on that language's specifics in my math syntax
it wouldn't allow me to try out this "keep two implementations in sync with LLM" approach (let me have some fun!)

Avoid Needless Inconsistency

When you write something from scratch, it is easy to accidentally deviate from established conventions. I had the LLM check the CLI against the excellent clig.dev and compare behavior with existing tools like Soulver, Numi and Numbr, adopting the same conventions where I had no strong preference. Better consistency is not simpler in a direct technical way, but usually makes the user's life simpler, so I'll still count it towards this goal.

Verdict

As intended, the result is small and simple compared to similar projects: a 52KB HTML file, a 47KB Python file, a 62-line Makefile and no trace of the npm ecosystem. The really interesting part will be to see how maintainable this is over a longer time frame. But I'm optimistic that at least some of the approaches are genuinely good ideas (e.g. letting the LLM check against clig.dev and comparing with similar projects).

I might have created something technically better if I wrote it by hand, but realistically, I just would not have written it at all. And when most people use LLMs to quickly generate vast amounts of code, it is nice to see that you can also use them to generate less in some cases.

Raising Notifications From Terminal

2026-01-17T14:01:35+01:00

Raising Notifications From Terminal

When executing long-running jobs in the terminal, it's useful to get notified when they complete so you can do other things while waiting. Here are a few ways to achieve this.

Using notify-send (Linux)

The simplest approach is to chain your command with notify-send:

slow-job; notify-send "done"

If You Already Started the Job

If you've already started a long-running job and forgot to add a notification, you can still do it:

Press Ctrl-Z to suspend the job and put it in the background
Run fg; notify-send "done"

The job will resume in the foreground, and you'll get notified when it finishes.

Notify on Success or Failure

Using ; to chain commands will always raise the notification, regardless of whether the job succeeded or failed. You can use && and || to be more selective:

slow-job && notify-send "success"   # only on success
slow-job || notify-send "failed"    # only on failure

This also works when adding the notification after backgrounding the process with Ctrl-Z:

fg || notify-send "failed"

Using osascript (macOS)

On macOS, you can use osascript instead:

slow-job; osascript -e 'display notification "done" with title "Terminal"'

I've put this osascript command (with a $1 instead of done) into a small script called notify-send, so that I can use the same command on both Linux and macOS. Since I don't use more than a single text parameter for my notifications, that works well for me.

The Terminal Bell

An interesting alternative is ringing the terminal bell:

slow-job; echo -e '\a'

Many terminal emulators show some kind of notification or badge when the bell rings while the terminal is in the background. The great thing about this approach is that it works across many platforms and even through SSH sessions!

OSC 777

Some terminals support the (highly underdocumented) OSC 777 escape sequence for desktop notifications:

slow-job; printf '\x1b]777;notify;Command;Job finished\x1b\\'

Just like the terminal bell, this emits an escape sequence that is interpreted by the terminal emulator, but is made specifically for raising desktop notifications. So it keeps the terminal bell's advantages of not requiring external tools and working through SSH. Terminals that support this include foot, Ghostty, WezTerm and some others.

Kitty has its own notification protocol with advanced features like icons, buttons, and urgency levels. It comes with a convenient notify kitten that wraps this:

slow-job; kitten notify "Done" "Job finished"

Closing Thoughts

For quick local work, notify-send or osascript are straightforward and provided by the system. The terminal bell is the most portable option. OSC 777 gives you proper notifications without external tools. The last two also work through SSH. In the long run, I'm hoping for proper standardization, documentation and widespread support of OSC 777, but for now I can't blindly recommend a single approach, so this blog post seems necessary.

Stack Traces are Underrated

2025-03-08T09:41:27+01:00

Stack Traces are Underrated

I Love Stack Traces

When something goes wrong in a program, many languages will spit out a stack trace with lots of useful information. Here's an example from one of my Python programs:

Traceback (most recent call last):
  File "/home/piku/.piku/envs/wikdict/lib/python3.11/site-packages/flask/app.py", line 1511, in wsgi_app
    response = self.full_dispatch_request()
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/piku/.piku/envs/wikdict/lib/python3.11/site-packages/flask/app.py", line 919, in full_dispatch_request
    rv = self.handle_user_exception(e)
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/piku/.piku/envs/wikdict/lib/python3.11/site-packages/flask/app.py", line 917, in full_dispatch_request
    rv = self.dispatch_request()
         ^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/piku/.piku/envs/wikdict/lib/python3.11/site-packages/flask/app.py", line 902, in dispatch_request
    return self.ensure_sync(self.view_functions[rule.endpoint])(**view_args)  # type: ignore[no-any-return]
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/piku/.piku/apps/wikdict/wikdict_web/lookup.py", line 119, in lookup
    if r := get_combined_result(lang, other_lang, query):
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/piku/.piku/apps/wikdict/wikdict_web/lookup.py", line 91, in get_combined_result
    conn = get_conn(lang + "-" + other_lang)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/piku/.piku/apps/wikdict/wikdict_web/base.py", line 103, in get_conn
    raise sqlite3.OperationalError(
sqlite3.OperationalError: Database file "/home/piku/.piku/data/wikdict/dict/en-ko.sqlite3" does not exist

Beautiful! In addition to the error, I immediately see the line that caused the error, the full call stack and I have the file paths and line numbers at hand to quickly jump to each of the locations. Often, this is all I need to fix the problem.

The Case of the Missing Trace

Stack traces are already a common debugging tool for decades, but unfortunately they are not ubiquitous and in some cases, they even disappear where we used to have them. Let's take a look at a few of these cases.

Modern Error Handling

Many people dislike exceptions since they break the usual control flow and make it easy to skip proper error handling. So instead of raising exceptions, they return errors as special return values. This was always the case in C because it doesn't have exceptions, but also more modern languages like Go and Rust do this, although in a nicer way. But this approach does not yield stack traces since the functions return normally, just with different values. So instead of the beautiful stack trace above, Go will give you

wrong number of elements

or, if the author was diligent and added context (preferably with fmt.Errorf's %w format string) each time the error is passed along, something like:

can't load data: failed to parse header: wrong number of elements

While these prefixes resemble a poor man's stack trace, they

don't show the file and line number
don't show the code
can be ambiguous (the same error message or prefix could be used in multiple places in the source)
can't be trusted to be constructed consistently

The situation in Rust is similar, where errors are also passed as return values, just with more interesting typing than in Go. But Rust has a better workaround to create stack traces: the backtrace module, which allows capturing stack traces that you can then add to the errors you return. The main problem with this approach is that you still have to add the stack trace to each error and also trust library authors to do so.

More Complicated Architectures

Not only modern programming languages, but also modern architectures can be a threat to good error traces. More and more often, a single system is split up across many programs, often under labels like microservices, containers or serverless functions. This allows using different programming languages between components, better isolation and scalability. But in addition to making everything a lot more complex, it breaks stack traces! If you have an HTTP call between your functions, you will have to put a large amount of work into your tooling to get something nearly as useful and consistent as Python's default stack traces. Most people don't and even fewer succeed at doing that.

Closing Thoughts

So while I can understand that not everybody likes exceptions, I don't see any reasons against having stack traces. Collecting the traces can cost some performance, but that is a small price to pay for the advantages and could even be turned off in production builds. I'm really surprised that so few people complain about the lack of stack traces in some modern programming languages and ecosystems. Are they just not used to having them so that they don't miss them? Or are they heavily relying on other tools that mitigate the problem (e.g. debuggers)? Please let me know your thoughts on this!

Easily Entering Umlauts With a US Keyboard Layout

2024-08-29T11:58:59+02:00

Easily Entering Umlauts With a US Keyboard Layout

As a software developer, a US keyboard layout is great for entering all the special characters you need while coding and for using certain applications like vim. But as a German speaker, I also frequently need to enter German characters that don't exist in English: the Umlauts äÄöÖüÜ and ß. I want to do this without giving up the US layout and without having to press complicated key combinations (no dead keys, no unintuitive combinations).

My goal is to get the German characters by holding right alt ("Alt Gr") while pressing the respective Latin character. E.g. ralt+a => ä.

Previous Approach: xmodmap

For the last years, I used the following .Xmodmap file, which could be applied by running xmodmap .Xmodmap:

keycode 39 = s S ssharp
keycode 38 = a A adiaeresis Adiaeresis
keycode 30 = u U udiaeresis Udiaeresis
keycode 32 = o O odiaeresis Odiaeresis

This worked, but had two downsides:

It only works with Xorg, but not with Wayland.
The applied modmap got lost regularly (related to suspend or screen locking?), so I had to rerun xmodmap frequently.

New approach: xkb

Fortunately, there is a way that (despite its name) works for both Wayland and Xorg: setting up a user specific xkb configuration. Based on a detailed blog post and a github comment, I created the following configuration:

File: .config/xkb/rules/evdev.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xkbConfigRegistry SYSTEM "xkb.dtd">
<xkbConfigRegistry version="1.1">
  <layoutList>
    <layout>
      <configItem>
        <name>us</name>
      </configItem>
      <variantList>
        <variant>
          <configItem>
            <name>umlaut</name>
            <shortDescription>umlaut</shortDescription>
            <description>English (US, international with German umlauts)</description>
          </configItem>
        </variant>
      </variantList>
    </layout>
  </layoutList>
</xkbConfigRegistry>

File: .config/xkb/symbols/us
partial alphanumeric_keys
xkb_symbols "umlaut" {
    include "us(altgr-intl)"
    include "level3(caps_switch)"
    name[Group1] = "English (US, international with German umlaut)";
    key <AD03> { [ e, E, EuroSign, cent ] };
    key <AD07> { [ u, U, udiaeresis, Udiaeresis ] };
    key <AD09> { [ o, O, odiaeresis, Odiaeresis ] };
    key <AC01> { [ a, A, adiaeresis, Adiaeresis ] };
    key <AC02> { [ s, S, ssharp ] };
};

If you prefer, you can also find the files in my dotfiles repo.

After restarting your desktop environment, you can select the keyboard layout and start using it. Under GNOME, you'll find it under Settings -> Keyboard -> Input Sources -> + -> English.

Alternatives

Recent versions of xkeyboard-config include a "de_se_fi" variant for the us layout, that should give you the same results as my approach above.

There's also the AltGr-wEur keyboard layout, which fits the Danish, Dutch, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish and Swedish characters all into a single keyboard layout without using dead keys. Combining all of these languages requires compromises, which results in the German ß not being on the S key but on number 8 key. If that's ok for you, this layout is a good choice.

Consistent Handling of Git Repositories With Different Default Branches

2023-09-17T09:32:14+02:00

Consistent Handling of Git Repositories With Different Default Branches

Why Do I Care About Default Branches?

Typically, I develop on a feature branch, and when the feature is ready, there is an obvious branch into which I want to merge the branch. This branch is often called master, main or develop. During development, I will occasionally rebase my feature branch on top of this branch, to reduce future merge conflicts, and to avoid falling behind on changes merged by other developers. I will call this branch the default branch from here on.

To make common operations consistent across repositories, I want to use a git default-branch command that returns the name of the default branch, so that I can use commands like

# Rebase on latest version of the default branch
git fetch origin $(git default-branch) && git rebase origin/$(git default-branch)

# Switch to the default branch and bring it up to date
git switch $(git default-branch) && pull

# Absorb staged changes into the respective commits since branching off of the default branch
git absorb --base (git merge-base HEAD $(git default-branch))

How to Determine the Default Branch

What I consider the default branch in the examples above is the HEAD of the remote repository (usually on GitHub). I use the remote name origin for the remote containing the latest version of the default branch. If your naming is different, adapt the commands accordingly.

The command remote show origin provides all relevant information about the remote, including the HEAD branch which can be filtered out with git remote show origin | sed -n '/HEAD branch/s/.*: //p'. The downside of this approach is that it queries the remote, so it will take quite a long time due to network latency, and will only work if you are online.

Fortunately there is a local representation of this information available via git symbolic-ref refs/remotes/origin/HEAD, but it may be out of date or unavailable (in which case you will see the error fatal: ref refs/remotes/origin/HEAD is not a symbolic ref). To update it, run git remote set-head origin --auto.

Implementing the `default-branch` Command

Since I want to neither memorize nor type out these commands all the time, I package them up in two git aliases in my .gitconfig:

[alias]
	default-branch = "!git symbolic-ref refs/remotes/origin/HEAD --short | sed 's|origin/||'"
	update-default-branch = remote set-head origin --auto

Now you can update the information with git update-default-branch and then use the git default-branch as shown in examples at the top or however else you like.

If you prefer the slow, always up-to-date version with online requirement, use the following alias instead:

[alias]
	default-branch = "!git remote show origin | sed -n '/HEAD branch/s/.*: //p'"

Q&A

The remote names differ across my repositories, so I can't put the alias with an origin remote into my gitconfig?

If you want the same alias to work across all repos, you will have to set up consistent branch names.

Let's assume origin always points to your personal github repo, but for some repos your default branch lives in you repo while in other cases, your repo is a fork and your default branch lives in the upstream remote. In that case I suggest to add an upstream remote to all repos (even if it will be identical to origin when your repo contains the default branch). This allows you to use upstream in the alias and have your alias work across all repos again.

Why don't you create a local branch called default that points to the default branch on the remote?

This would also be a valid solution, but I am easily confused when local branch names don't match remote branch names.

Simple Testing with `git diff`

2022-07-30T16:14:20+02:00

Simple Testing with `git diff`

Automatic tests are great, but creating and maintaining them is time consuming and sometimes really complicated. Often, getting a moderate test coverage to prevent regressions is important, but written a "proper" test suite is more work than you can justify. Let me show you how to solve this in a way that is easy to apply and does not rely on any specific programming language or ecosystem.

Snapshot Testing

What is a quick way to get test cases? You take a well defined run of your program (usually something you did during manual testing before) and save the output. After changing your code, you run the program again and compare the outputs. This can yield one of three results:

The output stays the same. You now know that you did not add a regression for this test case.
The output differs in a wrong way. Go fix your code!
The output differs in just the way you intended when changing the code. You should mark the new output as correct.

This approach is called "Snapshot Testing" and is especially useful when your program's output is so large that it is hard to describe in a test, or when you need to guarantee backwards compatibility across a huge number of test cases. But it is also great for creating high level tests quickly.

Testing snapshots with `git diff`

There are libraries that can help you do snapshot testing. But those usually rely on a specific programming language, test runner or other infrastructure and take some time to learn. I prefer to go with tools I and most other developers already know and use: git, sh and optionally make. What do we actually need? We need a way to

generate the output
compare the differences to the accepted output
mark output as accepted

Generate Output

This is the hardest part and the part that depends on your specific program the most. If it is a simple unix tool, you can just create a directory with program inputs and write a small script to generate and save the corresponding outputs. I like to put such things in a Makefile like

# We want to generate one .out file for each .in file in `tests`
test: $(patsubst %.in,%.out,$(wildcard tests/*.in)) 

# An .out file can be created by calling myprogram on the corresponding .in file
%.out: %.in myprogram
		./myprogram $< > $@

Mark Output as Accepted

It is good practice to store the test cases along with the code in you git repository. So let's just add and commit the output to the git repo! I know the general rule is to not add generated files to git, but this is no random output, it is our test suite!

Compare the Differences to the Accepted Output

Now that we have our accepted output in git, it is trivial to check for differences and show them in a nice way:

git diff -- tests

It is a good idea to add --exit-code so that a difference (and thus a failing test) will yield a non-zero exit code. Adding that to the test make target above results in

# We want to generate one .out file for each .in file in `tests`
test: $(patsubst %.in,%.out,$(wildcard tests/*.in)) 
		git diff --exit-code -- tests

# An .out file can be created by calling myprogram on the corresponding .in file
%.out: %.in myprogram
		./myprogram $< > $@

which will run you code on all test cases and compare the results with just a run of make test. A complete test runner, implemented in just four lines of make!

Common Objections

My Output Is Not Diffable

If your output is not very readable in the default diff format, there are ways to improve the situation (in order of preference):

change your output to be more diffable (e.g. sort objects by keys if your output is JSON)
postprocess your output (run PDFs through pdftotext)
use a custom diff tool with git (you can configure different diff drivers per file type via git attributes)
write a custom script to compare the outputs instead of using git diff

My Program Does Not Create Output Files

Make it do so!

Write a thin wrapper around core parts of you logic and serialize the results
If it outputs user interfaces, you could create screenshots of them
If it creates network traffic, capture it
Get creative!

This will not only help with automatic testing, but allow you to script you program for one-off tests or other tasks.

This Does Not Create Unit Tests

No, it doesn't. Oftentimes, you don't really need unit tests if your overall testing exercises your code well. You can still add unit tests later if you realize you need them. This is mostly about getting working tests with low effort, not about creating the perfect test suite.

Does This Work for Real Projects

Yes, I have used it in multiple commercial projects, as well as for the smu markdown parser.

`make` as a Static Site Generator

2022-06-14T14:30:11+02:00

`make` as a Static Site Generator

Static site generators are in fashion for good reasons. The resulting pages are easy to host, fast and extremely low on maintenance while being sufficient for many use cases. As I learned when setting up my blog, writing a simple script myself is faster and more satisfying than learning one of the other site builders and customizing it to my needs. This time, I only need a plain site without automatically updated timestamps or an RSS-feed, so I can go even simpler than by blog script.

Basic setup

To get the site into a working state, I require the following functionality:

All input files reside in the source directory, in the same layout as I want them in the output.
During processing, add a header to all HTML files.
Copy all other files to the build directory as they are.

Each of these points results in one rule in the Makefile:

# The `build` target depends on all output files in the `build` directory. It
# does not do anything by itself, but causes one of the following rules to be
# applied for each file.
build: $(patsubst source/%,build/%,$(shell find source -type f))

# For each .html file do `cat header.html $input > $output`.
build/%.html: source/%.html header.html Makefile
	@mkdir -p $(dir $@)
	cat header.html $< > $@

# Copy all other files without changes.
build/%: source/%
	cp $< $@

With a corresponding header.html and these rules in place, calling make build will create a build directory that can be browsed locally or uploaded to any web server.

Variations

This is really all you need, but the real strength of this approach is that it is so simple, that you can trivially extend it to fit different needs. Let me show you a few examples!

Mark Current Page

It is helpful to highlight the current page in the navigation so that the visitor sees where he is within the site at a glance. To do this, we search for the link within the navigation and replace the link with a highlighted version. The specifics vary depending on your markup. I'm using the following code to add the current class to the link tag:

build/%.html: source/%.html header.html Makefile
	@mkdir -p $(dir $@)
	sed -E 's|(href="$(subst source,,$<))|class="current" \1|' header.html | cat - $< > $@

Generate Page From Markdown

If you dislike writing HTML or if you have existing content in markdown format, you can pipe your markdown content through a markdown-to-HTML converter of you choice (I like smu).

build/%.html: source/%.html header.html Makefile
	@mkdir -p $(dir $@)
	smu $< | cat header.html - > $@

Since we still assume that build/foo.html is built from source/foo.html, you should keep the .html suffix for the markdown files or modify the rules to look for .md files as input.

Little Helpers

You can not only modify the site generation itself. Convenience features can also be added as additional make targets.

Serve Site Locally

Not all sites can be accurately previewed by opening the local files in your browser. The most common reason for this is using absolute links instead of relative ones. In those cases, you will want to run a small test web server locally to preview your site. Python is already installed on many systems and comes with a web server this is suitable for the task.

serve:
	python -m http.server -d build

Rebuild on Change

If you work a lot on your site, manually rebuilding after each change is a hassle. Just use entr (or inotifywait if you want to avoid the dependency) to rebuild automatically when a file in the source directory changes.

watch:
	find source header.html Makefile | entr make build

Upload to GitHub Pages

I store my repositories on GitHub, so using GitHub Pages to host the resulting HTML is a natural choice. Getting the commands just right so that you don't have to care about git details when publishing is a bit tricky, but easy enough in the end. The approach is based on Sangsoo Nam's post.

deploy:
	git worktree add public_html gh-pages
	cp -rf build/* public_html
	cd public_html && \
	  git add --all && \
	  git commit -m "Deploy to github pages" && \
	  git push origin gh-pages
	git worktree remove public_html

Summary

Having your own static site generator in only six simple lines in a Makefile is great! There are no exotic dependencies, nothing to maintain and you can quickly adapt it to your needs. A page I built using this approach is available at https://github.com/karlb/astridbartel.de and can serve as a real world example.

When Is Complexity OK?

2022-04-03T09:54:28+02:00

When Is Complexity OK?

We all known complexity is bad. It slows down development, makes bugs more likely, increases the maintenance burden and makes it harder to onboard new developers. So why do we still have complex software everywhere? Legacy code, misaligned incentives, unclear goals, bad development practices or sheer incompetence can be causes. But even well run projects often get very complex because it is required to achieve the desired outcome ("essential complexity"). Distinguishing between essential and accidental complexity is hard and even if I could identify and remove all accidental complexity, one question would remain: Is the complexity level of this project healthy, or do I have to fundamentally change the overall approach (or declare the project a failure)?

If I manage to keep the project very simple the answer is obvious, so let's ignore that case. Just looking at the complexity level is not sufficient, since there are many projects of significant complexity which are very health and have a bright future (e.g. Linux, SQLite, PostgreSQL). But these projects are mature enough to carry the weight of their complexity. But projects don't start out incredibly mature, so I need to know if they are on the trajectory to get into the realm of complex but healthy and mature, or whether they are set up for failure. Looking back, the best way to find out was to ask myself

"Is the project getting more mature faster than it is getting more complex?"

Complexity                    Complexity                
^                             ^                /
|                             |               /
|            ____             |             _/    
|        ___/                 |            /
|     __/                     |          _/
|   _/                        |         /
|  /                          |       _/
| /                           |    __/
|/                            |___/
+--------------> Maturity     +--------------> Maturity
  healthy project               unhealthy project

When I'm trying to get an early version mostly stable and bug-free, but each time I fix a problem, I have to add new concepts to handle those cases, that is an indication that I can't improve the maturity faster than the complexity. After all, when even fixing bugs does not improve the maturity/complexity ratio, then adding new features will be even worse. Continuing to work in the same won't be sustainable and I should look for a different approach of declare the project a failure. On the other hand, if I am able to fix bugs and fine-tune the program behavior without increasing the code size or making it harder to read, then I'm right on my way into the healthy "more mature than complex".

So now that you know my complexity assessment heuristic, let me point out some details:

I used the term "project", but the same approach works on different levels. E.g. a complexity and maturity of a single feature can be compared in the same way.
When the result is unclear, assume that you are in the unhealthy case. We tend to overestimate maturity until we had enough time to observe many edge cases.
There certainly are other approaches which are better in specific cases, but this one is the most generic approach that yielded good results for me.
Time is mostly orthogonal, since it can be used to move in any direction in the complexity/maturity space.

As always, if you have any feedback, don't hesitate to let me know!

Formatting Numbers of Unknown Order of Magnitude

2021-05-01T15:07:39+02:00

Formatting Numbers of Unknown Order of Magnitude

Sometimes, I write programs that need to display numbers where I don't know how big or small they will be. The most common approaches of printing numbers won't be very helpful in such a case.

# Default print: more decimal places than useful
>>> print(1324325425.3254435363463)
1324325425.3254435

# Fixed amount of decimal places: better, but ...
>>> print("{:.0f}".format(1324325425.3254435363463))
1324325425
# ...useless results for small numbers
>>> print("{:.0f}".format(0.3254435363463))
0

A good way to deal with this problem is to use the scientific notation, which displays the mantissa and exponent separately.

>>> print("{:e}".format(1324325425.3254435363463))
1.324325e+09
>>> print("{:e}".format(0.3254435363463))
3.254435e-01

However, not everyone is used to reading the scientific notation and many programs don't accept it as input. What I often want to have is a format that:

does not irritate humans
is understood by all programs
is not unnecessarily verbose

One way to reach this is to round to a fixed number of significant figures.

>>> def fmt_sig(x, sig_figures=3):
...     show_dec = -floor(log10(abs(x)) + 1) + sig_figures
...     return round(x, show_dec)
...
>>> print(fmt_sig(1324325425.3254435363463))
1320000000.0
>>> print(fmt_sig(0.3254435363463))
0.325

But rounding the big number can be confusing because it only has an accuracy of three digits while showing eleven digits. My suggested solution is to format numbers with a minimum number of significant figures and to print all places before the decimal point for big numbers.

>>> def fmt_min_sig(x, min_sig_figures=3):
...     show_dec = max(-floor(log10(abs(x)) + 1) + min_sig_figures, 0)
...     return ("{:." + str(show_dec) + "f}").format(x)
... 
>>> print(fmt_min_sig(1324325425.3254435363463))
1324325425
>>> print(fmt_min_sig(0.3254435363463))
0.325
>>> print(fmt_min_sig(12.3254435363463))
12.3

This approach has worked well for me, but I have not seen it any other code bases. That makes me wonder: Did I miss any downsides? Are others doing the same and I just didn't notice? Or is there a better way to do the same? If you have the answer to one of these questions, please let me know!

Update (2026)

It turns out that JavaScript's Intl.NumberFormat supports this formatting strategy since the V3 proposal shipped in browsers. The ICU library that powers it calls the underlying concept "relaxed precision". You can get the same behavior as fmt_min_sig with:

const fmt = new Intl.NumberFormat("en", {
  minimumSignificantDigits: 3,
  maximumSignificantDigits: 3,
  maximumFractionDigits: 0,
  roundingPriority: "morePrecision"
});
fmt.format(0.0123456)  // '0.0123'
fmt.format(123456.78)  // '123,457'

The morePrecision mode resolves conflicts between the two rounding strategies by picking whichever produces more digits. For large numbers, maximumFractionDigits: 0 wins (keeping all integer digits). For small numbers, minimumSignificantDigits: 3 wins (keeping three significant figures). That is exactly the max() in fmt_min_sig.

Adding Gemini Support With Just a Few Lines of Code

2021-01-31T11:33:01+01:00

Adding Gemini Support With Just a Few Lines of Code

The Gemini protocol nicely matches my preference for simplicity, so I want to start providing content for it to show my support. The first step for doing that is providing this blog via Gemini. I'll quickly summarize the steps that were necessary to do this in this post.

What is Gemini?

Gemini is an extremely simplified version of the web. It doesn't have Javascript, CSS (or any other kind of styling) and it's markup language Gemtext is much simpler than Markdown. It doesn't use HTTP, but works in a similar way. Don't be irritated by the lack of content about Gemini on the web. You'll see most of the content about it only after installing a Gemini client. My recommendation is LaGrange. The great thing about Gemini is that both creating and consuming content is pretty easy due to the low complexity in every regard.

Generating Gemtext

I don't want to write each block post twice, so I'd like to convert the existing posts (written in Markdown) to Gemtext automatically. Fortunately, there's md2gemini, which can handle the conversion process. Since Gemtext does not support inline links, the links in my posts have to be moved out of the paragraphs into separate lines. md2gemini offers multiple ways to that. Putting the links at the end of each paragraph and numbering the references inside the paragraph (like this [1]) seemed like the most readable way to me, so I chose that one.

The resulting Gemini pages worked, but had two problems left:

The comments I left for myself in some posts suddenly became visible
The HTML-links I use to include the rel="me" attribute on the index page were not converted

Both of these issues arise because md2gemini does not try to interpret HTML (which is allowed in Markdown documents). The easy fix was to replace the HTML markup before passing it to md2gemini with regular expressions:

s/<a href="([^"]*)".*>(.*)<\/a>/[\2](\1)/g
s/^<!--.*-->//gsm

Combined with the call to md2gemini, this led to the following shell function to process Markdown to Gemtext.

GEMINI() {
	<"$1" perl -0pe 's/<a href="([^"]*)".*>(.*)<\/a>/[\2](\1)/g;s/^<!--.*-->//gsm' | md2gemini --links paragraph;
}

Now I can use this inside my page generation loop, I just have to replace the target suffix and append the last modification date.

GEMINI "$filename" | \
	   sed "$ s/$/\\n\\n$dates_text/" \
	   > "$(echo "$target" | sed s/.html/.gmi/)"

With the posts working, I'm still missing a proper index page. It should consist of an introductory text and a list of blog posts, ideally prefixed by the ISO date of the post, so that it matches the optional Gemini feed format. Instead of doing any abstractions, I just copied the index generation code for the HTML version and adapted it to Gemtext.

index_gmi() {
       # Intro text
       GEMINI index.md

       # Posts
       while read -r f title created updated; do
               if [ "$created" = "draft" ] && [ "$2" = "hide-drafts" ]; then continue; fi
               link=$(echo "$f" | sed -E 's|.*/(.*).md|\1.gmi|')
               created=$(echo "$created" | sed -E 's/T.*//')
               echo "=> $link $created - $title"
       done < "$1"
 }

That's all that was necessary to create Gemtext pages for my blog. Right now, there are only two things I plan to improve in the future:

Add the list of my projects. That page is not a blog post and thus slightly special.
Keep links between blog pages consistent. Right now, they all link to the HTML version, even in the Gemini version.

Setting Up the Server

Since Gemini doesn't use HTTP, I can't just copy the generated pages to my normal webspace. Fortunately, setting up a Gemini server is pretty easy.

Choosing a Server

There are plenty of Gemini servers. I chose gmnisrv for the following reasons:

Few dependencies (written in plain C)
Automatic certificate handling (Gemini always uses TLS and thus needs certificates)
Support for virtual hosts, which will allow me to add more Gemini services on the same host in the future

Installing gmnisrv

The compilation and installation was dead simple and done in a minute, just by following the instructions in gmnisrv's readme. Writing the configuration was also straightforward and resulted in this small config.

listen=0.0.0.0:1965 [::]:1965

[:tls]
store=/var/lib/gemini/certs

[gmi.karl.berlin]
root=/home/karl/hosts/karl.berlin/

The Gemini server itself worked now, but it was not reachable from the outside, yet. The two missing steps were

Configure the DNS setting for gmi.karl.berlin.
Open the Gemini ports in the firewall: sudo ufw allow 1965/tcp

As a final touch, I added a systemd unit to automatically start gmnisrv.

[Unit]
Description=gmnisrv Gemini server (see /usr/local/etc/gmnisrv.ini for config)

[Service]
Type=simple
Restart=always
RestartSec=5
ExecStart=gmnisrv

[Install]
WantedBy=default.target

Please note that you want to use a non-root user if there are other important services on the machine.

Result

That's it! If you are still reading this in your web browser, fire up your Gemini client and look at the result! Considering that this was a low effort way to create a presence in Gemini space, I'm quite pleased with the results.

My next goal regarding Gemini will be to bring WikDict to Gemini, which should be a bit more challenging.

Tcl as a Shell Scripting Replacement

2021-01-06T13:23:57+01:00

Tcl as a Shell Scripting Replacement

Summary: I got interested in the old scripting language Tcl, rewrote my blog generator in it as an exercise and compare it to shell scripting.

Motivation

Every once in a while, the "Tcl the Misunderstood" article by antirez gets to the front page of Hacker News. I've read it at least two of those times, since I appreciate antirez' opinions and I'm generally interested in programming languages. I've also often heard of Tk, one of the few simple cross-platform GUI libraries, which comes bundled with your Tcl install. Tcl is also close to the awesome SQLite project, which started out as a Tcl extension.

All of this provided a base interest in the language, but what really pushed me into action was reading the well-written "A Philosophy of Software Design" book by John Ousterhout, the creator of Tcl. When his general ideas about software development resonate well with me, the language he created might do so, too. So I got his other book Tcl and the Tk Toolkit and read through most of it, playing with small code samples along the way. But to get a real feel for the language, I needed to write a real project in it, even if it is a tiny one.

Rewriting My Blog Engine

The simple blog engine I wrote recently is small enough that I could rewrite it in Tcl within a few hours. Rewriting an existing project also gave me the opportunity to compare both versions afterwards, which shows the differences caused by the change of programming language in a nice way. The comparison won't be totally fair for two reasons:

I'm writing the code for a second time, so I already know exactly how I want the program to behave.
I'm biased by the existing implementation, so the code will be less idiomatic in the new language.

I chose to use the existing code as a starting point and port that to Tcl line by line, so the latter point is the more serious one. Even more so, since I'm new to Tcl but have used shell scripting before.

Rewriting Line by Line

Rewriting the first few lines already made one thing obvious: using Tcl in to call external commands is very easy and works mostly like it does in the shell. The code I use to get the time of the first git commit hardly changed:

-	$(git log --pretty='format:%aI' "$f" 2> /dev/null | tail -1)
+	[exec git log --pretty=format:%aI $f 2> /dev/null | tail -1]

The only notable difference is the lack of quoting required in the Tcl version. Tcl's quoting rules are a bit unusual, but actually quite simple and more regular and robust than the ones in traditional Unix shells. I won't go into the details here, but I want to point out one example of increased robustness of the Tcl way. Although list elements are separated by spaces, just like in sh, having spaces in your variables will never make the variable accidentally split into multiple variables. Let's assume you have the following variables:

a="eggs"
b="bacon spam"

When you call myfunc $a $b in sh, you will pass three parameters to myfunc, because b gets split up at the space. In contrast, Tcl will always pass two parameters, irregardless of the content of those two variables. There are ways to avoid this in sh (and even more ways in bash), but I still run into edge cases from time to time and find Tcl's approach more pleasant and sane.

Other changes compared to the shell version were

Use of a nested list instead of writing temporary data to a TSV, because Tcl made it easier to deal with the nested data
Some syntactic sugar like lassign and explicitly named function parameters
Replace some sed usages with built-in string functions

This led me to my first working Tcl version of the blog engine (blog.1.tcl, compare with blog.sh) which resulted in the same output as my original version, except for some insignificant whitespace differences.

Cleaning Things Up

The next step was to go through the code a second time and look for opportunities to simplify and clean up parts that felt out of place in a Tcl program. Calls to sed can be replaced by using Tcl's regex support:

-	set host [exec echo $uri | sed -r {s|.*//([^/]+).*|\1|}]
+	regexp {.*//([^/]+).*} $uri -> host

One use of sed was not as straightforward to replace as I expected. I didn't find a compact way to return a regexp match from a file, so I wrote a small helper function.

proc from_file {re filename} {
	set f [open $filename]
	regexp -line -- $re [read $f] -> match
	close $f
	return $match
}

This allowed me to replace four lines lines like set title [exec sed -n "/^# /{s/# //p; q}" $f] with set title [from_file {^# (.*)} $f]. The regexp is easier to read for me (the curly braces are just part of Tcl's quoting), which somewhat offsets the downside of requiring an extra function. Still, I don't see this as a clear improvement and would like to hear about better solutions.

The simple access to proper data structures also made me replace two calls to git (for getting first and last commit) by a single one and using the list functions get the desired parts from the result.

-       set created [exec git log --pretty=format:%aI $f 2> /dev/null | tail -1]
-       set updated [exec git log --pretty=format:%aI $f 2> /dev/null | head -1]
+       set commit_times [exec git log --pretty=format:%aI $f 2> /dev/null]
+       set created [lindex $commit_times end]
+       set updated [lindex $commit_times 0]

The new code is a bit longer, but less redundant and clearly displays the relationship between created and updated.

Result

Together, these changes resulted in the final version of my blog script (blog.tcl). Let's compare the size and run times as a last discipline.

$ wc blog.*
 105  354 2934 blog.sh
 105  409 3099 blog.1.tcl
 113  406 3143 blog.tcl
 323 1169 9176 total

$ time ./blog.sh
real    0m0,280s
user    0m0,263s
sys     0m0,098s

$ time ./blog.1.tcl 
real    0m0,125s
user    0m0,078s
sys     0m0,071s

$ time ./blog.tcl 
real    0m0,111s
user    0m0,085s
sys     0m0,035s

So the script got marginally longer but significantly faster, although all versions are more than fast enough for my case. I could probably have kept the file size the same if I wanted, but I went for readability in more cases in the Tcl script. E.g. I used $filename instead of $f and used more lines breaks (with the additional bytes for indentation that come with it) in cases like this escaping of HTML characters:

-	sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/g; s/'"'"'/\&#39;/g'
+	string map {
+		& &amp;
+		< &lt;
+		> &gt;
+		\" &quot;
+		' &#39;
+	}

Overall, the effort for porting was low and I'm happy with the result, especially the improvement in readability.

What Now?

So what do I do with it? Do I use it instead of my old shell version? Do I discard the code just as part of an experiment? I'm not sure, yet. I like the new code, but should I add another language to the zoo of code bases I'm maintaining? I guess it will depend on whether I find Tcl suitable for other projects. I currently see three areas that seem interesting:

shell scripting replacement, as described in this post
python alternative in certain use cases (lots of external programs or heavy meta programming)
as language for interactive shells

Originally, I wanted to write about the latter two points in this article, too. But it got long enough as it is and writing separate posts will keep me more focused. If those topics sound interesting, let me know to make sure that I actually get around to writing those posts!

My Simple Custom Blog Software

2020-08-30T16:35:19+02:00

My Simple Custom Blog Software

The pages on this site are generated by my own primitive blog engine. This post summarizes why I wrote my own, what my priorities for it were and how I went about achieving them.

Why Something Custom?

Originally I wanted to use Hugo for this blog. I started to look for a simple theme that did not involve many dependencies and provided clean output. This quickly frustrated me because the themes were either not minimal at all or I could not get them to work with my version of Hugo. This made me take a step back and think about what I actually want as blog output. I wrote a tiny HTML header, a small test blog article in markdown and did cat header.html > post.html && smu post.md >> post.html. The result looked good and that convinced me that writing a small blog creation script was more rewarding and maybe even faster than configuring something existing the way I like it.

Requirements

Before jumping deeper into it, I made a list of my basic requirements:

Low maintenance
Low barrier to create content (markdown)
Low requirements on the client (web browser, internet connection, RAM, CPU)
Shows creation and update timestamps of posts
RSS feed

How I Achieved These Constraints

Low Maintenance

Avoid dependencies: only a POSIX shell and a markdown converter are required. Dependencies always increase the maintenance burden.
Static files: hosting static files is much easier to do reliably than hosting dynamic content

Low Barrier to Create Content

Use markdown: when writing markdown I can mostly avoid thinking about the syntax and focus on the content
Automatically generate timestamps: generating the timestamps from the git history allows me to just create posts without needing any templates or front matter to provide this data. I also can't forget to update these timestamps.

Low Requirements on the Client

This is mostly solved by not doing anything complicated. Not adding any JS and CSS frameworks keeps the size small. Not setting a font size and not disallowing zooming makes the text readable on a wide variety of devices and by people of bad eye sight. Just using basic HTML and a few lines of CSS allows old or limited browsers and slow computers to display the page easily. I could go on for a long time here, but I'm sure you get the concept.

RSS Feed

Adding an RSS feed (an Atom feed to be precise) was the most complicated part of the script. But I really love RSS and in my opinion RSS support is an essential part of a blog. I was shocked to learn that nowadays some blog engines need plugins to get RSS support! Writing something that is nearly a valid Atom feed is pretty easy. Just take the example Atom feed and fill in your own values. But to make it standard compliant and work well with different clients, I also needed to

Use an absolute feed URL. I usually avoid absolute URLs, as that makes local testing easier.
Generate good IDs for the posts. This was the hardest part, see Mark Pilgram's recommendations to see the challenges in detail.
Include the post content while escaping the HTML tags

Results

The HTML Output

No JS, no tracking, no custom fonts
No external CSS
Minimal styling
This page weighs just 7K, most of it the text you are reading right

The largest part of the CSS is the styling of the navigation bar. I could have went with a line of text links separated by spaces, but I wanted to have a clearly visible navigation at the top. Using such a small amount of CSS also removed the need for any CSS preprocessors like Sass.

The Blog Script

You can find the code of the resulting script on github. The blog you are currently viewing is part of the same repository and serves as example content.

To make the script work as intended, you should adhere to the following rules:

Use git and don't edit history after publishing. This is required for the automatic timestamp generation.
All posts and the index.md have a title using the # syntax. This title is used for the HTMl title tag and for the post titles in the article listing and RSS feed.
header.html contains an absolute link to your atom.xml, including a hostname you control. This is necessary to build a correct atom feed.
Uncommitted files are drafts and won't show up in the normal article list, but are shown in index-with-drafts.html.

Feel free to contact me if you have any questions. If you want to use it for your own site, I can give some guidance. Since I don't expect many users, this is less effort than writing and maintaining good documentation.

Hacking on "smu", a Minimal Markdown Parser

2020-05-06T17:26:23+02:00

Hacking on "smu", a Minimal Markdown Parser

Introduction

I wanted to get my hands dirty and improve a suckless related program. So I had a look at the project ideas page and picked out something simple:

Improve the Markdown parser used by the suckless wiki called "smu" to conform more to Markdown. for example for nested codeblocks. Difficulty: trivial-medium.
Specs: http://daringfireball.net/projects/markdown/syntax.text and http://commonmark.org/.
smu: https://github.com/Gottox/smu

First Impressions

While C is pleasantly simple in many regards, writing good code can be quite cumbersome if you're not used to it. I didn't write any serious amount of C for many years and I tend to think that C is generally a bad choice for anything that does large amounts of string manipulation. I was expecting many regular expressions and some hard-to-get-right memory allocation code. To my surprise, I didn't find a single regex and hardly any memory management code. Instead of regexes, the code relied on basic string functions like strstr and lots of manually-iterating-through-char-arrays.

Like most suckless programs, smu consists of a single C file with only a few hundred lines (624 in this case), had no dependencies and compiled instantly without the need to run a configure script.

How smu Manages to Stay Simple

Put Logic Into Data instead of Code

Markdown has a large amount of different syntax elements, but many of them behave in similar ways. Smu takes advantage of this by declaring the different syntax elements in data structures that can be processed by a small amount of different functions. Here's one example:

static Tag lineprefix[] = {
    { "   ",        0,  "<pre><code>", "</code></pre>" },
    { "\t",         0,  "<pre><code>", "</code></pre>" },
    { "> ",         2,  "<blockquote>", "</blockquote>" },
    { "###### ",    1,  "<h6>",         "</h6>" },
    { "##### ",     1,  "<h5>",         "</h5>" },
    { "#### ",      1,  "<h4>",         "</h4>" },
    { "### ",       1,  "<h3>",         "</h3>" },
    { "## ",        1,  "<h2>",         "</h2>" },
    { "# ",         1,  "<h1>",         "</h1>" },
    { "- - -\n",    1,  "<hr />",       ""},
};

These declarations provide the basis of handling code indents (both with spaces and with tabs), blockquotes, headings of different levels and horizontal rules. All of these different syntax elements can now be processed by a single small functions (~45 lines). Not only does this reduce the amount of code, but it also makes it a lot easier to get an overview of the possible markup constructs and how they relate to each other.

Avoid Memory Management

Since these syntax elements have to be parsed into different parts (markdown syntax, content, link title, link target, etc.), I was expecting many strings allocations to hold these parts. But smu gets around this in most cases by doing one of these two things:

Instead of saving the parsed data structures, the corresponding output is generated immediately, so that the parsed strings don't have to be saved at all
Instead of allocation a new string, two pointers are used to mark the desired substring in smu's input.

Simplify Spec

Markdown is not something that falls out of a beautiful mathematical model, rather it is grown over the time, driven by what people "mean" when they write pseudo-plaintext. This led to a bunch of weird edge case handling rules and syntax oddities. Smu took the liberty to ignore parts of markdown (reference style links) and handle some details differently (escaping, white space handling).

Changing smu

Test Suite

As mentioned above, I didn't write C for a long time. I also was not sure how all Markdown should be interpreted in detail. So to prevent me from breaking everything, I needed some way to spot regressions or other bugs. When looking for Markdown test cases, I found mdtest and took a set of basis tests from it that mostly worked with smu. Then I looked through the remaining differences and tried to understand why smu delivered different results. That way, the tests did not only provide some safety while hacking on smu, but also showed me where it differed from other markdown implementations.

To turn the (input, expected output) pairs into automated test cases, I committed both to git and added a make target that regenerates the output and runs git diff on the test directory. When the diff shows no output, the tests have passed! This will give more false positives than mdtest's algorithm that accounts for insignificant white space, but it is much simpler.

CommonMark Compatibility

These differences provided a nice starting ground for the first steps towards improved markdown compatibility. I could pick some minor differences that could easily be adjusted by modifying just a few line of code. At the same time, I collected a list of differences to CommonMark that I noticed but couldn't (or didn't want to) fix right away in order to add that to the documentation.

By doing a few of these changes I got more confident when changing the code and felt ready to start bigger changes. For my personal usage, one feature omitted by smu proved to be a annoyance: code fences. Without code fences, copy/pasting code to and from your markdown code blocks requires changes in indentation, which is error prone and a bit of a hassle. To implement code fences, extending one of the lists of syntax elements was not enough, since they work neither by prefixing every line of the block nor are the surrounding markers for other elements sufficient to accurately capture their block behavior. So I unfortunately had to add another parsing function to handle them correctly. That however, worked without much surprises and yielded results to my satisfaction.

One other conceptual difference I introduced was a different escaping rules. Originally, smu had the simple rule of escaping the characters \ ` * _ { } [ ] ( ) # + - . !. This worked fine in most cases, but brought downsides with it:

There is not way to escape text parts that look like HTML but aren't
Some code parts containing backslashes lost their backslashes unless you escape them (bad for copy/paste).

To remedy the first problem, I looked up the CommonMark escaping rules and added all characters from the CommomMark list to smu's list of escaped characters. Inside code spans, \` was the only escape needed to be allowed, since it would mean the end of a code span without escape and all other characters have no special meaning inside code spans/blocks. But this was an ugly special case in the code and would also lead to silently broken code samples when you add code that does contain a literal \`. How does CommonMark deal with this? The rules for code spans and code blocks allow an unlimited amount of different start and end markers, so markers can be chosen that are not present in the code itself. I chose a subset of these rules that could be expressed with smu's existing matching declarations, so that you can write `` ` `` if you want a code span that contains a single backtick (The pair of single white spaces is ignored). When first reading the CommonMark specs, I felt that these rules were strange and arbitrary, but after trying to find simpler alternative, I started to appreciate the spec more and more, even though I still consider parts of it to allow an unnecessarily amount of different syntaxes.

Conclusion

Overall, the small and well structured code base allowed me to dive into the project quickly and get my first small success within the first hour of coding. This is a pleasant contrast to bigger software projects where I'm sometimes happy to have it build successfully during that time frame. The only thing that really slowed me down was the lack of tests, since I didn't dare to change most parts before I added some test coverage.

The resulting program is very usable for my markdown use cases (it rendered this page), but I would not dare to run it on potentially malicious input. I'm also not sure how well the HTML pass-through works, since I haven't used it myself, yet.

The increased CommonMark compliance should make it easier for new users to start working with smu, but it did come at a slight increase of complexity. My version is ~100 lines longer, but about half of that is comments, blank lines and additional escaping declarations. This feels like a good trade off to me.

The result can be seen on my smu fork's github page. Feedback welcome!

Suckless Software on My Desktop

2020-04-28T19:37:01+02:00

Suckless Software on My Desktop

I took a look at which simple programs I could use as a desktop environment instead of Gnome and picked out the following ones

st as a terminal
dwm as a window manager, along with slstatus
slock for screen locking

Initial Impression

The suckless tools are configured by editing C header files before compilation. This is pretty straightforward to do in most cases, but it requires dealing with source changes in git repos instead of using config files. For now these changes stay outside my dotfiles repo and I'm not sure about the best way to version and sync this type of configuration.

One very pleasant aspect is how easily and fast the programs compile. They have hardly any dependencies and compilation is finished nearly at the same moment as you hit the enter key to call make.

Since each of the programs handles only a single concern, you have to collect more of them than you're used to when you want to cover the usual amount of use cases. This allows freely mixing and matching different tools as you like. I like the general approach, but would have preferred a way to get a selection of recommended programs and configs and start using a known-good setup before fiddling with the details.

Additional Configuration

xbindkeys

I want to be able to change the volume and screen brightness with the media keys and have a keybinding to turn off and lock my screen. This can be configured with xbindkeys by assigning shell commands to certain keys. This has a nice unix feel to it, but needs some fiddling to get right. I also miss the visual feedback when changing brightness and volume.

# Brightness +
"lux -a 100"
    XF86MonBrightnessUp 

# Brightness -
"lux -s 100"
    XF86MonBrightnessDown 


# Increase volume
"pactl set-sink-volume @DEFAULT_SINK@ $(pacmd list-sinks | awk '/volume:/ {print int($3 * 1.2); exit}'); pacmd list-sinks | awk '/volume:/ {print $5; exit}' | dzen2 -p 2"
   XF86AudioRaiseVolume
# Decrease volume
"pactl set-sink-volume @DEFAULT_SINK@ $(pacmd list-sinks | awk '/volume:/ {print int($3 * 0.8); exit}'); pacmd list-sinks | awk '/volume:/ {print $5; exit}' | dzen2 -p 2"
   XF86AudioLowerVolume
# Mute volume
"pactl set-sink-mute @DEFAULT_SINK@ toggle"
   XF86AudioMute

# Shift + super + L locks screen and turns display off
"slock & (sleep 1 && xset dpms force off)"
   Shift + Mod4 + l

# turn screen off
"sleep 1.0 && xset dpms force off"
   shift + mod4 + s

"systemctl suspend"
   shift + mod4 + z

"autorandr -c"
   control+shift + a

# toggle redshift
"killall redshift || redshift -l 52.5200:13.4050 -b 0.7:0.3 &"
   shift + mod4 + r

Problems

autolock

I didn't find an autolock setup that worked as well as I would like. My goal would be:

Lock screen when sleeping or after X minutes
Turn screen off when locking
Don't lock when watching fullscreen videos in Firefox

I could not get the last point working reliably for me with xautolock or xidlehook (bug report). I stopped using autolock and just manually lock my screen.

Versioning My Setup

As noted above, the suckless tools don't use config files, so they I can't put their configuration in version control as I am used to.

Lack of Good Predefined Setup

While the programs work well and reliably, using them is not just matter of installing and running them. Getting to a usable setup involves quite some time of choosing the right set of programs and configuration that works for you. I would have liked a known-good setup as a starting point.

Exercises in Simplicity

2020-04-19T14:00:55+02:00

Exercises in Simplicity

The more time I spent on software development, the more I come to appreciate simplicity. When software is buggy, slow or lacking features, that is annoying. But as long as it is simple, I can still understand the limitations and work around them or even fix them. When something goes wrong in a complex program, it is often not worth spending the huge amount of time necessary to even understand what is happening. Instead of learning about the problem your software solves, you are drowned in build tools, pre- and post-processors, too many layers of abstractions, many different APIs and huge amounts of dependencies.

Dealing with simpler software is more satisfying for me and provides a faster way to deep understanding. I want to write a few posts about the different ways I approach simple software. Sometimes, I want to replace a program I use by something simpler, in other cases I just want to try something out in order to learn how much of the complexity of common solutions is really necessary.

Guidelines

Simplicity is more important than features.
Usability must not suffer too much.
If I start with something minimal, some growth over time is ok. The important thing is a high ratio between benefit and increase of complexity.

Exercises

This web site itself
Vim instead of IDE (see my vim config)
Use suckless software on my desktop
Hacking on a minimal markdown-like parser

Inspiration

Quotes

Controlling complexity is the essence of computer programming.

-- Brian Kernighan

Simplicity is prerequisite for reliability.

-- Edsger W. Dijkstra

A program is like a poem: you cannot write a poem without writing it. Yet people talk about programming as if it were a production process and measure "programmer productivity" in terms of "number of lines of code produced". In so doing they book that number on the wrong side of the ledger: We should always refer to "the number of lines of code spent".

-- Edsger W. Dijkstra

Karl Bartel's Website

Can We Make Simpler Software With LLMs?

Can We Make Simpler Software With LLMs?

The Project

No Dependency Management

No Build System

Two Implementations Without Transpilation

Avoid Needless Inconsistency

Verdict

Raising Notifications From Terminal

Raising Notifications From Terminal

Using notify-send (Linux)

If You Already Started the Job

Notify on Success or Failure

Using osascript (macOS)

The Terminal Bell

OSC 777

Closing Thoughts

Stack Traces are Underrated

Stack Traces are Underrated

I Love Stack Traces

The Case of the Missing Trace

Modern Error Handling

More Complicated Architectures

Closing Thoughts

Easily Entering Umlauts With a US Keyboard Layout

Easily Entering Umlauts With a US Keyboard Layout

Previous Approach: xmodmap

New approach: xkb

Alternatives

Consistent Handling of Git Repositories With Different Default Branches

Consistent Handling of Git Repositories With Different Default Branches

Why Do I Care About Default Branches?

How to Determine the Default Branch

Implementing the default-branch Command

Q&A

Simple Testing with `git diff`

Simple Testing with git diff

Snapshot Testing

Testing snapshots with git diff

Generate Output

Mark Output as Accepted

Compare the Differences to the Accepted Output

Common Objections

My Output Is Not Diffable

My Program Does Not Create Output Files

This Does Not Create Unit Tests

Does This Work for Real Projects

`make` as a Static Site Generator

make as a Static Site Generator

Basic setup

Variations

Mark Current Page

Generate Page From Markdown

Little Helpers

Serve Site Locally

Rebuild on Change

Upload to GitHub Pages

Summary

When Is Complexity OK?

When Is Complexity OK?

Formatting Numbers of Unknown Order of Magnitude

Formatting Numbers of Unknown Order of Magnitude

Update (2026)

Adding Gemini Support With Just a Few Lines of Code

Adding Gemini Support With Just a Few Lines of Code

What is Gemini?

Generating Gemtext

Setting Up the Server

Choosing a Server

Installing gmnisrv

Result

Tcl as a Shell Scripting Replacement

Tcl as a Shell Scripting Replacement

Motivation

Rewriting My Blog Engine

Rewriting Line by Line

Cleaning Things Up

Result

What Now?

Implementing the `default-branch` Command

Simple Testing with `git diff`

Testing snapshots with `git diff`

`make` as a Static Site Generator