Posts in category "Coding"

As Rogallo got close to being "stable", I did a fair bit of work on its documentation. Something that I wanted to include in the site was a good collection of up-to-date screenshots. These are all created on the fly. To do this, of course, requires something that looks like a Gemini server.

Initially, this was simple: Rogallo only supported Gemini capsules, so I could illustrate most things just using Gemtext files in the local filesystem (with an admonition in the documentation to point out that Rogallo was for more than viewing local files). This, of course, wasn't going to scale when I added Finger support, and neither was it going to work well for Gopher support.

The solution seemed obvious: use a lightweight local server for these protocols. With this need in place SmolServe was born. As mentioned when I released Rogallo v1.5.0, this isn't a project to build a comprehensive smolweb server. The aim is to build myself a minimal just-good-enough server that helps me with local testing and documentation.

As it stands, SmolServe supports Gemini, Gopher, Finger and Spartan. Or, rather, it supports a just-enough-to-get-by version of each of those protocols. None are implemented in a way that would serve as a "production" server; they're implemented to allow me to generate screenshots for the Rogallo documentation, involving any of the supported protocols, without the need to rely on services I don't control and which aren't local.

The big benefit of SmolServe is the exec support. With this, you can run up the server and then have it run another command. Once that command finishes its work, SmolServe will close down too. This means that, when it comes to producing the Rogallo documentation, I can just have the server running when I need it. Pulling some snippets from the Rogallo Makefile:

run      := uv run
smol     := $(run) smolserve --config $(docs)server/smolserve.toml
smolexec := $(smol) exec --
mkdocs   := $(smolexec) mkdocs

##############################################################################
# Documentation.
.PHONY: docs
docs:
    $(mkdocs) build

.PHONY: rtfm
rtfm:
    $(mkdocs) serve --livereload

.PHONY: publishdocs
publishdocs: clean-docs
    $(mkdocs) gh-deploy

The idea is that, when I build the documentation, I actually run smolserve, which in turn runs mkdocs, which then produces the documentation while the local server is available.

I also use this sort of approach for local testing of the content of my capsule that lives over on tilde.team.

.PHONY: view
view:
    uv run smolserve --config smolserve.toml exec rogallo open gemini://localhost/

My aim now is that, if I add any other protocols to Rogallo, I'll add a just-good-enough version of them to SmolServe to help me with testing and documentation. For the moment, though, I think it's in a stable and usable state.

Rogallo v1.6.0 is now available. This release concentrates on the addition of a newly-supported protocol, and improving what can be displayed in the viewer and how it looks.

The headline change is the addition of support for the Spartan protocol. Having run into a couple of sites that either offered this as an alternative access method to their content, or the only access method, and noticing its vague similarity to Gemini (and also its reliance on Gemtext as the main hypertext language), it seemed like an obvious feature to add. So, having built a library to handle the low-level details, I got to adding support for this to Rogallo.

Anyone using Rogallo should find that spartan:// URIs are handled in just the same way as gemini:// URIs are, so following them from within documents, or entering them into the command line all works. On top of this, Rogallo now supports Spartan's =: line type in documents served from a Spartan server. This means that this form of input is now supported.

So, just to recap, at this point, Rogallo supports 4 different protocols.

• Finger
• Gemini
• Gopher
• Spartan

I suspect this won't be the last of them, but I sense I'm close to adding the most useful ones.

The two other changes in this release are closely related. Rogallo has always handed off any MIME types that it can't directly handle, and the types it could handle were set to a very narrow collection -- Gemtext, Gopher maps and plain text, pretty much. With this release the list has been expanded to anything text/*. Working on the (pretty safe) assumption that any text/ MIME type can be displayed as text, this seemed like a sensible switch to make.

