Internals documentation?

I’m interested in adding a feature to Graphviz - something that happens to be useful to me. I’ve never hacked on it before and am wondering if there’s any documentation on the internals, something to give an overview of how the code fits together?

The feature I’m looking to add is treating SVG files as proper custom shapes similar to HTML labels - so you could draw a shape in eg Inkscape, add port attributes to elements in the SVG and then use that SVG file as a shape for a node and define edges that refer to the ports in it.

After a quick look through the code, I think I can see roughly how to do this, but I’m not at all sure I’ve got my head around everything I need to.

That’s an excellent idea, but I don’t think we wrote any documentation like that. In some situations the capabilities of the internal APIs were somewhat fluid as we were working on it, is my lame excuse.

Can I run the idea past you briefly? As far as I can tell, I need to:

  1. Add something to struct usershape_s to map port names to locations relative to the shape’s origin.

  2. Modify core_loadimage_svg to extract the port locations and store them in the usershape_t.

  3. Modify poly_port() to check for ports on user-defined shapes (though how do I retrieve the usershape_t at this point?)

Does that seem broadly the right way to go about this?

Yes, that sounds right. poly_port would get the usershape_t from the node pointer which is the first argument though I forget exactly how but we must already do that in other places.

A couple of things to be slightly aware of:

  1. If there is a need to support non-covex shapes you might need to modify poly_path eventually.
  2. The case analysis for all the types of edges and ports was quite tedious (“multiple self edge but between different ports on the same node; multiple flat edges from west side of left node to east side of right node, some have labels” etc.) and it would not be a great surprise if we discover new problems there. This would be a good candidate for more thorough automated testing.