Stefan Lesser in 2023 (paraphrased): Building helps understand ourselves through the world, and understand the world through ourselves.

Me now: Building things is easy. Evaluating what you build is hard. It requires lots of attention. Therefore, build things that you want to pay lots of attention to. ]]> http://akkartik.name/post/luaML2 29 Mar 2025 12:03:28 PDT http://akkartik.name/post/luaML2 Here's a document containing a line of text:

{type='text', data={'hello, world'}}

I'm building in Lua, so I'm reusing Lua syntax. Here's how it looks:

Such text boxes are the workhorse of this markup language. There are 3 other kinds of boxes: rows, cols and filler. Rows and cols can nest other boxes. But let's focus on text boxes for a bit.

Here's a text box containing two lines of text:

{type='text', data={ 'hello', 'world'}}

Since it's hypertext, you get a few attributes. You can set color, bg (background color) and border (also color). Each of these is a Lua array of 3 or 4 elements for red, green, blue and transparency.

{type='text', data={'hello, world'}, bg={1,0.6,0.4}, border={0,0,0}, color={0,0.2,0.8}}

Notice that the text is not centered vertically. The browser doesn't know details about the font like how far down the baseline is. You have to center manually using line_height.

{type='text', data={'hello, world'}, bg={1,0.6,0.4}, border={0,0,0}, color={0,0.2,0.8}, line_height=25}

I imagine this sort of thing will get old fast. Probably best to use bg and border sparingly.

Since this is a hypertext browser, the main attribute of course is hyperlinks. To turn a text box into a link you can click on, use the target attribute.

{type='text', data={'hello, world'}, target='x'}

Links get some default colors if you don't override them. The target is a file path that will open when you click on it; there's no networking here. Press alt+left to go back.

What else. The one remaining attribute text boxes support is font. You can use any font as long as it's Vera Sans (or you're welcome to open up my program and put more fonts in). But you can adjust the font size and select bold and italic faces. However, before we can see them in action I should discuss inline styles.

A text box contains lines. Each line so far has been a string. But it can also be a string augmented with attributes. Here's a line with an inline 'tag':

{type='text', data={ {'hello, style1@{world}', attrs={ style1={font={italic=true}}, }}, }}

(So many irritating silly curly brackets! But I hope you'll stick with me here. The goal is a simple markup language that is easy to implement while still providing some basic graphical niceties.)

Inline segments of text are surrounded in @{...} and prefixed with an alphanumeric name. (So they have to begin at the start of a word, after whitespace or punctuation.) The name gets connected up with attributes inside a block called attrs.

To stretch our legs, here's a text box with two lines, each containing inline markup for font and color.

{type='text', data={ {'hello, style1@{world}', attrs={ style1={font={italic=true}}, }}, {'style1@{hello}, style2@{world}', attrs={ style1={font={bold=true}, color={1,0,0}}, style2={font={italic=true}, bg={1,0,1}}, }}, }}

Each line's attributes are independent. So far you can't change font size or add borders inline, because it complicates matters to change line height within a line, and also seldom looks nice.

Inline attrs should arguably be used sparingly. The pattern I've been using more is to give each text block a uniform font and mix and match combinations of text boxes. There are 2 ways to combine text boxes: rows and cols. Here's a vertical array of text boxes:

{type='rows', data={ {type='text', data={'hello, world'}}, {type='text', data={'goodbye, cruel world'}}, }}

And here's a horizontal array:

{type='cols', data={ {type='text', data={'hello, world'}}, {type='text', data={'goodbye, cruel world'}}, }}

It's hard to see, so let's make the border more obvious. You can add attributes to rows and cols just like to text.

{type='cols', bg={0.8,0.8,1}, data={ {type='text', bg={1,0.8,0.8}, data={'hello, world'}}, {type='text', data={'goodbye, cruel world'}}, }}

All children of rows share a width, and all children of cols share a height. Children can also share other attributes when specified in a default attribute:

{type='rows', default={color={0.8,0,0}}, data={ {type='text', data={'hello, world'}}, {type='text', data={'goodbye, cruel world'}}, }}

Widths and heights will grow and shrink depending on what you put in them, but you can also fix a width in rows and text boxes, and lines will wrap as needed.

{type='rows', width=200, data={ {type='text', data={ 'This is a long sentence.'}}, {type='text', data={ 'This is a second long sentence.'}}, }}

Notice that it'll try to wrap at word boundaries if it can. But it'll chop mid-word if a line would be too empty without the entire word.

For completeness, here's a filler box. All it does is add padding within rows and cols. Within rows, filler needs to specify a height, and within cols, a width. The other dimension will resize as needed.

{type='rows', default={color={0.8,0,0}}, data={ {type='text', data={'hello, world'}}, {type='filler', height=50}, {type='text', data={'goodbye, cruel world'}}, }}

Putting it all together, here's a table:

{type='rows', border={0,0,0}, default={border={1,1,1}}, data={ {type='cols', default={ font={size=21, bold=true}}, data={ {type='text', data={'widgets'}}, {type='text', data={'quantity'}}}}, {type='cols', data={ {type='text', data={'foo'}}, {type='text', data={'34'}}}}, {type='cols', data={ {type='text', data={'bar'}}, {type='text', data={'7'}}}}, }}

No wait, that's not right:

{type='cols', border={0,0,0}, default={border={1,1,1}}, data={ {type='rows', data={ {type='text', font={bold=true}, data={'widgets'}}, {type='text', data={'foo'}}, {type='text', data={'bar'}}}}, {type='rows', data={ {type='text', font={bold=true}, data={'quantity'}}, {type='text', data={'34'}}, {type='text', data={'7'}}}}, }}

That's annoying! You have to specify columns before rows, or you're stuck manually sizing widths. But, 600 lines of code! Here it is. You'll need LÖVE, but the code should be easy to port to other graphics toolkits, the markup to JSON literals, etc. The program is a zip file containing the source code. ]]> http://akkartik.name/post/debugUIs 31 Jan 2025 09:06:44 PST http://akkartik.name/post/debugUIs Sorry, this article is too wide for my current website design so you'll need to go to it →

]]> http://akkartik.name/post/programming-2024 31 Jul 2024 11:52:44 PDT http://akkartik.name/post/programming-2024 I talk a lot here about using computers freely, how to select programs to use, how to decide if a program is trustworthy infrastructure one can safely depend on in the long term. I also spend my time building such infrastructure, because there isn't a lot of it out there. As I do so, I'm always acutely aware that I'm just not very good at it. At best I can claim I try to compensate for limited means with good, transparent intentions.