Working in conjunction with this, Rogallo will now also attempt to infer what kind of text is being shown, and apply some syntax highlighting where appropriate. So, for example, if you visit a text file that is Python code, it will be highlighted as Python code (if the server tells us that we're looking at Python code).

One final change in this release is a small fix to Gopher support. Rogallo lets you configure a connection timeout value, but this wasn't being used for Gopher support. This is now fixed.

After a short break to do some fossil hunting, I'm back tinkering with Rogallo. The main change in v1.5.0 is the addition of support for custom themes.

Before I get to that though, there's a small number of other fixes, additions and tweaks. The first is a small change to the Gopher support. As of this version, if there's a type 8 item in a Gopher menu, it will now be turned into a telnet:// URI rather than being left as a gopher:// URI. This should help in handing off such an item to the correct application in your environment.

I've also added a new command: PipeDocument. This is bound to Ctrl+Shift+p by default. If you're viewing a document and run this command, you'll be prompted for a shell command that the source of the document will be piped through. This could be useful for transforming the source and passing it on elsewhere. For example:

One small fix in this release is the correction of a typo in the code that resulted in a misspelled item in the configuration file. The bookmarks_visble configuration setting has been changed to bookmarks_visible (the spelling of visible was wrong). Technically this is a breaking change but, because the impact is almost zero, I'm running with it. The worst possible outcome after installing v1.5.0 is that the bookmarks aren't showing in the sidebar when they were before; calling them back up will fix the issue.

Now on to the main change: custom themes. Rogallo has always had theme support, and the themes that were made available were most of the themes built into Textual. There was a request to be able to create additional themes, and so, here's that feature. Using this, if you want to have Rogallo look just so, you can now follow the documentation, or look over the examples, and have a play. So if you fancied a version of Rogallo that looked like it was running on a good old green terminal:

Or perhaps an amber terminal is more your thing?

Maybe you hanker after the days of MS-DOS and those Turbo IDEs?

Even better: perhaps the CBM64 was your thing back in the day?

Note that none of these themes are part of Rogallo itself, and don't ship with it; they're just examples of what you could do if you wished. I don't even offer them as good examples of what you could do (for example: I can see that I've managed to end up with the jump labels being far too dim to be readable). I'm sure other people with more talent for design than I have will be able to do far better. If anyone wants to make their own themes and share them, I've created a spot just for that.

One last thing: while it's not a feature of this version of Rogallo, I've also done some work on the site to try and add a little more detail about using Rogallo. This process will be ongoing. The main additions here are some background on the supported protocols and some help on the key UI elements.

The documentation is also greatly improved with better examples thanks to smolserve -- this is a little helper project I've been tinkering with. Note that this is not and will never be intended to be an actual small web server; it is and always will be a tool to help development and to support the production of Rogallo's documentation.

I've updated Rogallo to v1.4.0. The main change in this release is to how server certificates are handled, which in turn should solve a bit of friction Rogallo had when using some popular Gemini capsules.

Until now, Rogallo simply used a TOFU approach for all capsules it encountered. In part, this was because that's all I'd really read about until that point, and also in part because, as Rogallo became more capable and I started to use it as my daily-driver, it just worked. Then, within the space of about a week, I had two popular capsules apparently change their fingerprint. I wasn't expecting that so soon (hence one issue about dealing with this still needing to be worked on).

With this in mind, I made a note about this, and carried on. When someone else also noticed the fingerprint change for AstroBotany, this made me want to try and actually sort this out. And so here's v1.4.0, which I think will (if I've understood things correctly) address the problem and make the journey a lot smoother.

From this version, Rogallo uses a kind of "hybrid" approach to validating the certificate of a capsule. Simply put, here's how it goes:

• Can we check with a certificate authority? If so, perform that check and raise an error if there's a problem.
• If, on the other hand, the certificate is self-signed, use the TOFU route.

To help keep an eye on this approach, and because it's just generally handy to know, I've added a small new element to the UI of Rogallo: a verification badge. This can be seen up in the top-left corner of the viewer. It has three states:

• It will show ⛉ if we're visiting a capsule that was validated using a CA
• It will show ✓ if we're visiting a capsule that was validated using TOFU
• It will show no icon if we're visiting a location where this isn't applicable

This is alongside the already-existing ⚿ icon that is shown if we're making use of a client certificate.

While I've not documented them yet (I need to do a round of website updates), each of these icons can be changed if you prefer something different. Just take a look in the configuration.json file for Rogallo.

    "client_certificate_used_icon": "\u26bf",
    "verified_ca_icon": "\u26c9",
    "verified_tofu_icon": "\u2713",
    "verified_off_icon": "\u2717",
    "verified_none_icon": " ",

Note that under normal circumstances the off icon there should never be needed or seen. That's just more for testing.

All of this ends up looking something like this:

To help test and keep an eye on this, I've also added a new command to Rogallo: AboutThisPage, bound to F7 by default. With it you can check on some information about the current page, and also the certificate that was checked when acquiring it.

Note that if a page is loaded from cache you won't see certificate information in this dialog, as that isn't (currently) recorded in the metadata in the cache. I might do that at some point in the future, but it didn't seem necessary for now.

Rogallo has been updated to v1.3.0. This release adds an extra cosmetic feature to the Gopher support, and also extends what the internal command line is capable of.

