[feature] Force increased spacing and ordering for readability

[tim292stro]

So I'm actually trying to use this to describe a cable rework at my day job - and I have a doozy of a cable to describe:
HDMI_Sideband_Tap.txt

Which renders:

You can see that I did some wonky stuff here - there are a bunch of twisted pairs with drain-wires inside foil shields. To keep that context I broke each twisted pair and drain out to its own described "cable". However at the bottom of the rendered image, you will see that the "sideband" cable is being rendered above the 5th twisted pair (TPBlueSilver) This is kind of annoying, I'd like to be able to override the order that was picked somehow.

Another issue - is that where the wires between the cables and connectors overlap, the wires become untraceable. I'd like a way to force more space between objects so that drawn connecting wires are not stacking on top of each-other.

All in all, a pretty good first stab at a "production" documentation effort, I intend to evangelize this tool at my job a bit more as a result.

[kvid]

Thank you for sharing your project. After running Wirewiz and got the same result as you, I tried some tweaking of the intermediate .gv file to address your issues. Is this result (in low resolution to save space) closer to your expectations?

Tweaking of the HDMI_Sideband_Tap.gv file:

• Increased the ranksep from 2 to 6 to increase the separation between ranks (rank increases from left to right).
• Appended a cluster subgraph containing two nodes you wanted close to each other and specified a white frame color to hide the cluster subgraph frame.

4c4
<       graph [bgcolor=white fontname=arial nodesep=0.33 rankdir=LR ranksep=2]
---
>       graph [bgcolor=white fontname=arial nodesep=0.33 rankdir=LR ranksep=6]
74a75,79
>       subgraph cluster1 {
>               color=white
>               TPPinkSilver
>               TPBlueSilver
>       }

I then executed dot -Tpng -O _test/HDMI_Sideband_Tap_tweaked.gv to generate the .png file.

Such tweaking requires knowledge of the Graphviz syntax and dot tool. It's hard for Wireviz to know what needs such tweaking without the user specifying it. Would you recommend a new Wireviz optional feature to specify such low level tweaking from the YAML input to avoid manual modifications of the intermediate file followed by executing the dot tool manually?
Edit: Ideally, Wireviz should support hierarchical cables containing separately shielded groups of wires, etc., and I guess a future version will support this, but maybe not within the next month. In the mean time, would you find it useful to be able to tweak the diagram output from the YAML input, e.g. something like in the proposed extended syntax below?

connectors:
  ...
cables: 
  ...
connections: 
  ...
tweak:
  override:
    graph:
      ranksep: '6' # Larger horizontal separation between nodes
  append: |
    // Tweaking two cable nodes to keep close to each other
    subgraph cluster1 {
      color=white // Same as background to hide the surrounding frame
      TPPinkSilver
      TPBlueSilver
    }

[formatc1702]

This might be loosely related to #31 and #56, regarding grouping issues...
It would be nice to create nested bundles, and twisted pairs are also an important missing feature (#3).

I will think about other reasonable workarounds for your specific case... e.g. defining your cable with five shielded twisted pairs as a 15-wire cable, and using dual colors (only possible in the dev branch right now) and perhaps the notes of the cable to show the pairs... the shields would have to be rendered as "normal" wires for the time being, as multiple shields are not yet supported.

[tim292stro]

Thanks to both kvidf and fromatc1702 for your replies. kvidf, that spacing is exactly what I'm looking for, thanks for mapping out the path to that fix and the ordering! I can do that for now.

Yes, I agree that the user will have the most information about what needs to be grouped - so providing them some way to add that information would be useful. I've already chimed in on the heat-shrink/shielding issue Daniel mentioned above, my multiple cables work-around is a "what can be done today" usage. As an example in this cable (from first post), the cable bundle I have marked as sideband - the foil goes around all of the sub twisted pair bundles, with the SHELL shield being the foil shield drain wire.

I want to put out the idea of columnizing items if that's possible, the first graph was of just the starter unmodified cable - I wanted to show some of the rework additions being made to that cable.

What I did here was add a pin header and some rework wires that I wanted a tech to attach to the cable, and tangentially here I ran into another limitation with the Wireviz tool - I can't describe a splice at the cable, it must be at the connector. (wire to wire connections throw an error.

What I would have liked to do in place the "rework" cable in the same column as the "near" connector, and the pin header to the left of (in its own column) the near connector.

One work-around I've thought of, is abusing the connector cable definitions to make the rework cable a connector - as connector-to-connector connections are allowed under the tool's rules. But I haven't re-written the definition file yet (maybe later today when I have more time).

There was an intermediate step I don't have the picture here for (didn't save a copy in my revisions, but I'll re generate it later) - being able to override which side of a cable the wires come out of in the definition file looks like a good thing to think about. You will note in the above picture that wire #1 (white) in TPBlueSilver is only wired to one connector. If I had wired it to "pin header" the wiring did some "spaghetti gymnastics" to get to the connector and actually made it impossible to understand. Trying the rework wire cable made it easier to define length and colors for those wires, but here is where I ran into the limitation of not being able to connect cable to cable.

Imagine I want to graphically describe a pin-header rework to a technician for this cable:

Now imagine that the document to describe this rework is 6 pages long. I don't have to imagine it, I'm living it ;-)

[dallasbrittany]

I really feel like having the option to do straight lines would solve this problem. Even if there are a lot of lines, at least they would be traceable.

[kvid]

@tim292stro and @dproldan who reacted with thumbs up to my #174 (comment) (and others that might need such a feature) are invited to test my draft #215 PR and write a comment about their thoughts. This tweak feature is not limited to what I suggest above. It enables overriding any main attribute of any entry in the generated .gv file and appending any number of custom entries, e.g. nodes, edges, and subgraphs.

[kvid]

@tim292stro asked for wire to wire connections more than a year ago in this old issue. If you (or other visitors) still need this, please read all my suggestions in #270.

[martinrieder]

I really feel like having the option to do straight lines would solve this problem. Even if there are a lot of lines, at least they would be traceable.

This can simply be achieved by tweaking the splines attribute with the hints provided from the previous post referring to #270.

Increased the ranksep from 2 to 6 to increase the separation between ranks (rank increases from left to right).

Interestingly, the value of ranksep equals the number of parallel wires in this example. Perhaps this should be determined dynamically without manual tweaking in the future.

Besides this, the mclimit and minlen attributes are intended to influence the crossing algorithm.

What might also provide more eye-pleasing results, is a combination of virtual splices (as in #270) and simple wires (as in #376). These could additionally be grouped using clusters. Please see #275 as well in this context.