Consider building the SVGs from PlantUML sources using a GitHub Action

[nigelmegitt]

https://github.com/marketplace/actions/plantuml-generator could be useful for generating the SVG images from PlantUML sources as a build step. Currently any edits to the diagram(s) need to have an SVG generated locally and committed and pushed, but arguably they could be build artefacts instead.

Low priority.

[himorin]

some random considerations...

• we are using spec-prod action for generating (via respec w/ local browser) and uploading to /TR/, which relies on actions/checkout for assets from git repository
  • initially checkout PR ref, but final status of actions/checkout is detached HEAD, so not easy to push something back from here to main
  • spec-prod seems to use the local assets passed after checkout step, so some edit like plantuml-generator could be possible before processing of spec-prod (or say, respec)
  • if there is no nice action on git operation, it's not easy to push generated SVG file into some branch, like main or PR - need to use git command as old style
  • note that we cannot push updated detached HEAD to main, since assets contains ones to be merged to main after this GHaction
  • not sure what happens when we update PR/id/merge branch via GHAction...
• spec-prod also can push generated assets into gh-pages, we may rely to that for ED (of course, no use after passing FPWD and set streamlined publication as our default)

another possible way with some restriction, separate PR into two, one only with UML sources, and anything else. For latter, the same as now, and for former we can copy and paste an example in plantUML action's page.

[nigelmegitt]

Discovery we made after adding the GitHub Action to check or check and deploy for automated publication: the SVG that PlantUML makes does not pass our validation checker. It has a few issues, which are certainly manually fixable. If we were to generate the SVG as an action, we'd also have to write a script to clean it up.

Most of the fixes are easy enough - a simple regexp could be used, but one of them in particular, where the XML needs to be slightly restructured so there are not nested <a> elements, is likely to be a bit trickier to fix.

[himorin]

I believe nested a itself is wrong, since most of them are link covering all of UML class diagram, and nested ones are its members. (I've not checked whether it is non-changeable styling of the processor, although...) One another possible way could be using separate SVG image, if SVG themselves are valid (I believe validator will not check files linked from html), but named links would not work for this option...

[nigelmegitt]

I think keeping the current Respec inclusion mechanism is best, because I prefer to keep those links working. Of course the other option is to file a bug report with PlantUML, which I intend to do.

[nigelmegitt]

I looked at Mermaid as an alternative to PlantUML but according to the docs (and my experiment) it cannot generate links from class members, only classes. That seems like a significant drop-off to me.