Both of the changes come from suggestions made by -fab-, who's been an avid tester of Rogallo and a good source of pointers and ideas. The first change comes from a mention they made of how some Gopher clients will prefix links in a map with a three-letter ID to give a clue as to what the linked resource is. TXT for a text file, SND for any audio file, MNU for a link to a further map, that sort of thing. While I didn't add that when I initially added Gopher support, it did seem like a useful option to provide.

However, this being a "modern" TUI application, with access to a wee bit more than plain old ASCII, I thought I'd mix it up a little. By default, little "icons" or "badges" are shown with each link. So to take the examples given above, I'm using 📄 for a text file, 🎵 for an audio file, and 📁 for a menu.

Of course, some people might not want this, and this can be turned off entirely in the configuration file by setting gopher_show_type_badges to false. However, it might be that someone wants this, but not the emoji. That's where gopher_type_badges comes in. This is an association of Gopher types with text to use as the "badge". If three-letter all-ASCII "badges" are what you want:

"gopher_type_badges": {
    "0": "(TXT)",
    "1": "(DIR)",
    "2": "(CSO)",
    "3": "(ERR)",
    "4": "(HQX)",
    "5": "(DOS)",
    "6": "(UUE)",
    "7": "(FND)",
    "8": "(TEL)",
    "9": "(BIN)",
    "i": "(INF)",
    "g": "(GIF)",
    "I": "(IMG)",
    "h": "(WEB)",
    "d": "(DOC)",
    "s": "(SND)",
    "P": "(PDF)",
    "X": "(XML)",
    "unknown": "(???)"
}

The other feature springs from another suggestion -fab- made. This time it was the idea of adding direct command-line support for Gemini and Gopher search engines. This struck me as an excellent idea, but I got to thinking that it could be a little more generic than that. So I've added support for declaring simple command-line aliases. There's now a section in the configuration file¹ called aliases. It's an association of a command alias and an expansion. The alias itself must be a single "word" of characters, and the expansion the actual command that will be used. It can be any other command-line command, or a URI. Anything that the command line can normally handle.

When the user types something into the command line, the input will be split on the first space. If the first half matches an alias, it will be substituted for the input, and the tail of the input will be made available as a parameter to the expansion.

There are three placeholders that do the expansion:

• {q} -- The tail of the command quoted for use in a URI
• {qp} -- As above, but spaces will be + rather than %20
• {r} -- The raw, unquoted, tail of the command

I've probably done a bad job of explaining it. But hopefully the following default set of aliases will nicely illustrate it:

"aliases": {
    "fg": "gopher://gopher.floodgap.com/1/v2/vs?{q}",
    "gp": "gemini://gemi.dev/cgi-bin/wp.cgi/search?{q}",
    "ken": "gemini://kennedy.gemi.dev/search?{q}",
    "tlgs": "gemini://tlgs.one/search?{q}"
}

Given this, if you type ken test search, the actual command that gets input is gemini://kennedy.gemi.dev/search?test%20search. As I said, it's not just about search engines; you can also expand to other built-in commands. For example:

"whois": "!finger {r}"

Would have whois davep@plan.cat expand to !finger davep@plan.cat.

I feel this nicely solves the original request and adds an extra layer of utility to the internal command line.

Rogallo v1.2.0 is now available. The main change in this release is the kick-off of support for the Gopher protocol.

As I've mentioned before: Gopher is kind of an unknown to me, in terms of actually using it. I'm aware of it, I've known about it ever since I first got on the Internet back in the 1990s, I have a half-recalled memory of dabbling with a Gopher client at some point back then, but I had no conscious knowledge of its workings. So, when I say "kick-off" above, I say it because I suspect there's going to be more work to do to make it work "just so".

However, right now, gopher:// URIs are supported in Rogallo.

The approach to supporting this is pretty simple: given a gophermap, as pulled from a server, Rogallo converts it into Gemtext and then displays it using the normal Gemtext viewer.

There is more to Gopher than just displaying the maps, of course: there's access to all kinds of resources. Where possible, Rogallo will display text-based resources within the viewer; all other kinds of resources are handed off to the operating system as they probably need applications and tools that Rogallo doesn't offer (viewing images, playing audio, etc).

Searches (item type 7) are supported, and when following such a link, you will be prompted for input, which will be used as the query.

Note that, for the moment, there is no support for extensions to the protocol such as Gopher+. Doubtless I'll look into doing something with this in the future; Rogallo's development is incremental and for me it's all about having fun (re)discovering new/old things.

There are two other notable changes in Rogallo v1.2.0:

