embed a graph description language

[vitiral]

I would like to leverage svgbob to be able to support svg diagrams.

Basic design

The svg code block will render as an svg diagram. I.e.

\`\`\`svg
    -o----o---
          |                    .--> D
           \                  /
A -> B -> C -----------------*---> .
            \         ^  ^ ^  \
             B -> C _/  / /    '--> D
 *----->           \   / /
                    *
\`\`\`

The backend/static site would search for these blocks and add a rendered_svg field onto Project which would be a HashMap<ArtName, Vec<SVG>> containing the indexed svg images in the specified artifact's text.

Future Improvements

In the future there could be a RenderSvgs API call to dynamically render a list of raw svgs so that svg can be rendered while editing (without needing to save).

[vitiral]

I think there might be an even better solution here, which is the DOT graph description language

It has extremely concise syntax and can be rendered as a imagemap (image where nodes can provide links).

Use graphiz to allow more programmatic trees, including links within nodes:

• http://www.graphviz.org/content/output-formats#dimap
• link support using imagemaps: http://www.graphviz.org/content/graphviz-links-within-record-nodes
• http://viz-js.com/ : this is probably the javascript library I would use to render things
  • if you replace the a1 line with the following, you can get links to work in the SVG format:
  • {"[[REQ-foo]]" [fontcolor=blue; URL="https://google.com";]} -> b3;
• attributes are well documented here: http://www.graphviz.org/doc/info/attrs.html#d:URL

You can "declare" node attributes like this. Further attributes can still be defined at later points.

    {"REQ-foo" [fontcolor=blue;URL="https://google.com";]};
    {"b0" [fontcolor=blue; URL="https://google.com";]};
    {"b1" [fontcolor=red; URL="http://xkcd.com"];};

[einsweniger]

While I do like the graphviz system, I have strong feelings about it. The dot language is an ambiguous mess and the documentation is horrible. Took me two days to figure out what will work and what won't: otherwise dot is concise and versatile.

[vitiral]

The documentation is pretty bad, but I'm curious what you mean by "ambiguous mess"? Can you give some examples? **Edit:** I'm also curious if you have thoughts for an alternative? I'm all ears! For my use case, I thought it was quite succinct and NOT ambiguous: - nodes are just plain text `node`, a string `"a node"` or if you want to add attributes, a `{...}` block `{"a node" [URL="https://google.com"]}` - nodes can be connected with `->` - you can use the same name multiple times: ``` a -> b -> c a -> c -> d -> e -> f ``` Also there is *some* way to specify if statements, but I can't find it right now... Okay, it's not *great* ... haha

[vitiral]

Here are some pretty decent tutorials I have come across:

• basic tutorial: http://www.graphviz.org/pdf/dotguide.pdf
• pretty good examples and references: http://graphs.grevian.org/documentation
• more good examples: http://tonyballantyne.com/graphs.html

As for if statements... just use the diamond shape.

I'm looking online for alternatives and really don't see any -- it looks pretty spiffy to me honestly.

[einsweniger]

Alternatives: none.
It's the best tool for the job, I just wanted to sound the warning.
At first glance, dot seems elegant and simple; until you try to get it to behave the way you want.
One of the most offputting features: I wanted my subgraph in a box.
So, try to find the attribute in the official documents, the way they do their documentation is not my thing. Explanation and vaild scope are just too far away from each other.

At some time you give up and try to work by example. After bisection you realize nothing you did is different but you still won't get a box around the subgraph.
Once you realize, that you get a box around it, just by giving the subgraph a different name (e.g. cluster_0): that's why I think is ambiguous.
If you just want to output arbitrary dependency graphs, dot is just fine.

[emden]

We took the approach of providing tutorials, a collection of examples with corresponding "recipes" and in-depth descriptions of the language, attributes, node shapes, etc. Clusters are described in the dot tutorial, several examples are given on the Gallery page, and clusters and their semantics are described in the dot language page. The tutorial notes A cluster is a subgraph placed in its own distinct rectangle of the layout. A subgraph is recognized as a cluster when its name has the prefix cluster. The Gallery example labeled Cluster has the text This small example illustrates dot's feature to draw nodes and edges in clusters or separate rectangular layout regions. Clusters are encoded as subgraphs whose names have the prefix 'cluster'. Subgraphs and clusters relate to the graph's topology; they are not layout or rendering attributes. In any case, this hardly warrants the language being viewed as an ambiguous mess. The language is very concise and there is no ambiguity in any well-formed graph described in dot.

[vitiral]

@emden thanks for the clarification. I should point out by "pretty bad" that I meant in my 10 minute overview of the linked docs I didn't come across good docs (again note: good docs for getting started -- they are extraordinarily complete from a specification standpoint). Since then I have found the ones I linked, and have noticed that the new site (which is not yet the main one) does link to the docs from the beginning (looking forward to it being the main site!)

I think I will be adding a brief overview of DOT in the simple quality book. I would love any review by a project contributor when I do!

[vitiral]

it looks as if this may depend on #190. Hopefully we can reach consent (looks possible).

[einsweniger]

@emden Well, I'm sorry. I should have phrased it differently. That's what it felt like when I used it to build more complicated graphs with interdependencies and different node weights. I just did not get it.

Instead of harsh phrasing, I should have considered improving the documentation.

[vitiral]

The initial implementation is now merged into master. I will be doing some follow up work to improve the overall web-ui using graphviz nodes. Stay tuned!