I just spent a month of my free time, off and on, rewriting the core of a program I've been using and incrementally modifying for 2 years. I've been becalmed since. Partly this is the regular cadence of my subconscious reflecting on what just happened, what I learned from it, taking some time to decide where to go next. But I'm also growing aware this time of a broader arc in my life:

• Back in 2015 I was suspicious of abstractions and big on tests and version control. Code seemed awash in bad abstractions, while tests and versions seemed like the key advances of the 2000s. I thought our troubles stemmed from bad incentives, using abstractions too much, and not using tests and versions enough. Mu1 was an attempt at designing a platform with tests and layers (more like versions, less like abstractions) as foundational constraints influencing everything else.

• In 2017 I started reworking Mu1 into the current Mu. At the start I used all my new ideas for tests and layers. But over time I stopped using them. Mu today has tons of tests, but they are conventional tests, and I never got around to porting over my infrastructure for layers.

• In 2022 I started working on Freewheeling Apps. I started out with no tests, got frustrated at some point and wrote thorough tests for a core piece, the text editor. But I struggled to find ways to test the rest, and also found I was getting by fine anyway.

• Now it's 2024, and a month ago I deleted all my tests. I also started radically reworking my text editor, in a way that would have made me worried about merge conflicts with other Freewheeling Apps. In effect I stopped thinking about version control. Giving up tests and versions, I ended up with a much better program. The cognitive dissonance is now impossible to ignore.

After mulling it over for a few days, I think my current synthesis on programming durable things is:

1. Building durably for lots of people is too hard, just don't even try. Be ruled by what you know well, who you know well and Dunbar's number.
2. Most software out there is incurably infected by incentives to serve lots of people in the short term. Focus as far as possible on software without lots of logos on the website, stuff that is easy to build, has few dependencies, definitely doesn't auto-update. Once you filter by these restrictions, the amount of durable software humanity has created so far is tiny.
3. Small changes in context (people/places/features you want to support) often radically change how well a program fits its context. Our dominant milieu of short-termism doesn't prepare us for this fact.
4. Given this tiny body of past work and low coverage per program, any new program you decide to build is quite likely striking out into the unknown in some way or other. You often won't know quite what you're doing in some direction or other. (In my example above, I was trying to insert special "drawing lines" in a text editor. Questions that raised: can the cursor lie on a drawing? Can I try to draw in one line while the cursor is on another? Drawings are taller than text lines. Can a drawing be partially visible at top of screen? Can I draw on a partially visible drawing? My answers to these questions were sub-optimal for a long time, leading to hacks piled on hacks.)
5. Types, abstractions, tests, versions, state machines, immutability, formal analysis, all these are tools available to us in unfamiliar terrain. Use them to taste.
6. You'll inevitably end up over-using some of these tools, the ones you gravitate towards. The ideal quantity to use these tools is tiny, much more miniscule than any of us is trained to think by our dominant milieu of short-termism. The excess is tech debt. It keeps us from noticing that a program is unnecessarily complex, less durable than it could be, harder to change when the context shifts.
7. When your understanding of the context stabilizes, there's value in throwing away vast swathes of a program, and redoing it from scratch.
8. Before you set out to rewrite, you have to spend some time importing everything into your brain at once. Everything you want from the program, all the scenarios the program has to cater to. This is hard. The goal is to get to a point where you can build everything all at once.
9. Build everything all at once.

