6 ms·

A CSS-Inspired Syntax for Flowcharts

130 points by tonerow 4y ago

Veuxdo 4y ago
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 https://www.ilograph.com
gavinray 4y ago
This idea rocks, great writeup!
mro_name 4y ago
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 https://en.wikipedia.org/wiki/DRAKON
- lupire 4y ago
  Omnigraffle? ($$)
KaoruAoiShiho 4y ago
Article doesn't explain what's wrong with mermaid?
- tonerow 4y ago
  (article author here) There's definitely nothing wrong with Mermaid. In fact, the current syntax at https://flowchart.fun 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.
immigrantheart 4y ago
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.
eurasiantiger 4y ago
Needs some way of saying ”these things are alternatives to each other so display them side by side”.
- tonerow 4y ago
  When you say _these things_ you mean the previous syntax and the new syntax? Sorry, I don't understand.
  - eurasiantiger 4y ago
    No, I meant nodes in the diagram and why not edges too.
deleted 4y ago
[deleted]
tonerow 4y ago
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!
- masukomi 4y ago
  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.
- anoncept 4y ago
  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!
- catapart 4y ago
  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!
  - tonerow 4y ago
    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?
    - catapart 4y ago
hk__2 4y ago
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.
- spockz 4y ago
  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.
  - tonerow 4y ago
    That's sort of what https://flowchart.fun https://flowchart.fun is. Although, it doesn't have as many graph types as PlantUML. Mermaid also has https://mermaid.live/ https://mermaid.live/ running in the browser.
- tonerow 4y ago
  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.
- anoncept 4y ago
  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.
  - lupire 4y ago
    Pro tools like Omnigraffle handle that sort of thing. Best of both worlds.
cbarrick 4y ago
Why would someone choose this over DOT?
- tonerow 4y ago
  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.
  - wpietri 4y ago
    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?
    - xaedes 4y ago
      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.
    - anoncept 4y ago
      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?)
Joker_vD 4y ago
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.
- chrisweekly 4y ago
  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 https://every-layout.dev to see CSS in a new light; it's profoundly compelling, powerful, and elegant.
  - jonahx 4y ago
    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 http://worrydream.com/MagicInk/#p255
  - mixmastamyk 4y ago
    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.

130 points by tonerow 4y ago

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 https://www.ilograph.com

gavinray 4y ago

This idea rocks, great writeup!

mro_name 4y ago

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 https://en.wikipedia.org/wiki/DRAKON

lupire 4y ago
Omnigraffle? ($$)

KaoruAoiShiho 4y ago

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

tonerow 4y ago
(article author here) There's definitely nothing wrong with Mermaid. In fact, the current syntax at https://flowchart.fun 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.

immigrantheart 4y ago

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.

eurasiantiger 4y ago

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

tonerow 4y ago
When you say _these things_ you mean the previous syntax and the new syntax? Sorry, I don't understand.
- eurasiantiger 4y ago
  No, I meant nodes in the diagram and why not edges too.

deleted 4y ago

[deleted]

tonerow 4y ago

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!

masukomi 4y ago
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.
anoncept 4y ago
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!
catapart 4y ago
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!
- tonerow 4y ago
  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?
  - catapart 4y ago

hk__2 4y ago

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.

spockz 4y ago
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.
- tonerow 4y ago
  That's sort of what https://flowchart.fun https://flowchart.fun is. Although, it doesn't have as many graph types as PlantUML. Mermaid also has https://mermaid.live/ https://mermaid.live/ running in the browser.
tonerow 4y ago
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.
anoncept 4y ago
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.
- lupire 4y ago
  Pro tools like Omnigraffle handle that sort of thing. Best of both worlds.

cbarrick 4y ago

Why would someone choose this over DOT?

tonerow 4y ago
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.
- wpietri 4y ago
  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?
  - xaedes 4y ago
    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.
  - anoncept 4y ago
    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?)

Joker_vD 4y ago

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.

chrisweekly 4y ago
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 https://every-layout.dev to see CSS in a new light; it's profoundly compelling, powerful, and elegant.
- jonahx 4y ago
  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 http://worrydream.com/MagicInk/#p255
- mixmastamyk 4y ago
  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.