A CSS-Inspired Syntax for Flowcharts | Hacker News Reader

A CSS-Inspired Syntax for Flowcharts

tone-row.com

130 pointstonerow47 comments

In my experience, the biggest issue with flowcharts is not to transform text into charts (PlantUML works well) but to get the layout I want when the chart/graph becomes more complex. For complex-but-small charts I usually just do them on Google Drawing because I have total control over the layout.

That's very true. On Flowchart Fun we have a bunch of layout algorithms you can choose from, but even then making a great-looking graph usually requires some manually tweaking like you said.

Total control is good for small charts and for especially important charts but for complex uses, the number of clicks and drags required to perfectly position connectors really rapidly degrades the editing experience, especially if you’re still working out the contents of what needs to be depicted.

As a result, for either high-speed or larger scale usage, my experience is that text (in combination with constraint-respecting automatic layout options that suit one’s personal aesthetic) really starts to shine.

Pro tools like Omnigraffle handle that sort of thing. Best of both worlds.

And omnigraffle can take a dot definition as input and the let you fiddle with it manually, it is really a joy to work with.

yEd is freeware (not free software) but I have not found a better program that matches accessibility (Java-based so runs cross-platform) and sophistication in automated graph layouts.

Have you found a tool similar to plantuml that runs completely in the browser? I could deploy the web server but it would be nicer if I didn’t have to maintain a running server for generating the images.

That's sort of what https://flowchart.fun is. Although, it doesn't have as many graph types as PlantUML. Mermaid also has https://mermaid.live/ running in the browser.

Hey everyone! I stumbled into a syntax for flowcharts and other data/graphs that I think is pretty interesting. I'd love to get peoples feedback on what works/doesn't work and ways to improve it. Thanks!

This looks like a really nice attempt to improve the comfort and capability of styling drawings of small graphs that I’m excited to explore; thanks for building and sharing it!

I've been approaching a similar problem, recently, in trying to represent my javascript node-graph elements as plain text. Very different output and use case, but I settled on the same kind of "psuedo-selector" idea that you seem to have. Hash to tag id's, wrappers to allow for complex content, and I even went as far as to use query string format to allow for dynamic event raising (when a node is hit, I can trigger an event with a key and value pair). I can show a video of it, if it's of interest, but I don't think there's much I can help recommend. This comment is just to say that I like what you're doing and have found myself in a similar situation so I'll be very eager to hear what the community has to say about your project!

That sounds really cool! When you say query string, am I right in thinking of URL search params? i.e., "?trigger=event1" kind of thing?

Yes, exactly! For example `(myVar=myVal&key=value)` I use a runtime list of regex to parse the text into tokens, so it's completely dynamic but my current project I have a need to "condition" the nodes (only show up if certain conditions are true) and also to set values upon node actions (in this case, "selecting" a node can set values; i.e. `<myVar="a weirdly formatted new value"&key=newKey>`, or whatever). As far as I can tell, allowing the library that will generate compile-time/runtime objects from the nodes to receive those types of key-value pairs can allow for whatever text-substitution, state-setting, or event triggers a consuming app would need. Very interested if you can think of some outlier functionality that I'm missing, though!

It definitely seems like your use-case is more complex than just rendering the diagrams. I think that is very cool. I'd love to see the video if you want to share it (my email is on my hn profile)

Oh for sure! I'm actually using the parsing to generate a branching dialog markup syntax, so it's keeping track of things like if you've already chosen an option, or if your character has the stats to even show an option to you.

The intention, though, was the make the variable assignment general-purpose enough for whatever node data needed to be stored. So, in my case, I'll be storing things like "x" and "y" positions, so that the nodes can be restored to their absolute position on the graph.

As for the video, please feel free to ask any questions; I'm sorry about it being kind of slow and incomplete. This was recorded to showcase how the tokenization is dynamic: https://streamja.com/JKPkJ

initial thoughts:

- if indentation is significant, then save yourself headaches and require either tabs or spaces. Don't allow both. - not sure why i'd want to use this instead of plantuml which can do this, plus so much more.

About 47 years ago Dijkstra wrote his infamous "How do we tell truths that might hurt?" memo which contained this dubious claim, among other dijkstrisms:

    It is practically impossible to teach good programming to students that have had a prior exposure to BASIC: as potential programmers they are mentally mutilated beyond hope of regeneration.

    The use of COBOL cripples the mind; its teaching should, therefore, be regarded as a criminal offence.

