commit d5c6458d77493a320f3d9cb6ac956738b5e6441b
Author: MrJensK <jens.se@icloud.com>
AuthorDate: Thu Aug 13 15:33:12 2026 +0200
Commit: MrJensK <jens.se@icloud.com>
CommitDate: Thu Aug 13 15:33:12 2026 +0200
docs: add st quirks section (config.h staleness, cell-vs-pixel sizing, live zoom, icat deps, etc.)
---
README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 55 insertions(+)
diff --git a/README.md b/README.md
index daa9ed2..9079f81 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,7 @@
- [Structure](#structure)
- [sxwm patches](#sxwm-patches)
- [st patches](#st-patches)
+- [st quirks](#st-quirks)
- [Keyboard shortcuts (sxwm)](#keyboard-shortcuts-sxwm)
- [Status bar modules (sxbar)](#status-bar-modules-sxbar)
- [Utility scripts (bin/)](#utility-scripts-bin)
@@ -174,6 +175,60 @@ previews it in `feh`, `Ctrl+Shift+middle-click` shows placement info in
internal state, `Ctrl+Shift+F7` unloads cached images to free RAM, and
`Ctrl+Shift+F8` toggles image display on/off entirely.
+## st quirks
+
+Coming from kitty, a few things about st behave differently enough to be
+worth writing down:
+
+- **Config is compiled in, not read at runtime.** kitty re-reads
+ `kitty.conf` on the fly; st bakes `config.def.h` into the binary at build
+ time as `config.h`. Changing font/colours/keybinds means editing
+ [`config/st/config.def.h`](config/st/config.def.h) and rebuilding (`./install.sh`,
+ or the manual steps below) — there's no config file to just edit and
+ reopen the terminal.
+- **`config.h` doesn't auto-refresh from `config.def.h`.** The Makefile's
+ rule for `config.h` only runs if the file doesn't exist yet — `make clean`
+ does *not* delete it. If you rebuild in a directory that already has a
+ stale `config.h` from a previous build, your `config.def.h` edits are
+ silently ignored. Either `rm -f config.h` before `make`, or always build
+ in a fresh `git clone` (which is what `install.sh` does).
+- **Manual rebuild, step by step** (what `install.sh` does for st, if you
+ want to do it yourself):
+ ```bash
+ cd ~ # don't sit inside the directory you're about to rm -rf!
+ rm -rf /tmp/st-build
+ git clone --depth=1 https://git.suckless.org/st /tmp/st-build
+ cd /tmp/st-build
+ for p in ~/dotfiles/st-patches/*.patch; do patch -p1 < "$p"; done
+ cp ~/dotfiles/config/st/config.def.h config.def.h
+ make
+ sudo make install
+ ```
+- **Live font zoom exists but isn't advertised.** `Ctrl+Shift+PageUp`/`PageDown`
+ zooms the font in/out, `Ctrl+Shift+Home` resets it — built into vanilla st,
+ no patch needed. Easy to miss since kitty's equivalent
+ (`change_font_size`) is the one actually documented in `kitty.conf`.
+- **No runtime equivalent of kitty's per-launch `--override`.** Things like
+ `window_padding_width` or `mouse_hide_wait` are compile-time-only in st;
+ `screensaver-launch` can only override font (`-f`) and alpha (`-A`) when
+ spawning the screensaver's st instance, not padding or cursor-hiding.
+- **Window size is in character cells, not pixels.** `cols`/`rows` in
+ `config.def.h` set the *initial* size; kitty's `initial_window_width/height`
+ were literal pixels. With the `anysize` patch the window can still be
+ resized to any pixel size afterwards, it just doesn't start at one under
+ sxwm anyway since sxwm tiles it immediately.
+- **`icat` needs `imagemagick` and `bc` at runtime**, not just build-time
+ `imlib2`/`zlib`. `make` succeeds without them; the script only fails the
+ first time you actually try to display an image. Both are in
+ `install.sh`'s package list now.
+- **Scrollback is intentionally disabled inside full-screen apps** (vim,
+ less, tmux, etc. — anything using the alt screen). That's the
+ `02-scrollback.patch` behaviour, not a bug — those apps have their own
+ scrolling.
+- **Selecting text copies to both `PRIMARY` and `CLIPBOARD`** (from
+ `03-clipboard.patch`), unlike vanilla st which only ever touches
+ `PRIMARY` on select and needs an explicit keybind to push to `CLIPBOARD`.
+
## Keyboard shortcuts (sxwm)
`mod` = <kbd>Super</kbd>