halcmd: add -p option to generate PlantUML diagram of HAL pins/signals

[petterreinholdtsen]

Emit bracket-style component boxes grouped by instance, with the component type name (loadrt/loadusr module name) in parentheses. Signals are rendered as queue entities so one writer can fan out to multiple readers via a single node.

Components with all unconnected pins are filtered out.

Also documents the new -p option in the halcmd man page.

This patch was created with help from OpenCode using local llama.cpp server with Qwen 3.6.

[BsAtHome]

Why can't you just use script-mode for output (halcmd -s) and post-process with your own script?
I cannot see a reason why you need to have plantuml specific output to be part of halcmd. If script-mode shows a deficiency for post-processing , then we can simply fix that (in a compatible way).

[petterreinholdtsen]

Why can't you just use script-mode for output (halcmd -s) and post-process with your own script?

Who say I can not? I just believe it is more convenient and available for a large audience if the program do this directly and on its own, instead of having to track down a separate tool.

This patch is actually a byproduct of an experiment adding a graph tab to halshow. Have not yet found a way to make that graph pretty and useful, so in the mean time I have been using plantuml to get an overview of the HAL setup and changes on machines. :)

[andypugh]

Do you have a sample of the plantuml output as SVG?

[BsAtHome]

But still, the correct way then is to make the script that is part of LinuxCNC for that "large audience". You still need plantuml for it to function. So, you make a script that calls halcmd -s processes the output and wraps it all up. No need to add another mode to halcmd. Just make a script that does it all for that large audience.

The problem I'm addressing here is that you can add N+1 output interfaces to halcmd and still not be able to capture them all for any audience's liking. However, it makes halcmd unnecessarily complex and difficult to maintain. Therefore, using one standard script-friendly output format, which we have, should suffice and everything else is external or encapsulated post-processing.

[petterreinholdtsen]

Do you have a sample of the plantuml output as SVG?

Sure. Attached.

[petterreinholdtsen]

The problem I'm addressing here is that you can add N+1 output interfaces to halcmd and still not be able to capture them all for any audience's liking.

While it of course is true and sound very dramatic, I suspect that in reality, there are two major formats that are relevant, the graphviz dot format and plantuml. So N=0 will make a lot of people happy and N=1 will provide a useful format for the wast majority. I would be happy to add a -g option for graphviz dot, if you believe it is vital to increase the audience approval.

[BsAtHome]

What about PGF/TikZ? Or R? Or Vym?. Then there are numerous other packages. Just looking at the very long list of available UML tools should give you an indication how many different ways there are to tell a similar story. There is the whole category of argument/concept mapping software and associated languages. You may not be able to surface once you down that rabbit hole and forever stay in the Red Queen's prison with your head chopped off.

FWIW, we already have N=1_{you know the saying, use N=0, N=1 or N=∞}. With N=1 we have the script-friendly output. As said, if it is insufficient or incomplete, then it should be fixed to be generic. But I'd strongly resist adding any specific target language.

[petterreinholdtsen]

[BsAtHome]

What about PGF/TikZ? Or R? Or Vym?. Then there are numerous other packages. Just looking at the very long list of available UML tools should give you an indication how many different ways there are to tell a similar story. There is the whole category of argument/concept mapping software and associated languages. You may not be able to surface once you down that rabbit hole and forever stay in the Red Queen's prison with your head chopped off.

I can probably even come up with my own special graph format, to increase the number of packages and formats. But doing this do not really affect the popularity of the most used formats, and thus not my observation on how many formats are needed to make the majority happy. :) A more relevant measurement might be to see how many competing LinuxCNC extentions exist for drawing a graph from the HAL structure, and which format they are using. I am thinking about projects like <URL: https://github.com/JTrantow/LCNC_HAL_to_graphviz > and the many mentioned in <URL: https://www.forum.linuxcnc.org/24-hal-components/37821-graphing-a-hal-configuration >

FWIW, we already have N=1_{you know the saying, use N=0, N=1 or N=∞}. With N=1 we have the script-friendly output. As said, if it is insufficient or incomplete, then it should be fixed to be generic. But I'd strongly resist adding any specific target language.

Always fun with some math, and while induction is a powerful tool, it is unlikely to apply if the goal is to provide for the majority, not track down every potential user and cater for every need. :)

…

-- Happy hacking Petter Reinholdtsen