Of course, one can write off that quote simply as Dijkstra's typical arrogance and over-exaggeration (and hey, who even uses BASIC or COBOL any more?) but every time I see attempts to carry the CSS experience over to other areas, or just the "CSS is amazing, why do you all not see it?" attitude, I get an uneasy feeling that he might've actually been on to something.

Most CSS, as authored, is a maintenance nightmare full of kludges. So I can understand your take. But (as someone who's been building and improving websites since 1998), I don't blame CSS per se. The problem is developers who haven't learned it properly trying to be the browser's micromanager instead of its mentor. Take a look at https://every-layout.dev to see CSS in a new light; it's profoundly compelling, powerful, and elegant.

It has gotten more tolerable with flex and grid, but no, the problem is not primarily developers' lack of moral virtue. The design of CSS has deep problems. The most thoughtful critique I've seen is still Bret Victors in Magic Ink. While the piece is old and CSS has improved a lot since then, the basic points are all still relevant:

http://worrydream.com/MagicInk/#p255

Fantastic... a blank page. Agree it is elegant, but not particularly compelling.

I needed to read the source html to see what it was about. Pentagrams in the source, btw.

Blank page? Strange. Try https://every-layout.dev/rudiments/boxes/

Looks like it was white on white after all, I managed to get some contrast haha. I've seen this site before. Thanks.

CSS the language is pretty great.

All of the hacks and warts around the specifics of rendering for the browser? Pretty bad.

Why would someone choose this over DOT?

That's a good question. I'm less familiar with DOT than I am with Mermaid.js, but in my experience the one benefit an indent-based language has over the declare nodes then declare edges separately pattern (which I'm pretty sure DOT is also) is that it's nice for making smaller graphs quicker, because you retain a lot of context when you're just indenting from the line above. But that's totally a guess on my part.

DOT seems like a really robust, expressive language. Maybe at some point I'll to write something that transforms from this syntax to DOT.

In my experience, typing dot requires a lot of quoting and brace-matching, often in editors without the best affordances for those operations, with so-so error reporting.

The result is that it’s very challenging to type syntactically correct dot at “line-speed”, e.g., if one is taking notes.

(This is one of several reasons that I think there is definitely still room for improvement in notation for graph-drawing, as I have begun exploring in my own work.)

That's interesting. It's not hard to see the problem. HTML labels don't help, either. How do other languages solve this? Like, a shell HERE document that has one fixed string as a terminator? The graphviz lexer https://gitlab.com/graphviz/graphviz/-/blob/main/lib/cgraph/... seems hackable but disabling downstream processing of escapes elsewhere would be necessary too. Possibly this would mean bypassing some of the processing in the function make_label in https://gitlab.com/graphviz/graphviz/-/blob/main/lib/common/...

It's a disappointment or even failure of our current language scanning and parsing tools or, really, the way we used them, that this is not an easy exercise.

One potential solution direction, which you can try out via my own incomplete drawing toy [1] is to treat punctuation characters like SP (“ “), COMMA (“,”), and SEMICOLON (“;”) as markers for the product operations of a family of monoids that allow you to specify more and more complicated sequences without requiring the typist to “move the cursor left” to add a matching character.

This way, simple lists can be specified via juxtaposition:

a b c

And then more complex lists

thing 1, thing 2, thing 3

and still more complex lists like

A complex thing; with data, and more data

can be specified in a way that is potentially still human-legible and easily editable.

Combined with ~instant feedback while typing and, ideally, a “brushing” system to allow selection of parts of the textual model via the linked drawing, I am hopeful that this can be solved resiliently, at least for the most common use cases.

(Part of why I am excited about OP’s work here though is that while I have done a fair bit in my own project on drawing a related kind of diagrams, I have myself only begun thinking about how to make the resulting drawings nicely stylable/themeable.)

[1] https://mstone.info/depict/ -> https://github.com/mstone/depict

I'm a pretty big fan of graphviz/dot myself so that kind of transform would be great.

https://www.graphviz.org/gallery/

https://graphviz.readthedocs.io/en/stable/examples.html

Noted! After Github added support for Mermaid in markdown, we added an "Export as Mermaid" feature to Flowchart Fun. It's good to know people would be interested in conversion to Graphviz too.

At this point I feel like I've come across a half-dozen of these text-to-chart languages. My impression is that they all started with a simple case for which it works fine, but then get hairy as they add broader/more complex use cases.

It leaves me wondering: if somebody carefully looked at all the languages and all the use cases, is it possible to build a single language that does it all while still being easy for smaller charts? Or are the goals of easy and complete in too much tension, such that we're better off with a bunch of languages, each one tuned for making things easy in a particular zone of the problem space?

That syntax here already is basically just sexpressions with indentation. Just integrate a full lisp with macros and all. Then people can define sugared DSLs for the simple use cases.

IMO there are always going to be tensions (as well as differing personal preferences) for surface syntax and authoring environment.

What I think may emerge though is a better shared understanding of “what’s needed” as well as a great (ideally libre) library for implementing those ingredients consistently and interoperably — e.g., a DOM/CSSOM for these graphs as well as maybe an adaptagrams- or cairo-like library for the common layout and drawing capabilities.

(For example, have you noticed how many general-purpose drawing tools now have “align and distribute” capabilities that all work similarly? AIUI, many of those tools are either directly using or are inspired by Kim Marriot, PJ Stuckey, Tim Dwyer, & colleagues’ work in this area?)

With this intention in mind, I think I may have a recommendation? You might consider shorthand / expanding tokens? In my project, I have a couple of well-known nodes with a parent child relationship, such that it would be impractical to write out all of the link definitions separately. But there also needs to be a way to format the nodes in a way that makes logical sense to the markup writer, so I included a simple token - for those nodes only - that link them. On the backend, it goes through shorthand tokens first, then document placement, then into other parsing if those don't match. So, the idea is similar to the CSS values having multiple shorthands; the language just understands them all. It's a ton more work, but it's valuable for interop, which seems to be the whole purpose of generalized formatting like this.

Are tokens different from applying an ID to a node? In this syntax something like

---

#token Some Node That is Referenced Often

other node A

  (#token)

other node B

  (#token)

other node C

  other node D

    (#token)

Oh! Sorry! "Token" is an intermediary object that acts as a sorting category.

So if your markup was:

```

#parentA Start 'Welcome Node'

  #childA /1 "this node has a

line break, so its content is in quotes"

```

That could be "tokened" as

[

{

tokenType: "ID"

value: "parentA"

decorators: [{ "character": "#", indexes: [0]}]

{

tokenType: "CONTENT"

value: "Start"

decorators: null

{

tokenType: "TITLE"

value: "Welcome Node"

decorators: [{character: "'", indexes: [0, 13]}]

...

]

So it could be that you can read multiple different syntaxes into the same tokenizations.

```

#parentKey parent

#childKey child

#childKey -> #parentKey /north

```

could be equivalent to

```

#parentKey parent

  #childKey child /north

```

I see. That's an interesting idea! I can definitely see how tokenization makes filtering parts of the graph easier.

You've done what I were trying to do a year ago! I was trying to build a crypto visualizer app that's easy to write. I played around using Cytoscape.JS but still thinking of how to best represent the data in a textual format.

This is a cool idea! Although my project is now in a back burner, in the future if I want to pick up where I left off I might just use your library.

Ilograph[1] is tackling this problem using YAML instead of css. Both are declarative, which is the key differentiator vs. tools that use programming languages.

[1] https://www.ilograph.com

Needs some way of saying ”these things are alternatives to each other so display them side by side”.

When you say _these things_ you mean the previous syntax and the new syntax? Sorry, I don't understand.

No, I meant nodes in the diagram and why not edges too.

bear with me slightly OT: I am looking for a tool to edit drakon[1] flowcharts offline on a M1 mac.

[1] https://en.wikipedia.org/wiki/DRAKON

Omnigraffle? ($$)

This idea rocks, great writeup!

Article doesn't explain what's wrong with mermaid?

(article author here) There's definitely nothing wrong with Mermaid. In fact, the current syntax at https://flowchart.fun can be converted to Mermaid (in export window) and I'll continue to support that when I migrate the app to the new syntax I'm proposing in this article.

The biggest differentiator is indenting to create edges, which I think is useful for some graphs and in some contexts (especially for quick brainstorming). Mermaid is great and super expressive.

Reply on news.ycombinator.com