Generic Syntax / Layout Algorithms

[nirname]

While developing new diagram, I noticed that there are plenty of things, that can be done based on the same syntax. All the diagrams are data driven, so that is not really important what the source of data is, more important that it is structured one. Having looked at Excel, you may notice that table representation is almost always fulfill the purpose. So there is not so much difference between:

• Bar
• Pie
• Line Chart

Because all of them represent the same idea - proportion.
We can assert the same thing about the majority of all node-links graphs (with some assumptions), like:

• Git
• Mindmap
• State
  ...and many others.

So the only difference is layout algorithm + some attributes and verifications.

Is it possible to support some universal languages or formats like dot, csv, or maybe a custom one, and specify data format and layout algorithm independently?

[knsv]

If all diagrams that use a graph like flowcharts/state diagrams, class diagrams etc would generate a layout object of the same type when performing the layout algorithm, we could use the same rendering logic everywhere. The difference would be different shapes/styling of edges etc. This is something we should work on (in the roadmap).

The other aspect is regarding syntax. My main though here is that if can make one diagram you should not need to relearn everything for next one.

This becomes more and more important the more diagrams we add. We have some diagrams that has been created in the project like for instance flowcharts. For others diagrams we have tried to re-use PlantUML syntax to make it easier for authors.

My latest thoughts here would try to end the duality be to make a common UML syntax.

Note though that when it comes to syntax we are very restrictive. Once it has been released ... it is there. You can expect some developer integrating mermaid to a website to cope with breaking changes when updating mermaid. A very different story with diagram authors. We can not expect them to go back and update the documentation already written this means that the syntax once it is released is fixed.

One example of an early mistake ;)

Legacy syntax:

A --->| an edge label| B

The more readable syntax:

A -- an edge label --> B

We still support both.

[knsv]

Some examples that should be the same everywhere:

• classDef
• styling
• theme handling
• title handling
• comments (obviously...) :)

[nirname]

From my perspective, although UML is a standard and well defined, it is not a best choice because its notation complexity and variety is half way between bash and makefile. It takes a considerable amount of time to memorize all this symbols and not using all of them quite often forces a user to constantly check their meaning. Lets have a look at it:

@startuml
Class21 #-- Class22
Class23 x-- Class24
Class25 }-- Class26
Class27 +-- Class28
Class29 ^-- Class30
@enduml

Answer #1

These are different shapes. I can accept arrow operator -> because it is very pictorial, but why on earth this # refers to rectangle, I have no idea.

---

Another example, ask anyone who is not very familiar with it, what does it mean

@startuml
class Dummy {
 -field1
 #field2
 ~method1()
 +method2()
}
@enduml

Answer #2

In that one example, which is supposed to be a simple one, they replaced human readable words with some obscure notations and eventually a user ends up referring to their documentation.

Whereas any translator will help you with plain English.

---

And if you, esteemed reader, got to this point, now, without looking at the previous answers, test yourself, say what diagram would it be and what does it represent:

@startuml
class Message {
  #text
}
Message #.. User
@enduml

Answer #3

The answer is that text is a protected field marked by diamond shape which is represented by # (nothing says it is protected, only diamond shape, you need to learn that) whereas the same # sign in the links represents ... rectangle.

---

I believe initial intentions of PlantUML developers were good but they ended up in a sort of language that is not readable at all and you can only handle it through WYSIWYG editor. It must be treated as internal format only.

Perhaps we can support Plan UML simply as one of the possible notations, but not as a standard

[nirname]

I cannot fully agree on that. I think it is professional deformation. People are getting used to special characters, but in every tool and every language they have their own meaning. Had not there been some habits there would've been much more human-readable formats.

[weedySeaDragon]

Some points:

1. Supporting both experts/advanced users and novices/casual users

This is a classic cognitive/UX problem: How to support both experts/advanced users ("power users") and novices (casual/infrequent users). They represent not only different levels of what they know (e.g. the syntax) but also of how they use that knowledge.

Specifically, when dealing with syntax, what is "readable" for experts is not necessarily "readable" for novices.

2. Any syntax adopted must be based on logical overall design decisions

Note: all of my comments are about the syntax going forward. I am not addressing the fact that we must support current/past syntax (backwards compatibility).

What is most important is that whatever decisions are made about the syntax (notation), the decisions and design have an overall logic so that users (both experts and novices) can have a basic understanding of why a notation (symbol, string of symbols) was adopted.

This lowers the friction (makes it easier) for learning and remembering the syntax.
Ex: With UML notation, @nirname doesn't know why # refers to a rectangle:

but why on earth this # refers to rectangle, I have no idea.

If he knew the reasons behind that, it would be easier to remember and 'make sense' to him. (Perhaps it's because the octothorpe (#) has a rectangle shape within the grid.)

When there are underlying principles and logic:

• users can better guess and predict what a syntax means even if they don't know/understand 100% of it. This means that users can read syntax and understand the basics without having to remember all of it
• future additions to the syntax (e.g. additional diagrams) will be less likely to have edge-case and 'non-standard' syntaxes/notations

[weedySeaDragon]

@nirname Can you explain what you mean by:

... I think it is professional deformation.

I'm not familiar with the phrase "professional deformation"

[nirname]

Deviation in behavior if I may say so. A person who are used to complex things stops thinking they are complex and starts to think that other more extensive but readable things are redundant.

[weedySeaDragon]

Got it. Thanks for explaining.

[weedySeaDragon]

Chiming in here:

Be sure that whatever syntax is adopted/evolved, it can be parsed by a lexer-parser (as is being done now across all the diagrams/charts). It must have a well-defined grammar. I point this out because the syntax PlantUML is a mess; don't want to end up like that. That's also why I agree with @nirname : It'd be fine to support PlantUML if wanted, but Mermaid should not use it as a basis.

[weedySeaDragon]

Sidenote:

I think that the references to "UML" in this discussion all really refer to PlantUML .
This is not the same as the long-time standard "UML" notation. It's important not to confuse the two. (Wikipedia entry for UML with some history.)
PlantUML has a custom syntax developed ad hoc and is not a grammar that can be easily parsed. (If you look at the code, you can see that.)

(Fun fact: I started with OO in the late 80s and watched the UML develop.)