💾 Archived View for geminiprotocol.net › history › phlog › link-syntax-finalised.gmi captured on 2024-05-12 at 15:19:26. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Gemini links finalised

(originally posted in Gopherspace on 2019-07-21)

Okay, I am back in the Gemini saddle. I don't have a huge amount of time to throw at the project for the next few weeks, but I'm going to do a little bit each day to start the ball rolling again and I still hope to have the core of the protocol pretty much finalised by the end of this month.

Before I went away, I was gnashing my teeth over whether the new => link syntax should be URL-initial or URL-final. I gave this a lot of thought during my recent travels, carefully considered the various arguments which have been made by various parties, and I think I'm finally ready to lock something in.

I have decided to reject as an invalid method for making this decision any kind of comparison to already existing markup languages. The reason for this is simply that there exist multiple languages implementing both orders. We are immediately forced to decide *which* language to copy. Choosing one on the basis of their relative popularity is totally invalid, because popularity is not any metric of quality (see also: the web). The decision should be made on the basis of practical principles which are relevant to Gemini specifically.

Tomasino has argued for link-first order on the basis that the URL is the more important part, in the sense that a URL alone will get you where you want to go but a human-friendly description alone will not. On an usually short screen/terminal, the first item is more likely to be displayed in full, while the second item might be truncated or split, so the URL should come first.

Tomasino's 2019-07-05 post discussing link syntax

Contra this, JFM/gcupc has argued for link-last order on the basis that human readers are more interested in the description and, in order to find it, they should not be forced to read past the URL, which might be long and strange-looking. Putting the human-readable text first makes things much more, well, human-readable.

Jason McBrayer's 2019-07-05 post discussing link syntax

I have decided that neither of these arguments are especially compelling, because they are both concerned with human beings reading raw geminimaps and that's an edge case, just like human beings reading raw gophermaps is an edge case. Using protocols like Gemini or gopher manually is a neat parlour trick, or perhaps a valuable MacGuyver survival technique to be used in desperate circumstances, but 99.9% of the time people are going to interact with Gemini servers via clients which will parse the maps behind the scenes and present things in a human-friendly manner. It doesn't make sense to optimise the format for rare parlour tricks.

Direct human eyeball processing of geminimaps should be more or less exclusively done by authors, not readers, and authors are much more likely be writing, editing and maintaining their own maps than simply reading random maps. It makes sense to optimise the format for this kind of work. And for this kind of work, I think the URL is the most important part. Typos in URLs should be easy to spot, as should be accidentally duplicated URLs in long lists of links due to careless copy and pasting, and other common gotchas.

So far I think everybody has spoken in favour of allowing arbitrary whitespace between the URL and the label, regardless of which order they are in. I'm onboard with this, so consider it locked in. This means that fastidious authors can use spaces or tabs as they like to produce beautifully aligned maps like this:

=> ShortFirstPart                               ShortSecondPart
=> ShortFirstPart                               QuiteABitLongerSecondPart
=> ReallyAParticularlyLongFirstPart             VShort2ndBit
=> MediumLengthFirstPart                        VShort2ndBit
=> ABC                                          TheLongestThingInThisEntireExampleSoFar

With this kind of care, both components are very easy to scan separately, so it really doesn't matter one bit whether URLs come first or last. But let's be honest with ourselves, people are much more likely to write this:

=> ShortFirstPart ShortSecondPart
=> ShortFirstPart QuiteABitLongerSecondPart
=> ReallyAParticularlyLongFirstPart VShort2ndBit
=> MediumLengthFirstPart VShort2ndBit
=> ABC TheLongestThingInThisEntireExampleSoFar

If URLs come last, this looks like:

=> ShortFirstPart gemini://zaibatsu.circumlunar.space
=> ShortFirstPart gemini://gemini.conman.org
=> ReallyAParticularlyLongFirstPart gemini://gemini.conman.org
=> MediumLengthFirstPart gopher://gopher.club/1/users/somebody/
=> ABC TheLongestThingInThisEntireExampleSoFar gopher://gopher.clib/1/users/somebody/phlog/

While if URLs come first, we get:

=> gemini://zaibatsu.circumlunar.space ShortSecondPart
=> gemini://gemini.conman.org QuiteABitLongerSecondPart
=> gemini://gemini.conman.org VShort2ndBit
=> gopher://gopher.club/1/users/somebody/ VShortSecondBit
=> gopher://gopher.clib/1/users/somebody/phlog/ TheLongestThingInThisEntireExampleSoFar

I think it's undeniable that in the second example, with URLs first, it's much easier to quickly scan down the list looking for a particular hostname, it's easier to spot that there are two consecutive links to gemini.conman.org, it's easier to spot that gopher.club has been mistyped as gopher.clib in the second example, and the internal structure of the gopher.club site is better highlighted because common subdirectories are aligned in consecutive links.

These are very important considerations for people maintaining their geminimap, who are ideally the only people who really have to get close and personal with the link syntax. A typo in the human friendly description might embarrass you or confuse your readers, but an error in the URL will break the link outright, which is far worse. URLs are more liable to change over time than labels. Consider all the people in the past few years who have migrated their phlogs from SDF or grex to newer, more reliable gopher hosts; you still want to link to "SoAndSo's Phlog", but the URL changes. Or the recent URL change for Bongusta, which you would still want to link to as "Bongusta (cool phlog aggregator)" or whatever even after the move. For gemini content authors, URLs are more important than the label. For gemini content readers it's definitely the other way around, but those people aren't looking at naked maps anyway.

So, I'm calling it: URLs come first, and Gemini links now officially look like this:

=> gemini://zaibatsu.circumlunar.space The Zaibatsu

(as a small bonus, I really like that this way, the arrow of the => is literally pointing at the location that the link points to. It's a nice little bit of iconicity in the syntax)

I quite like Tomasino's idea of the descriptive text being optional, so that the following is also valid:

=> gemini://zaibatsu.circumlunar.space

(a sensible thing for clients to do when encountering such a link is to just to use the URL itself as the description when presenting the link to the user)

So, let's allow that, too.

I'm sorry to everybody who was strongly in favour of URL-final syntax, but it was clear that I'd be apologising to some people either way, and after really giving this small detail an awful lot of careful thought I honestly think this is the best of the two choices. I really appreciate the interest and enthusiasm that everybody has shown in Gemini so far and I hope nobody is put off from continuing to follow the project because of this. At the end of the day, this is a small detail which anybody who uses the protocol regularly will stop even consciously noticing once they get used to it. Even if you think this detail is "wrong", I hope you'll agree that Gemini gets so much more important stuff right that it's still an improvement on the status quo.

I will be updating the speculative spec document and all my own Gemini software to be in line with this decision within the next 24 hours. Please update your own stuff at your earliest convenience!