snap.love/README.md

snap.love: a graph drawing tool

Unlike Graphviz and PlantUML, this tool is for small graphs where you want complete control over layout. Unlike PowerPoint or draw.io, this tool results generates text files that are more amenable to version control. The catch: it's a lot more limited than all these tools; all you can do so far is draw rectangles and edges between them.

You can't change the styling. Unless you modify the code. But that's easy! Read on.

Getting started

Install LÖVE. It's just a 5MB download, open-source and extremely well-behaved. I'll assume below that you can invoke it using the love command, but that might vary depending on your OS.

Run this app from the terminal, passing its directory to LÖVE.

You'll see a single box on screen. Drag the surface or press arrow keys to pan around. Try dragging the border of the box. You'll see an edge stick out. Release the mouse button, and a new box (node) will pop out at the other end of the edge. Try dragging the top-left bar for each box. They move relative to each other. Try typing inside. The text wraps within and the box grows taller to accomodate it. Try dragging the parallel lines to the right of a box. The width of the box changes.

Try quitting and restarting. Your changes will still be present. By default, snap.love writes to a file called graph in a directory specific to this app (https://love2d.org/wiki/love.filesystem.getSourceBaseDirectory). To switch to a different file, drop it on the snap.love window. You can also pass in a filename when starting the app from the terminal.

Hacking

To make changes to this app without restarting the app each time, download the driver app. Example session:

To publish your changes:

• delete all files with a numeric prefix from the repo, and then
• move all files with a numeric prefix from the save directory to the repo.

Keyboard shortcuts

While editing within a node:

• ctrl+f to find patterns within a file
• ctrl+c to copy, ctrl+x to cut, ctrl+v to paste
• ctrl+z to undo, ctrl+y to redo
• ctrl+= to zoom in, ctrl+- to zoom out, ctrl+0 to reset zoom
• alt+right/alt+left to jump to the next/previous word, respectively
• mouse drag or shift + movement to select text, ctrl+a to select all

When cursor is not in an editor:

• arrow keys pan the surface
• shift+arrow keys pan faster
  • pagedown and pageup are aliases for shift+down and shift+up respectively

Exclusively tested so far with a US keyboard layout. If you use a different layout, please let me know if things worked, or if you found anything amiss: http://akkartik.name/contact

Known issues

• Both freewheeling apps and the driver for them currently benefit from being launched in terminal windows rather than by being clicked on in a desktop OS. See the driver app for details.

• No support yet for Unicode graphemes spanning multiple codepoints.

• No support yet for right-to-left languages.

• Undo/redo may be sluggish in large files. Large files may grow sluggish in other ways. Works well in all circumstances with files under 50KB.

• If you kill the process, say by force-quitting because things things get sluggish, you can lose data.

• Long wrapping lines can't yet distinguish between the cursor at end of one screen line and start of the next, so clicking the mouse to position the cursor can very occasionally do the wrong thing.

• Can't scroll while selecting text with mouse.

• No scrollbars yet. That stuff is hard.

Mirrors and Forks

This repo is a fork of lines.love, an editor for plain text where you can also seamlessly insert line drawings. Its immediate upstream is luaML.love, a box model for a Lua-based markup language that models an infinite pannable, zoomable 2D surface. Updates to it can be downloaded from:

• https://git.sr.ht/~akkartik/snap.love

Further forks are encouraged. If you show me your fork, I'll link to it here.

Feedback

Most appreciated.