I love the, idea of PlantUML, to be able to define UML diagrams in a textual form. The diagrams are really fast to write that way. But the problem is that the generated visual representation is far from what one would expect, they are almost useful as a tool for communicatng.
This has been brought up here for example https://github.com/plantuml/plantuml/issues/13. There's also several questions and suggestions here regarding better manual control of the layouts.
While it's possible to somewhat control the layout, by changing the direction of arrows, using hidden arrows and using Hidden groups, I don't think that's a good idea.Once you start doing tricks like that you can easily waste more time, than what you would have, by using a visual tool. It's certainly more annoying, and mostly a question of trial and error. Things could get better by giving more control, but I don't want more control, I want it to "just work".
Therefore I really wish that the automatic layout generation was much better. And I believe it's possible by switching to the Open Graph Drawing Framework instead of GraphViz. I did some experiments by adding "!pragma svek_trace on" to a relatively simple diagram. That generates a dot file, which I modified a little bit to allow a really simple program made with OGDF to open it, generate a layout and save it as svg. I also tried to use neato instead of dot for the generation, which was possible by just running dot.exe with different parameters, and adding "overlap=false" to the dot file. So it seams that integrating neato into the existing svek architecture should be really easy.
So let's do some comparison, first the original dot generated diagram
Then the same diagram with neato, as you can see it's still very far from good. It also loses the nice propery of the arrows going in one direction, which is good for class diagrams. However for state machines this could be a better format
Then let's look at the Sugiyama layout of OGDF (with OptimalRanking, MedianHeuristic, and OptimalHierarchyLayout). This layout have most of the same properties of the GraphViz dot layout, but is considerable easier to read. The arrows are not drawn, but it doesn't matter for this example.
There's another very similar one UpwardPlanarizationLayout, with OptimalRanking and OptimalHierarchyLayout. But produces a slightly taller graph, but with less crossings. So it's much better
For state machines, and why not for class diagrams too, if you don't care that much of which direction the arrow points. Then a PlanarizationLayout(with VariableEmbeddingInserter, EmbedderMinDeptMaxFaxLayers and OrthoLayout) could be used.
This generates a layout without any crossings whatsovever.
I didn't import these diagrams back into PlantUML, mostly since OGDF, doesn't export the svg files in the right format for PlantUML.
I checked the svek code, and it seems like support for this would be fairly easy to implement. Instead of generating dot files and importing svg files, you could generate a GML files (specifications), which an ogdf program can easilly read and write without losing any information.
The actual graph generation program (using OGDF) could be a separate project, which just takes a GML file, and converts it according to the commandline options given.
For PlantUML, you would need to add some syntax to specify that the target is that instead of GraphViz. For example by specifying this "ogdf -paramter1 -paramter2=value", at the top of the PlantUML file. The paramters could be anything, and PlantUML would not need to care. Which would help for developing these parts separately. Otherwise PlantUML would have to change each time we add some new way of generating layouts, either new algorithms or parameters for existing ones.
I can implement the external OGDF program, but I wish that you could implement the PlantUML part. Would that be possible? If not, then I will probably be forced to fork my own version of PlantUML, and do it myself, since these quick tests really shows that it would be worth it. The other option I have is to just ignore PlantUML and use a good visual tool.
Edit: Fixed the display of the Planarization diagram