Tables in Gemtext, the non-hacky way

2023-06-30 | #tables #gemtext | @Acidus

There is a lot to unpack in @freezr's recent post about 4 years of Gemini. However something that I felt compelled to write about was their suggestion to add table syntax to gemtext.

Four years of Gemini… And so what?

Specifically:

> Basic table management through client. Tables are difficult to make fluid but are annoying to write manually, so we can stick with the verbatim line, but we can ask the clients to format the text for us.

They then propose a domain specific language to overload a preformatted line with extra meta data to tell the client how to render a table

Please don't do this. Here is why:

It's way too primitive...

First of all, it's a very naive system. It covers only the most primitive use case.

Tables are something that, at first glance, seem really easy, but need to be incredibly flexible. Here are just a few use cases that @freezr's approach won't handle.

Cell alignment? It's common to right align numbers, but left align or center align text

Cell padding? Padding between cells and values is important for readable tables

Wrapping cell contents? How do you determine where to wrap long lines of text in a cell? What about cell values that don't have spaces and need to be hyphenated? What happens if it's just a number that you *can't* hyphenate?

Borders? What characters should be used to contain the table? ASCII, Unicode box characters, etc? A mix?

Row or column spans? How do you define table cells that span multiple rows or columns?

None of this is supported by @freezr proposal. They do however have an option to denote a header row at the top of the table, or to have headers on both the top row *and* left side column. But strangely not a way to have a header on the left side column.

Their suggestion for more advanced uses cases is:

> "In case to render more complex case the use of a CSV files can be an alternative"

😮 🤮

... and yet radically complicates clients

Let's see where this proposal breaks down in even the most trivial example. Here is a table using @freezr's syntax

Pretend you are a client. How wide should the first column be? The text "Food", "Apple", and "Rice" and all short. But "Raspberry Cheesecake Crumble" is super long. A naive rendering might look like this:

Before a client could render the first line of the table, it would need to first know that the first column needs to be 30 characters wide to fit everything. But the client won't know this until it reads the 5th line of the table definition and sees the cell value "Raspberry Cheesecake Crumble."

This requires "state." Whenever a "table line" is encountered, a client would need to read the entire preformatted blob. It would then need to figure out how wide to make each column. It would then need to figure out where to wrap columns. There is tons of complexity here.

Aside: What do web browsers do?

Readers may have noticed that the issue I describe isn't unique to tables in gemtext. Web browsers, when encountering a <TABLE> tag, have the exact same issue: How does the browser know what width to draw the table columns? Guess what? It doesn't know! Instead it draws what makes sense, and as it encounters new rows with cells that require a change to the width, it redraws the table.

If you watch a web browser rendering a very large table, you'll see it redraw the entire table as it encounters different cells of different lengths. In some cases, large tables will actually cause a browser to freeze rendering. The difference is that Web browsers can handle this because they have the flexibility to "go back" and redraw something.

Gemtext is Line Oriented

Gemini clients, on the other hand, render 1 line at a time, as those lines are read. They can't/don't "go back" to a previous line and redraw it. That concept is completely foreign to how Gemini client's are written, because it breaks the fundamental concept of Gemtext's "line oriented" design. With @freezr's proposal, clients can no longer just render a line, how that line is rendered is now based on the contents of other lines. This breaks gemtext's line oriented concept and adds a ton of complexity to the clients.

(Aside: Technically, the "preformatted" line type has state as well. It toggles fixed-width rendering or not. However this is totally optional, and can be implemented as a single boolean by a client. Regardless, I'd say its the exception that proves the line oriented Gemtext rule.)

🔥 Burn baby burn 🔥

So how do we add tables to a gemtext document? Simple. Don't have the client interpret a domain-specific language to render a table. Instead, *YOU* render the table however you want, and "burn" that into the gemtext by just putting it in a preformatted text section, like this:

This way, you are free to handle tables however you want. Cell alignment, special formatting for headers, visually pleasing text wrapping, whatever. So I could render that same table above, and burn it into gemtext like this instead:

Or like this:

Or even like this:

Whenever I've written gemtext that has tables, like the WAREZ ebook, or many pages of the Apple II History project (both found on the root of this capsule), I've burned the tables into the gemtext.

But that's a lot of work!

Is it? I created those tables above by hand. If it's a real issue, you can just use a program. Do you really think "how do I generate a table in text" is a problem no one has had in the last 50 years of command line computing? Of course not, there are plenty of "CSV to ASCII table"-style command line programs out there that can do it for you. Why would we expect the client to do it for us?

But clients should control how things are rendered!

Sure, this is mostly true. How header lines, link lines, and list lines look is controlled by the client. And I think this is actually a strength of Gemtext.

However, we don't expect Gemini clients to control how our ASCII art is rendered. We don't define ASCII art using LOGO or some domain specific language and let the client render it. Instead authors create ASCII art however they want, and burn it into the gemtext by including it between preformatted lines. Why would we treat tables any differently?

"But... what if we could?"

"What if we could?" from "The Core" (Animated GIF)

To be clear: WE SHOULD NOT DO THIS!

But...

... if I *had* to include a table in gemtext...

I wouldn't create a new domain specific language to define a table, where I would just have to speed run all the lessons and evolution of the <TABLE> tag and all its attributes and child tags to support complex tables. I would just put TABLE HTML into the gemtext like this:

And then let clients render it if they support it. Other clients can just ignore it and render it as plain text.

In fact... if you held a gun to my head and asked me to design a generic system to embed resources into gemtext, which wouldn't violate Gemini's philosophy of "1 request per resource, only make requests triggered by explicit user action", I would do something like this:

Clients could choose to render that LaTeX math formula, or that HTML table, or colorize that C source code. Or not.

Luckily, we don't need to think about that, because I'm definitely not proposing that 🙈

Summary

We don't need to complicate clients by asking them to render tables:

1. It breaks the line oriented philosophy of gemtext.

2. It complicates writing clients

3. The majority of clients won't implement it anyway

4. You'll just have to include the table content another way so people can see it, making this whole thing moot anyway.

Convert the table to text and burn it in between preformatted lines and you are good to go.

(And see what I did there to make an ordered list? BOOM! Another thing @freezr brought up that you really don't need to worry about. Client could detect that pattern if they really want to and render it in a special way, just like how clients like Lagrange detect link lines whose link text starts with an emoji and render it in a special way.)