In my case, tests and versions actively hindered getting to the end of this evolution. Tests let me forget concerns. Version control kept me attached to the past. Both were counter-productive. It took a major reorientation to let go of them.

All the software I've written in my life — and all my Freewheeling Apps so far — are at level 6 in this trajectory. Only the output of the past month feels like it might have gotten to level 9. We'll see.

It seems likely that a program can grow so complex it becomes impossible to import into memory in level 8. That seems to describe most software so far, certainly most software written by more than a couple of people. Even my text editor, small as it is, was daunting enough I spent much of the month girding myself to face the terror.

Not all software necessarily needs to get to level 9. I think many of my Freewheeling Apps are simple enough and evolve slowly enough that they would stabilize to a bug-free state with just a handful of people using them, regardless of my initial design choices. Particularly now that I know how to streamline one complex piece at their core. Still, it's good to be aware of how things might be improved, if it becomes worthwhile.

One thing that feels definitely useful in getting to level 9 is data-oriented design. It's not a tool you can blindly apply but a way of thinking you have to grow into, to look past immediate data structure choices at the big picture of how your program accesses data. Just don't let tools like ECS blind you to the essential intellectual activity.

These levels are probably not quite right. I'm probably under-estimating tools I have less experience with.

I wonder what levels lie beyond these.

(I last wrote some thoughts on how I program back in 2019. It's nice to see signs of evolution.) ]]> http://akkartik.name/post/sokoban 13 Mar 2024 00:00:00 PDT http://akkartik.name/post/sokoban The kids have been enjoying Baba is You, and watching them brought back pleasant memories for me of playing the classic crate-pushing game Sokoban. So I went looking and found a very nice project that has collected 300 classic publicly available Sokoban puzzles. Then of course I had to get it on my phone so I could play it anywhere. The result is the sokoban.love client.

On a technical level, with sokoban.love I've finally managed to figure out how to scale modifying programs on my phone beyond the tiny scripts Lua Carousel supports. Carousel treats each 'page' of the carousel as a separate script, and shares the screen between the code for the page and the drawings the page makes. When you switch between pages, Carousel saves and restores code for you so the script currently on screen is always the one currently drawing.

sokoban.love comes bundled with multiple pages of code (including 7000 lines for all the levels; those would be a pain to copy paste into Carousel). The pages all collaborate to create the app; switching pages changes nothing about the code that is running. The screen is also no longer shared between the app and its code editing environment. When you run the app the Carousel menu disappears, replaced by a single button to exit the app and edit its code.

This approach works well for editing on a phone. The trade-off I made is to jettison the live-editing experience. You can still get that with sokoban.love, but you'll need to get on a computer and connect driver.love to it like all my Freewheeling Apps.

As a bonus, sokoban.love includes a simple solver to eliminate some gruntwork for moving the player on touchscreens that you can see in action in this video. Tapping on the buttons along the edges moves the player a single square. Tapping on an empty square moves the player there if that is possible without moving any crates. Tapping on a crate and then an empty square will try to get the crate there if that is possible without moving any other crates. ]]> http://akkartik.name/post/rabbot 20 Feb 2024 00:00:00 PDT http://akkartik.name/post/rabbot rabbot.love is a little helper I whipped up to check the programs the kids were writing for a neat little paper computer.

repo

Carousel has its own devlog/notebook. I try to post little scripts that are easy for someone to copy to their clipboard, paste into Carousel and run. Some examples:

• Hilbert curve and Lindenmayer tree fractal (70 lines each)
• rectangle art (40 lines)
• simple example using the physics engine. (100 lines)
• Chromacline: a war between colors in Game of Life world (100 lines)
• simple UI examples; simple voice recorder (<50 lines each)
• sprite editor (100 lines)
• Pong wars (70 lines)
• equation plotting over an infinite surface with pan and pinch-zoom (150 lines)
• Lots of different kinds of charts (200 lines)

How can we do this from within the LÖVE app? So there's nothing to install?

This is a story about a hundred lines of code that do it. I'm probably not the first to discover the trick, but I hadn't seen it before and it feels a bit magical.

Read more ]]>