Code Notes: replace the architecture diagram with a corrected SVG

[Zia-research]

code-notes.adoc:103 shows LinuxCNC-block-diagram-small.png, unchanged in the repository since 2012-11-19 (b60c20198e). This replaces it with a hand-written SVG: same topology, with corrections — they are listed here: https://zia-research.github.io/linuxcnc-audit/sheets/linuxcnc-code-notes-errata.html

@grandixximo proposed extracting this figure as a standalone .svg in #3718. This is not the continuation of #3718 — that PR updates LinuxCNC-block-diagram.png, a different file.

Nothing is deleted: the PNGs stay in the tree, only the image:: line changes. Say the word if you would rather I remove the superseded ones.

I will fix it according to your feedback. For the future, it is plain SVG so anyone can edit it.

With the help of AI

[BsAtHome]

I do like the update, in principle, but there are also some problems.

• The coloration of the boxes does not seem to have one specific meaning. I can't place a responsibility with the color.
• Some texts do not properly fit the box (like the one with "motor . encoder . limit switches..."). Alignment may also be improved when using SVG/style attributes. Especially when font replacement is done.
• The HAL layer includes both "components" and "drivers". Drivers are components that happen to talk to the hardware. Other components are generally intermediaries. Putting them side-by-side is a bit misleading. Also, the GUIs also have (non-realtime) components, but do communicate with RT components primarily using signals. This makes the picture more complex. Not sure how you should represent that. Maybe it requires multiple images.
• The text "absent from the original — yet it now carries every bit of hardware coupling" and "WHAT THE DIAGRAM GOT RIGHT" seem quite out of place.
• You have motmod in one box with many smaller boxes inside. However, motmod is loaded into HAL. What is the idea behind this? Are you going for hierarchy or logic? You seem to combine different strategies.
• You connect milltask to the nonRT-to-RT queues. However, you then do not connect that to motmod's motion controller, which is missing (on purpose?). However, you do have other modules, like homemod and kinematics as part of motmod, which are, well, user loadable (and user replaceable).

The image is called "architecture", but what is it exactly you are trying to visualize? Hierarchy? Logic? Communication? Container? The current form seems to do a blending of them all and confuses me a bit. Can you please explain your thoughts behind the layout and divisions?

[Zia-research]

Thanks. Pushed, three of your six fixed.

The colour key, the "what the diagram got right" panel and the "absent from the original" caption were leftovers from the errata sheet this was extracted from — the colours marked what my audit had corrected, not anything about LinuxCNC, which is why no responsibility maps to them. All gone. Dashed still means queue; colour now means nothing. The overflowing label was the only one, and is shortened.

Your last question is the right one. Honestly: the figure mixes containment, layering and dataflow at once. The purpose of this diagram is to replace the old one in the code documentation, after @grandixximo's input. That is where experience is needed, and my proposal is to shape the diagram from the review of people who know the code.

Which reader should this one serve? Your other three points follow from that, so I would rather have the answer before redrawing.

[BsAtHome]

Which reader should this one serve? Your other three points follow from that, so I would rather have the answer before redrawing.

That is the right question to ask. Where is this image in the documentation and what is being described in that part of the documentation. That is what you need to evaluate.

The document in question states at the top:

== Intended audience

This document is a collection of notes about the internals of LinuxCNC. It
is primarily of interest to developers, however much of the information
here may also be of interest to system integrators and others who are
simply curious about how LinuxCNC works. Much of this information is now
outdated and has never been reviewed for accuracy.

Therefore, the image must be representative of the technical architecture of the system where paths of communication and containment are clear. And, since this is a developer audience, any misrepresentations will have repercussions because they are misdirecting the (technically inclined) target audience.

That said, the quote above also clearly mentions much being outdated or inaccurate. Therefore, updating this image may not be very relevant if the actual text and content is not validated and corrected accordingly. So putting a lot of effort in this image would not be my first point of order without looking at the bigger picture first.

One more thing... The current color-scheme has very poor contrast IMO. Please consider the option that not all developers have young eyes or have perfect colour vision (f.ex. 8% of males have a red/green deficiency to some degree and contrast perception decreases with age).