Minor improvements to context diagram

[borine]

I've just noticed that the line break characters in the README mermaid diagram are no longer rendering correctly. I'm not sure how long ago that happened, nor if its just my local browser setup or some update to the github mermaid parser that has changed. The first commit here fixes them for me.

There is also a second commit to add a legend panel making clear the meaning of the colours. I cannot decide whether that actually improves the readability or not, so I put it in as a separate commit.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 70.23%. Comparing base (6e14215) to head (d2cba5f). Report is 1 commits behind head on master.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #728 +/- ## ========================================== + Coverage 70.18% 70.23% +0.05% ========================================== Files 96 96 Lines 15772 15772 Branches 2488 2488 ========================================== + Hits 11069 11077 +8 + Misses 4586 4578 -8 Partials 117 117 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[arkq]

I'm not sure how long ago that happened, nor if its just my local browser setup or some update to the github mermaid parser that has changed.

I've seen that also. Similar thing happened few months ago, but github has fixed it after a week or two.

How about using different shape for dbus (if possible)? Rectangles are used for Bluetooth and speaker, so one gets the impression that rectangles are for hardware. As for a legend, I think that it's OK to add it.

[borine]

How about using different shape for dbus (if possible)?

I wanted the dbus annotation to be a link label rather than a node in its own right, so I used the syntax defined here: https://mermaid.js.org/syntax/flowchart.html#text-on-links

There does not seem to be any way to control the shape or style of text on links. I will experiment a little with using nodes instead before deciding which is best.

[arkq]

I wanted the dbus annotation to be a link label rather than a node in its own right

OK, I see. I'm checking it on my phone right now, so maybe that's why I've got an impression that that's a node. If it's an edge label that's OK for me.

[arkq]

I've just checked it on a PC, and as the idea of adding a legend seems nice, the outcome is that now the diagram does not fit on a single screen (at least on my resolution). If you are OK with that I will skip the legend for now (maybe some verbose text in the README saying about the colors...). Also, I'd like to reorder components and maybe keep the layering tight as it was before (it's totally subjective, though; maybe because I got used to previous layout :D), e.g.:

flowchart TD
classDef external fill:#eee,stroke:#333,stroke-width:4px,color:black;
classDef bluealsa fill:#bbf,stroke:#333,stroke-width:4px,color:black;

A[Bluetooth Adapter] <--> B((bluetoothd<br/>daemon))
A <--> C((bluealsad daemon))
B <-- dbus --> C
C <-- dbus --> G((bluealsactl))
C <-- dbus --> D((bluealsa-aplay))
D --> E([ALSA libasound])
E --> K[Speakers]
C <-- dbus --> F((bluealsa<br/>ALSA plug-ins))
F <--> H([ALSA libasound])
H <--> I((ALSA<br/>applications))
C <-- dbus --> J(("other D-Bus<br/>clients"))
C <--> L((ALSA MIDI<br/>sequencer))
L <--> M([ALSA libasound])
M <--> N((ALSA MIDI<br/>application))

class A,B,E,H,I,J,K,L,M,N,Z external;
class C,D,F,G,Y bluealsa;

Also, maybe the MIDI part and "other D-Bus clients" could be swapped, so the controls will not cover the last node. However, placing D-Bus clients together seems more natural (from the design point of view). The MIDI part is kind of special because the ALSA MIDI sequence is in fact a kernel component (accessed via libsound).

[borine]

Moving the midi components to the left clears more space for the controls. Also perhaps a new shape for kernel components? For example:

flowchart TD
classDef external fill:#eee,stroke:#333,stroke-width:4px,color:black;
classDef bluealsa fill:#bbf,stroke:#333,stroke-width:4px,color:black;
A[Bluetooth Adapter] <--> B((bluetoothd<br/>daemon))
A <----> C((bluealsad daemon))
B <-- dbus --> C
C <--> D{{ALSA MIDI<br/>sequencer}}
D <--> E([ALSA libasound])
E <--> F((ALSA MIDI<br/>application))
C <-- dbus --> G((bluealsa<br/>ALSA plug-ins))
G <--> H([ALSA libasound])
H <--> I((ALSA<br/>applications))
C <-- dbus --> J((bluealsa-aplay))
J --> K([ALSA libasound])
K --> L[Speakers]
C <-- dbus --> M((bluealsactl))
C <-- dbus --> N(("other D-Bus<br/>clients"))
class A,B,D,E,F,H,I,K,L,N, external;
class C,G,J,M, bluealsa;