Logbook For Coding Vintage

So You Want To Log Your Vintage Coding Work

I've spent years trying to keep track of what I was doing on these old machines. Every time I switched between a Commodore 64 and a ZX Spectrum project, something got lost. I'd come back weeks later, stare at a disk labeled "maybe this one," and have no idea where the code left off. That's how I ended up building Logbook For Coding Vintage. The basic idea is straightforward: you keep a plain-text journal alongside your vintage computing projects, and the logbook tool parses it so you can search, filter, and flip between entries without digging through floppy disks or scanning paper notebooks. It runs on modern machines but is designed to work in constrained environments, so you can technically use it on anything with a BASIC interpreter. The real value comes from having timestamps, hardware notes, and code references all in one place.

How Logbook For Coding Vintage Actually Works

You create a .log file per project. Each entry starts with a date line, followed by what you worked on, which hardware or emulator you used, and a short snippet of code if it matters. The parser reads those files and builds a simple index. That's it. Nothing fancy. Here's a minimal entry: 2024-03-12 | C64, Kick Assembler, SID sound test

Wrote a 4-op chord sequencer. Sprite blink still happens at 0x04 where I thought I fixed it. Need to check cycle count. Lines 24-31: lda #$07, sta $d408 The tool picks that apart automatically. You get a calendar view, a keyword search across all your projects, and a raw dump of any entry. If you're working with hardware registers or assembly addresses, the parser highlights them so you can find "all entries mentioning $d408" in two seconds flat instead of opening six different projects and grepping manually.

I built the first version in Python because that's what I had available, then ported the core parser to a tiny C program because I wanted it to run inside a Linux virtual machine without dragging in dependencies. The C version compiles in under three seconds on a machine with 2 GB RAM. It reads log files, builds an in-memory index, and writes an HTML output file you can open in any browser. Total build time from scratch is maybe ten minutes if you're typing slowly.

Installing And Setting It Up

Grab the source from the repository. It's a small repo. Clone it, run make, and you'll have the binary. There's no installer. There shouldn't be one. If you need an installer for a hobby tool, you're probably overcomplicating it. Put your log files in ~/.vintage_log/books/ and point the tool there with a simple config file. The default config uses YAML, but a plain text alternative exists if you prefer not to install a YAML library.

log_dir: /home/user/.vintage_log/books
output_dir: /home/user/.vintage_log/html
date_format: %Y-%m-%d

Run the tool once and it generates the index and the HTML files. Subsequent runs are incremental. If you add three entries, it only processes those three. A full regeneration across twenty projects and four hundred entries takes about four seconds on my machine. The biggest problem I see is treating the log like a diary. It isn't. It's a technical record. You don't need to write what you felt when the SID chip finally produced a clean sawtooth wave. You write what register you changed, what value you tried, what happened, and what you suspect is wrong. Three sentences is enough. More than that and you're just padding the index with noise. Another common mistake: using different date formats across entries. The parser expects a consistent format. If you mix 12/03/2024 and 2024-03-12 into the same project, the sort order breaks. I learned this the hard way when I accidentally swapped my date format mid-project and spent an afternoon reordering five hundred entries by hand before writing a sed script to fix it.

The sed script was:

sed -i 's#^\([0-9]\{2\}\)/\([0-9]\{2\}\)/\([0-9]\{4\}\)#\3-\2-\1#' *.log

It runs in under a second and converts MM/DD/YYYY to YYYY-MM-DD across every file in the directory. I keep it in my bin folder now. Useful to have around. Logbook For Coding Vintage is not a version control system. It doesn't track diffs. It doesn't tell you what changed between March 12 and March 15. If you need that, use Git alongside it. The two tools complement each other because Git handles the code history and the logbook handles the context around why the code changed. It also doesn't handle large binaries well. If you're logging a project where the output is a 2 MB PRG file and you want to attach screenshots or captured tape images, the tool will choke on it. Keep attachments out of the log. Reference them by path instead. The parser ignores anything after a "see:" directive, so you can note file locations without breaking the index.

Another hard limit: the HTML output uses basic styling. If you open it on a phone, it's readable but cramped. If you want something that renders well on mobile, you'll need to write a custom template. The template system is simple enough that a weekend is all it takes, but the default output is desktop-first by design. I also found that Windows paths with backslashes caused issues in the early versions. The parser wasn't normalizing them properly. I added a path cleanup step that strips backslashes and replaces them with forward slashes before indexing. It's handled transparently now, but if you're running an older build, you might see broken links in the output. Update to the latest version if that happens to you.

When Not To Use It

If you're only working on one vintage machine and you write less than once a month, a simple text file is enough. The overhead of setting up the logbook structure isn't worth it. You'd be adding ceremony to something that doesn't need it. But if you juggle multiple systems, switch between emulators and real hardware, or come back to projects months later, the index is the difference between remembering what you did and spending three days rediscovering it. I've seen people lose weeks of work because they couldn't find the exact note about a clock cycle bug they'd solved in February. That's not a failure of memory. That's a failure of documentation, and the logbook prevents it.