• I've modified the ordering of entries in the history search so that the items appear in most to least recent order. While being able to type in things to find back a location is the primary use, I also found I was often pulling it up to find something I'd visited very recently.
• I fixed the "view source" status being sticky during navigation. If I was viewing the source of a location, and then navigated to another location (by using the Back command, for example), that other location would also show the source. The status is now reset every time you navigate to somewhere else.

That's it for this release. There's still a good few things on the TODO list so I'll be tinkering and enhancing for some time to come. As always, questions or suggestions are very welcome.

I've just made a small bug-fix release for Rogallo. v1.1.1 fixes two (mostly) cosmetic issues that were reported by a user. From the ChangeLog:

• Fixed cosy_link_jumps not being loaded from configuration when Rogallo starts up. (#230)
• Fixed viewer status line being lost when maximum_document_width is set to something other than 0. (#231)

Thanks to fab¹ for alerting me to these issues.

One other small change in this release is that the version of Port79 is included in the output from the diagnostics CLI command.

Rogallo v1.1.0 is now available. This release includes a number of new features and improvements, plus a small cosmetic fix.

Diagnostics¶

On the off chance that someone else does use Rogallo, and needs help getting to the bottom of some sort of issue, I thought it might be useful to add a diagnostics command to the CLI. Right now it's pretty simple, just dumping some version and environment information.

$ rogallo diagnostics
# Libraries
bagofstuff: 1.2.1
cryptography: 49.0.0
gemtext: 1.0.0
rogallo: 1.1.0
textual: 8.2.8
textual_enhanced: 1.6.0
textual_fspicker: 1.0.1
wasat: 1.0.1

# Python
Compiler: Clang 17.0.0 (clang-1700.3.19.1)
Executable: /Users/davep/.local/share/uv/tools/rogallo/bin/python3
Implementation: CPython
Version: 3.14.0

# System
Name: Darwin
Release: 25.5.0
Version: Darwin Kernel Version 25.5.0: Mon Apr 27 20:40:51 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T8112

# Terminal
Detected: ghostty

Finger protocol support¶

This was something I was interested in adding, and a couple of people have already requested it, so Rogallo now has finger support. This has been added in a couple of ways. The first and most obvious is that finger: URIs are now natively supported in Gemtext content. So now if you follow a finger:// link you'll see the response in Rogallo itself.

The other method is to use the new !finger command that has been added to the application's command line.

Of course, in the command line, you can also just enter a finger:// URI if you wish, which I guess is a third way of doing it.

Finger URIs are recorded in the history, and can also be bookmarked.

Using an external editor for user input¶

This was also something I was keen on doing, and then someone else happened to ask for it: support for swapping out to an external editor for writing user input. While the current mechanism is fine for entering a one-liner -- or composing a very short message -- a proper editor (for me that's ideally one with the ability to check spellings) is generally going to be far more useful for a longer body of text. So, with this in mind, the internal editor can now optionally swap out to your text editor of choice.

If you have either VISUAL or EDITOR set in your environment (VISUAL beats EDITOR), Rogallo will let you swap to it by pressing F3 in the internal editor. You can also override that choice by setting external_editor in the configuration file.

Personally, I'm finding this is working really well with emacsclient. From now on, I'm going to find writing content in Geminispace a lot easier.

Blended pre-formatted text¶

Now that I've been wandering around Geminispace some more, I've noticed that a common use of pre-formatted text is for logos, ASCII art, that sort of thing. Generally, the sort of things that are best presented with the background the same as the surrounding text. A different shade of background is fine if showing code and stuff, but I feel that this:

looks better than this:

To this end, I've modified the pre-formatted text rendering so that, by default, if pre-formatted text has no alt-text, the background is the same as the surrounding text. On the other hand, if it does have alt-text (and so is likely the name of a programming language, which implies syntax highlighting, which in turn implies you want it to stand out), it isn't blended with the rest of the text.

If your preferences differ from mine, you can control this with the new blend_pre_formatted_with_background configuration file setting. It takes a list of alt-text strings that should be blended. By default it looks like this:

    "blend_pre_formatted_with_background": [
        "",
    ]

That is, by default, it only blends empty alt-text pre-formatted text. As it happens, Station uses alt-text for the logo and the user image, but I'd like them blended in too, so I'm running with this:

    "blend_pre_formatted_with_background": [
        "",
        "Station logo",
        "User image"
    ]

Doubtless I'll add others as I run into them.

Fixed mouse hover effect¶

The last change is a small cosmetic fix to mouse interaction with links. When the mouse cursor is over a link, there should be a hover effect (that is, the background should change colour). This wasn't working if you had link stripes turned on. This is now fixed.

Thirty-three days ago, back on the 18th of June, I created a development directory called rogallo, and started adding dependencies and laying out the main user interface of Rogallo. It's been tons of fun working on it while exploring Geminispace. Given that it's quickly turned into my daily driver, and I'm finding it stable, I've decided it's time to drag it out of the 0verse and consider it worthy of being v1.0.0.

I was going to hold off a little longer, mainly because I wanted to flesh out the documentation some more, but that seems like a poor reason to keep it stuck somewhere in v0.x.

To recap, for anyone who might not have followed the development so far: Rogallo is a terminal-based client for the Gemini Protocol. I've built it for my own education. I've built it for fun. I've built it because I want to use it. I've built it hoping that someone else might enjoy it too. Some of the key features, as of this first "stable" release, are:

• Keyboard-first TUI interface with good mouse support too.
• Bookmark support.
• Forward/backward navigation.
• Location history.
• Home page.
• Designed to work on macOS, GNU/Linux and Windows.
• Trust-on-first-use support.
• In-application creation of client-side certificates.
• Full support for user input, both normal and sensitive.
• Full support for redirections.
• Context-sensitive help screens.
• All main application commands available via a command palette or an in-application command line.
• Themes.
• Responsive layout that dynamically adjusts to terminal resizing.
• Support for viewing Gemtext files in the local file system.
• View source support.
• Copy-to-clipboard support for URIs or page content.
• Optionally-numbered links with quick-jump support.
• Supports ANSI escape sequences in content.
• Supports filtering out ANSI escape sequences.
• Emoji filter (lets you remove emojis from most text).
• Support for handing off unsupported content to the operating system (with safety checks).

Probably some other stuff I've forgotten right now.

On top of this, there's more to come. v1.0.0 isn't the end of the line with Rogallo. I'm having plenty of fun using it, and improving it, and there's more I want to add. I very much want to add in-app support for the Finger Protocol, and I can see myself falling down the Gopher rabbit-hole¹ at some point too. While I don't want the application to grow out of hand, I can see plenty of extensions and enhancements that will be satisfying to add.

If any of this sounds interesting and you want to have a play, Rogallo is licensed GPL-3.0 and available via GitHub and also via PyPI. If you have an environment that has pipx installed, you should be able to get up and running with (note that Python 3.12 or later is required):

pipx install rogallo

It can also be installed using uv:

uv tool install rogallo

If you don't have uv installed, you can use uvx.sh to perform the installation. For GNU/Linux, macOS, or similar:

curl -LsSf uvx.sh/rogallo/install.sh | sh

or on Windows:

powershell -ExecutionPolicy ByPass -c "irm https://uvx.sh/rogallo/install.ps1 | iex"

Once installed, run the rogallo command.

I've bumped Rogallo to v0.12.0.

The first change is a simple addition of a !theme command to the command line. As much as possible, I've tried to make sure that every command that's in the command palette can also be run from the in-app command line, but I'd managed to leave this one out. Now you can type !theme and get the theme picker.

Next is the addition of an OpenFile command, bound to Ctrl+o by default. This opens a dialog for browsing the filesystem, allowing for easy access to local gemtext files.

Related to this, if you now enter the name of a directory in the command line, the same dialog will open, starting at that directory. Both these changes should make finding local gemtext files a smoother experience.

Another change is to the way that the recently added emoji removal works. I decided that it was a little too aggressive, in that it shouldn't remove them from the content of pre-formatted text. In my experience in Geminispace, so far, pre-formatted text is where the more creative displays happen. Indeed, I had a go at this myself for my new page:

Here I've used ANSI escape sequences and half-block characters to recreate my usual avatar. The problem is: the emoji-removal approach I've used sees the half-blocks as something to remove. The result isn't great.

Given that the unwanted emojis will generally be those in body text, links, quotes and headers, I've tweaked the way that pre-formatted text is shown, with it not having emojis removed. I feel this is a sensible approach.

I guess, if anyone really objects to this, I could add a configuration switch that dictates how aggressive the removal is.

The final change is something I wasn't really ever planning on doing, and I felt I'd removed the need for it when I added link stripes. But I got a request to do it and, really, the cost of doing it is nothing. The request? An option to move the link jump labels over to the left.

So now there's a ToggleCosyLinkNumbers command (bound to Super+F8 by default¹) which does what it says:

Personally, I prefer them on the right, where they don't disrupt the left-aligned margin for all the text, but I can see why this would be far more comfortable for others, so... why the heck not?