4 ms·

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?)
- catapart 4y ago
  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.
  - tonerow 4y ago
    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)
    - catapart 4y ago
      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. Like ``` #parentKey parent #childKey child #childKey -> #parentKey /north ``` could be equivalent to ``` #parentKey parent #childKey child /north ```
      - tonerow 4y ago
        I see. That's an interesting idea! I can definitely see how tokenization makes filtering parts of the graph easier.
- anoncept 4y ago
  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.)
  - graphviz 4y ago
    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/scan.l 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/labels.c#L113 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.
    - anoncept 4y ago
      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://mstone.info/depict/ -> https://github.com/mstone/depict https://github.com/mstone/depict
- acidburnNSA 4y ago
  I'm a pretty big fan of graphviz/dot myself so that kind of transform would be great. https://www.graphviz.org/gallery/ https://www.graphviz.org/gallery/ https://graphviz.readthedocs.io/en/stable/examples.html https://graphviz.readthedocs.io/en/stable/examples.html
  - tonerow 4y ago
    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.

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?)
catapart 4y ago
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.
- tonerow 4y ago
  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)
  - catapart 4y ago
    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. Like ``` #parentKey parent #childKey child #childKey -> #parentKey /north ``` could be equivalent to ``` #parentKey parent #childKey child /north ```
    - tonerow 4y ago
      I see. That's an interesting idea! I can definitely see how tokenization makes filtering parts of the graph easier.
anoncept 4y ago
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.)
- graphviz 4y ago
  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/scan.l 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/labels.c#L113 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.
  - anoncept 4y ago
    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://mstone.info/depict/ -> https://github.com/mstone/depict https://github.com/mstone/depict
acidburnNSA 4y ago
I'm a pretty big fan of graphviz/dot myself so that kind of transform would be great. https://www.graphviz.org/gallery/ https://www.graphviz.org/gallery/ https://graphviz.readthedocs.io/en/stable/examples.html https://graphviz.readthedocs.io/en/stable/examples.html
- tonerow 4y ago
  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.