Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improving additional component display, BOM item numbers #224

Open
Tracked by #251
formatc1702 opened this issue Mar 20, 2021 · 17 comments
Open
Tracked by #251

Improving additional component display, BOM item numbers #224

formatc1702 opened this issue Mar 20, 2021 · 17 comments

Comments

@formatc1702
Copy link
Collaborator

formatc1702 commented Mar 20, 2021

I have been using WireViz at work quite a bit (work being the main reason I haven't had time to contribute to the project 😕) and I have noticed the treatment of "main" components and additional components is not as consistent as it maybe should be.

Note: The following thoughts might partially contradict previous opinions and decisions... this is what happens when theory meets practice.

Take the following sample file:

image

Source
connectors:
  X1:
    type: Plug
    pincount: 4
    pn: 123
    manufacturer: ACME
    mpn: ABC
    additional_components:
      -
        type: Crimp
        pn: 987
        manufacturer: ACME
        mpn: ZYX
        qty_multiplier: populated
      -
        type: Housing
        pn: 345
        manufacturer: OTHER

  X2:
    type: Receptacle
    pincount: 4
    pn: 234
    manufacturer: ACME
    mpn: DEF
    additional_components:
      -
        type: Crimp
        pn: 876
        manufacturer: ACME
        mpn: WVU


cables:
  W1:
    wirecount: 4
    color_code: DIN

connections:
  -
    - X1: [1-4]
    - W1: [1-4]
    - X2: [1-4]

Issues (easily solvable)

  • When using the image file on its own (without the exported BOM), part number info is not visible for additional components, although it might be desirable when, e.g. pasting the image file into a larger documentation document, without losing this information. It is probably more consistent to show info for additional components as well, even if it makes the node grow in size.
    • A global show_part_numbers parameter could optionally hide the subtype (unused in this example),part number and manufacturer+mpn fields if desired, to match the current information content of the additional components list.
      • for consistency, this should also affect the display of part numbers of the main components.
  • Additional components show their assigned item number in the image (#4 etc.), where as main components (connectors and cables) do not. It should be either both, or none.
    • How about a global option to show_bom_item_numbers that then applies to both?
  • Personally, I find the # symbol and the brackets in the additional component list visually jarring.. perhaps there is a more elegant solution
    • Maybe circled numbers? ⓪ ① ② ③
      They appear to go at least up to ㊿.
    • Another idea (though potentially cumbersome) would be to use a 1x1 table to make BOM numbers appear in a box.
      This is similar to "balloons" used in mechanical technical drawings
  • The additional components section within the component node could be a table with invisible column separators, to get a more even look when it starts getting more populated.
    • A blank first column for indentation could be a visual cue as to where the list starts and ends.
    • If a column is completely empty (e.g. no part numbers specified for any item in the list), it should be removed.

Other thoughts (discussion required)

  • Should user-defined BOM item numbers be allowed?
    E.g. someone might want connectors numbered from 1, cables numbered from 50, use letters for crimps, etc...
  • Is it cleaner to use some indented auto-numbering scheme for additional components?
    E.g. A X1 is item 1, then the crimp could be 1a, the housing 1b.
    • Obviously this is problematic when using the same crimp for various connectors with different pincounts, etc. I thought I would bring it up anyways

Both these ideas complicate the idea of using custom unicode characters for a nicer rendering of the item number. Please see this as food for thought, perhaps we can come up with a nice solution.

Here's a mockup of what X1 from the example above might look like using rounded table borders to create "balloons" for BOM item numbers. The issue of different widths for the BOM balloons is there, but not a total dealbreaker

image

Graphviz Source
graph {
// Graph generated by WireViz 0.3-dev
// https://github.com/formatc1702/WireViz
	graph [bgcolor=white fontname=arial nodesep=0.33 rankdir=LR ranksep=2]
	node [fillcolor=white fontname=arial shape=record style=filled]
	edge [fontname=arial style=bold]
	X1 [label=<
<table border="0" cellspacing="0" cellpadding="0">
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td balign="left">
     X1
   </td>
  </tr></table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td>
   <table border="0"><tr><td border="1" style="rounded">1</td></tr></table>
   </td>
   <td balign="left">P/N: 123</td>
   <td balign="left">ACME: ABC</td>
  </tr></table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td balign="left">Plug</td>
   <td balign="left">4-pin</td>
  </tr></table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1">
   <tr>
    <td port="p1r">1</td>
   </tr>
   <tr>
    <td port="p2r">2</td>
   </tr>
   <tr>
    <td port="p3r">3</td>
   </tr>
   <tr>
    <td port="p4r">4</td>
   </tr>
  </table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td balign="left">Additional components</td>
  </tr></table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td align="left" balign="left" sides="tbl">
    <table border="0"><tr><td border="1" style="rounded">4</td></tr></table>
   </td>
   <td align="left" balign="left" sides="tb">4x</td>
   <td align="left" balign="left" sides="tb">Crimp</td>
   <td align="left" balign="left" sides="tb">P/N: 987</td>
   <td align="left" balign="left" sides="tbr">ACME: ZYX</td>
  </tr>
  <tr>
   <td align="left" balign="left" sides="tbl">
    <table border="0"><tr><td border="1" style="rounded">6</td></tr></table>
   </td>
   <td align="left" balign="left" sides="tb">1x</td>
   <td align="left" balign="left" sides="tb">Housing</td>
   <td align="left" balign="left" sides="tb">P/N: 345</td>
   <td align="left" balign="left" sides="tbr">OTHER</td>
  </tr></table>
 </td></tr>
</table>
> fillcolor=white margin=0 shape=none style=filled]
	X2 [label=<
<table border="0" cellspacing="0" cellpadding="0">
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td balign="left">X2</td>
  </tr></table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td balign="left">P/N: 234</td>
   <td balign="left">ACME: DEF</td>
  </tr></table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td balign="left">Receptacle</td>
   <td balign="left">4-pin</td>
  </tr></table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1">
   <tr>
    <td port="p1l">1</td>
   </tr>
   <tr>
    <td port="p2l">2</td>
   </tr>
   <tr>
    <td port="p3l">3</td>
   </tr>
   <tr>
    <td port="p4l">4</td>
   </tr>
  </table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td balign="left">Additional components</td>
  </tr></table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td align="left" balign="left">1 x #5 (Crimp)</td>
  </tr></table>
 </td></tr>
</table>
> fillcolor=white margin=0 shape=none style=filled]
	edge [color="#000000:#ffffff:#000000"]
	X1:p1r:e -- W1:w1:w
	W1:w1:e -- X2:p1l:w
	edge [color="#000000:#895956:#000000"]
	X1:p2r:e -- W1:w2:w
	W1:w2:e -- X2:p2l:w
	edge [color="#000000:#00ff00:#000000"]
	X1:p3r:e -- W1:w3:w
	W1:w3:e -- X2:p3l:w
	edge [color="#000000:#ffff00:#000000"]
	X1:p4r:e -- W1:w4:w
	W1:w4:e -- X2:p4l:w
	W1 [label=<
<table border="0" cellspacing="0" cellpadding="0">
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td balign="left">W1</td>
  </tr></table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellpadding="3" cellborder="1"><tr>
   <td balign="left">4x</td>
  </tr></table>
 </td></tr>
 <tr><td>
  <table border="0" cellspacing="0" cellborder="0">
   <tr><td>&nbsp;</td></tr>
   <tr>
    <td>X1:1</td>
    <td>
     1:WH
    </td>
    <td>X2:1</td>
   </tr>
   <tr>
    <td colspan="3" border="0" cellspacing="0" cellpadding="0" port="w1" height="6">
     <table cellspacing="0" cellborder="0" border="0">
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#000000" border="0"></td></tr>
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#ffffff" border="0"></td></tr>
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#000000" border="0"></td></tr>
     </table>
    </td>
   </tr>
   <tr>
    <td>X1:2</td>
    <td>
     2:BN
    </td>
    <td>X2:2</td>
   </tr>
   <tr>
    <td colspan="3" border="0" cellspacing="0" cellpadding="0" port="w2" height="6">
     <table cellspacing="0" cellborder="0" border="0">
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#000000" border="0"></td></tr>
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#895956" border="0"></td></tr>
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#000000" border="0"></td></tr>
     </table>
    </td>
   </tr>
   <tr>
    <td>X1:3</td>
    <td>
     3:GN
    </td>
    <td>X2:3</td>
   </tr>
   <tr>
    <td colspan="3" border="0" cellspacing="0" cellpadding="0" port="w3" height="6">
     <table cellspacing="0" cellborder="0" border="0">
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#000000" border="0"></td></tr>
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#00ff00" border="0"></td></tr>
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#000000" border="0"></td></tr>
     </table>
    </td>
   </tr>
   <tr>
    <td>X1:4</td>
    <td>
     4:YE
    </td>
    <td>X2:4</td>
   </tr>
   <tr>
    <td colspan="3" border="0" cellspacing="0" cellpadding="0" port="w4" height="6">
     <table cellspacing="0" cellborder="0" border="0">
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#000000" border="0"></td></tr>
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#ffff00" border="0"></td></tr>
      <tr><td colspan="3" cellpadding="0" height="2" bgcolor="#000000" border="0"></td></tr>
     </table>
    </td>
   </tr>
   <tr><td>&nbsp;</td></tr>
  </table>
 </td></tr>
</table>
> fillcolor=white margin=0 shape=box style=""]
}

The same component, rendered with the proposed show_part_numbers attribute set to false, to keep the graphics simple, and allowing cross-referencing with the BOM:

image

And the same component, with show_bom_item_numbers set to false, to contain all the information within the graphic and eliminate the need for BOM export, and BOM item number balloons:

image

The only thing getting lost in this case would be any additional_bom_items definde outside of connectors and cables, but I see that as a separate issue.

Personally, I would vote for having show_bom_item_numbers = False and show_part_numbers = True by default. This way, no information is lost when using only the graphics output, where as BOM cross-referencing is left as an "advanced" feature.

@martinrieder
Copy link
Contributor

martinrieder commented Jun 4, 2024

@formatc1702 wrote:

I have been using WireViz at work quite a bit (work being the main reason I haven't had time to contribute to the project 😕) and I have noticed the treatment of "main" components and additional components is not as consistent as it maybe should be.

Note: The following thoughts might partially contradict previous opinions and decisions... this is what happens when theory meets practice.

Dito. I was going to argue that the additional_bom_items in the syntax are inconsistent withadditional_components, but then I found your thoughts here. I need to take a closer look at the suggestions, yet. Since some time has passed, you might have gained some more 'practical' insights... Any updates on your opinions and decisions? Are you still open for discussion on the items below?

Other thoughts (discussion required)

  • Should user-defined BOM item numbers be allowed?
    E.g. someone might want connectors numbered from 1, cables numbered from 50, use letters for crimps, etc...
  • Is it cleaner to use some indented auto-numbering scheme for additional components?
    E.g. A X1 is item 1, then the crimp could be 1a, the housing 1b.
    • Obviously this is problematic when using the same crimp for various connectors with different pincounts, etc. I thought I would bring it up anyways

I would say that the most consistent implementation is this:

  • Define a global section for additional_components, which contains an unordered list, similar to connectors and cables
  • Use designators for each item, making sure they are unique and not in conflict with connectors and cables
  • Reference to these designators from both cables and connectors (or any other items)

Using the YAML lists (arrays) for referencing designators would align the syntax between additional_components and connections on global scope.

The only thing getting lost in this case would be any additional_bom_items definde outside of connectors and cables, but I see that as a separate issue

As stated above, I would at least rename additional_bom_items into additional_components. The difference is that you are suggesting to keep them in local scope only, while I am proposing the opposite.

Personally, I would vote for having show_bom_item_numbers = False and show_part_numbers = True by default. This way, no information is lost when using only the graphics output, where as BOM cross-referencing is left as an "advanced" feature.

I would like to discuss an implementation that would also work for cables. Keep in mind that there are two common use cases:

  • Connector crimps or single wire seals that need to be multiplied by pin count
  • Wire tubing or sleeves that need to be multiplied with cable length

The latter might cause confusion because wire count is an alternative multiplication factor, aa suggested in #222.

qty_multiplier: populated

Please also check the following issues related to this:

@kvid
Copy link
Collaborator

kvid commented Jun 12, 2024

Local Designators

I suggest keeping:

  • The BOM item numbering strictly numeric, and auto-assigned after BOM de-duplication.
  • A global additional_bom_items and local additional_components for each connector/cable.

However, I suggest we add a local designator suffix for each additional_components item, e.g. auto-assigned numeric (with some separator character between the global connector/cable designator and the local designator suffix) unless perhaps optionally specified differently for each item. We must require such local designators to be unique within the local scope (for each connector/cable), and the combined designators (e.g. X1-1, X1-2, ...) must be globally unique so the user cannot specify e.g. a global designator X1-2 that conflicts with the local designator suffix -2 to a global connector designator X1.

In addition, all items in the designators attribute of each additional_bom_items entry must also be included in the global scope together with connector/cable designators in the uniqueness checks described above.

When adding additional_components entries to the global BOM, the combined designator (as described above) should be used instead of only the connector/cable designator as today. Then it'll be easier to precisely identify the origins of such BOM entries.

The short designators suggested in #350 (comment) should then also be unique within the same local scope I suggest above, so such short items could be automatically included among the additional_components of the same connector, both in the local list inside the connector node, and in the global BOM, as I very briefly suggested in #369 (comment)

Update: As an alternative to the latter, we could let the user specify details of loops/shorts entries as ordinary additional_components entries with explicit local designators when needed, and use these explicit local designators in a simpler loops/shorts syntax (also allowing entries with no matching additional_components entry):

X1:
  loops:
    L1: [3, 11]
    L2: [6, 12]
  internal_shorts:
    Sh1: [1,5,7]
    Sh2: [2,8,10]
  additional_components:
    Sh1:
      color: PK
      mpn: 42A5Z42
      type: 3 pin Short ov er 5 pins, name of the part
    L2:
      color: GR
      qty: 10
      unit: mm
      type: Wire, 24 AWG
  • We would need to add an optional color attribute to entries of additional_components that should be appended to the description of the global BOM entry.
  • Any additional_components with list entries (as today) should get auto-assigned local designators unless we allow an optional designator attribute to be specified.
  • Any loops/shorts with list entries (as today) should get auto-assigned hidden local internal designators that don't match any other local designator in the same local scope.
  • We could also allow that loops/shorts entries with a local designator that doesn't match any additional_components entry, but match a known color (or optionally a combination of multiple known colors for loops) to use such local designators as their colors when rendering the diagram. Such a functionality would match the suggested PR Loops by pin or pinlabel, loop color #288.

@tobiasfalk
Copy link

tobiasfalk commented Jun 13, 2024

@kvid
Loops and shorts are often done with wires and therefore can not only have a color(for the isolation) bit also a gauge and so on, that also means that someone may wants to have the short in the list with all the wires.

@kvid
Copy link
Collaborator

kvid commented Jun 13, 2024

@tobiasfalk wrote:

@kvid Loops and shorts are often done with wires

I agree to that. 😄

and therefore can not only have a color(for the isolation) bit also a gauge and so on,

I'm not sure I interprete this part correctly. Do you mean "and therefore always need to specify more attributes than only color and gauge"?

If so, then I agree in most cases, but I've also seen very simple use cases where the diagram only is used to show the electrical connections, and has no needs for more details than perhaps different colors for readability.

that also means that someone may wants to have the short in the list with all the wires.

What "list with all the wires" do you mean?

Is it the global BOM? If so, then I agree in most cases, except in very simple use cases, like what I describe above, where a BOM is not needed at all.

Is it the list of wires in a bundle? If so, then I wonder how such a bundle should be shown in relation to the connector having the loops?

Do you mean a bundle node close to the connector with the loops drawn between these two nodes? If so, then I'm worried it will most often look a bit ugly because dot is not good at drawing circular graphs.

Do you mean the wire list of a bundle embedded into the connector node, e.g. just below the pin list, and loops at both sides of the connector to connect the pins to each end of the wire entry in such a wire list? If so, then it might work out well, except I'm a bit worried about readability when the number of loops increases.

@tobiasfalk
Copy link

@kvid
What I mean with the same list as the wires is that when you define a W1 with the gauge of .5mm^2 and also have a short with the same gauge, then one may want it in the same BOM entry for total wire length

@tobiasfalk
Copy link

Also the color can either be only for the purpose of differentiation bur could also be used for defining the color of the wire isolation

@martinrieder
Copy link
Contributor

martinrieder commented Jun 13, 2024

@kvid wrote:

We must require such local designators to be unique within the local scope (for each connector/cable), and the combined designators (e.g. X1-1, X1-2, ...) must be globally unique so the user cannot specify e.g. a global designator X1-2 that conflicts with the local designator suffix -2 to a global connector designator X1.

Going by the Graphviz dot language specification, the ID could contain any character when it is a quoted string. The exception is:

In addition, the content must be legal XML, so that the special XML escape sequences for ", &, <, and > may be necessary in order to embed these characters in attribute values or raw text.

Therefore, I suggest to put the auto-assigned numbering into brackets, which would also closely resemble the balloon numbers discussed above:
X1<1>, X1<2>, X1<3>, ...
The syntax would assure uniqueness, because users would need to explcitly use escape sequences if they wanted a designator like this.

EDIT: Adapting the example above, it should be possible to allow some flexibility:

X1:
  loops:
    - L1: [3, 11]      # simple loop, no additional components
    - L2: [6, 12]      # referenced below
  internal_shorts:
    # Sh1: [1,5,7]    # entirely moved below, no reference
    - Sh2: [2,8,10]
    -                 # unnamed list item, auto-generated X1<1>
      [3,9,11]         
  additional_components:
    - Sh1:            # named list item (added "-")
      internal_shorts: [1,5,7]
      color: PK
      mpn: 42A5Z42
      type: 3 pin Short over 5 pins
    - Sh1.Sh2        # copy some attributes from above?
    - L2:             # named reference for "L2: [6, 12]" above
      color: GR
      qty: 10        # should there be an alias "length:" ???
      unit: mm
      type: Wire, 24 AWG
    -                # unnamed list item (auto-assign to X1<2>)
      loops: [7, 14] # implies that it is not an "internal_short"
      color: BK

Note that todays's syntax has these items listed as an array (with dashes!). We should keep it this way to support the auto-generated numbering in a defined order, even if the list contains some named designators.

@tobiasfalk
Copy link

Why not just add one ore multiple shorts or loops to a additional component, and I we should not put the pin definition in to the additional component but keep it separate.

additional_components:
    - Sh1, Sh2, L1
      color: PK
      mpn: 42A5Z42
      type: 3 pin Short ov er 5 pins, name of the part

Also for shorts and loops wit wire/cable I think somthing like additional_cable would be good, this is practically additional_components but with the type Cable

@martinrieder
Copy link
Contributor

martinrieder commented Jun 13, 2024

@tobiasfalk wrote:

Why not just add one ore multiple shorts or loops to a additional component, and I we should not put the pin definition in to the additional component but keep it separate.

Also possible, but please add some [] brackets to indicate an array:

  internal_shorts:
    - Sh1: [1,5,7]
    - Sh2: [2,8,10]
  additional_components:
    - [Sh1, Sh2]
      color: PK
      mpn: 42A5Z42
      type: 3 pin Short over 5 pins

EDIT: I think that a discussion about implementing loops or shorts in a specific way is out of scope for this issue. Please try too keep it generic about additional_components and additional_bom_items.

Daniel @formatc1702, please provide an update on your thoughts from the original issue description.

@kvid
Copy link
Collaborator

kvid commented Jun 13, 2024

@tobiasfalk wrote:

@kvid What I mean with the same list as the wires is that when you define a W1 with the gauge of .5mm^2 and also have a short with the same gauge, then one may want it in the same BOM entry for total wire length

Yes, that is normal existing behavior. I called it "BOM de-duplication" in my last comment. To obtain a match between a wire in additional_components and the same wire in a bundle, we need all these properties of the BOM entries to be equal: ("description", "unit", "pn", "manufacturer", "mpn", "supplier", "spn")

"description" of a bundle wire = Wire, type, gauge, color
"description" of an additional component = type, subtype (I also suggested above to append color here)

That means if "type, subtype" of an additional component == "Wire, type, gauge" of a connector, then they match and they will be de-duplicated if also all remaining properties are equal. In my example above, I used type: Wire, 24 AWG to obtain this.

@tobiasfalk wrote:

Also the color can either be only for the purpose of differentiation bur could also be used for defining the color of the wire isolation

Yes, I don't see any conflict between this and my suggestions above.

@kvid
Copy link
Collaborator

kvid commented Jun 13, 2024

@tobiasfalk and @martinrieder - All your YAML input suggestions contain syntax errors. This is an example of an online YAML parser where you can test your syntax: https://codebeautify.org/yaml-parser-online

Each additional_components must either have only list items, or only key/value items. Trying to mix will result in syntax error.

Why do you want a list of local designators for an entry? If you want some entries to be a copy of another entry, you can use inheritance.

Please explain your motivation for suggesting these strange non-YAML syntax entries, and we might find alternatives that are allowed as YAML input.

@martinrieder
Copy link
Contributor

Sorry, I have put the : back to where they were in the example above and now it passes the checks. I used https://www.yamllint.com/ instead, which seems to use a different parser than the one you suggested...
The suggestion to use an array of designators is indeed a bit odd. It is inspired by the way that multiple arrows can be defined in the connections list. I guess we do not really need this special case.

@kvid
Copy link
Collaborator

kvid commented Jun 13, 2024

Be aware that https://www.yamllint.com/ seems to use YAML v1.2 which is different from v1.1 used by WireViz.

@tobiasfalk
Copy link

additional_components:
    - [Sh1, Sh2, L1]:
      color: PK
      mpn: 42A5Z42
      type: 3 pin Short ov er 5 pins, name

This past the test, the idea behind it is to not have to type the same thing multiple times

@martinrieder
Copy link
Contributor

martinrieder commented Jun 14, 2024

Be aware that https://www.yamllint.com/ seems to use YAML v1.2 which is different from v1.1 used by WireViz.

Thanks. I could not find that info directly on the website. This is another reason for #223 and #348.
The discussion is getting off topic if we are to discuss missing characters. It is the idea of (auto-)assigning designators to specific features that should be discussed.

I prefer the original idea with ballooned numbers, so I strongly recommend using lists (arrays) to make that possible.

@kvid your proposal in #224 (comment) was thereby simply missing the dashes. They are also present in the current WireViz syntax. You are welcome to discuss the specifics of YAML 1.1 vs. 1.2 in the other issues.

@martinrieder
Copy link
Contributor

martinrieder commented Jun 15, 2024

@kvid wrote:

Each additional_components must either have only list items, or only key/value items. Trying to mix will result in syntax error.

Why do you want a list of local designators for an entry? If you want some entries to be a copy of another entry, you can use inheritance.

Please explain your motivation for suggesting these strange non-YAML syntax entries, and we might find alternatives that are allowed as YAML input.

I agree with you that the proposed syntax is a bit strange from the standards perspective, although I would argue that it could be realized in perfectly valid YAML syntax. Thanks for pointing out inheritance.

The point is that you might define multiple shorts or loops with dedicated additional components, similar to how you would do with pins. There might be connectors that contain different types of contacts and it would be great to have an option for listing their crimps. The latter was recently requested in #372 by @ElPi23.

I made a proposal to use a reference key in #369 (comment) for the purpose of @tobiasfalk's Jumper implementation.

connectors:
  X1:
    pinlabels: [GND, VCC, RX, TX, GND, VCC, GND]
    shorts:  # see #369
      - SH1: [1, 5, 7]  
      - SH2: [2, 6]
    additional_components:
      - reference: [SH1, SH2] 
        color: PK
        
      - reference: [GND, VCC] # pinlabels not unique 
        type: crimp1

      - reference: [3, 4] # pin names are unique 
        type: crimp2

@kvid Would this be closer to the YAML syntax that you expect?

@ferdnyc
Copy link

ferdnyc commented Jun 16, 2024

@martinrieder

Going by the Graphviz dot language specification, the ID could contain any character when it is a quoted string. The exception is:

In addition, the content must be legal XML, so that the special XML escape sequences for ", &, <, and > may be necessary in order to embed these characters in attribute values or raw text.

Therefore, I suggest to put the auto-assigned numbering into brackets, which would also closely resemble the balloon numbers discussed above: X1<1>, X1<2>, X1<3>, ... The syntax would assure uniqueness, because users would need to explcitly use escape sequences if they wanted a designator like this.

Oh, no, that's a misinterpretation. The restrictions you quoted were for HTML-like strings, which have to be surrounded by < and > in their entirety, instead of being quoted.

graph G {
  // In other words, both of these are invalid graphviz:
  X1<1> [color=red];        // Creates 2 nodes, "X1" and "1"
  X1&lt;1&gt; [color=red];  // Syntax error
  // But this is perfectly legal:
  "X1<1>" [color=green shape=box];
  // (And this, which is the form that note was describing):
  <X1&lt;1&gt;> [color=blue shape=box];
}

So, if you're using quoted strings, there's no restriction on including < or > in the contents, and therefore no restrictions on users entering names like X1<1>.

If you're using HTML-like strings for node names... well, I wouldn't recommend that, because it gets ugly fast. (And wouldn't really solve the problem, because you'd end up with a user who wanted to use a reserved character like & or > in their labels, so you'd end up having to HTML-escape their input anyway.)

Better, I think, to just surround the user-provided content with some characters — in all uses — to ensure uniqueness.

For example:

  • Global X1 combined with local designator 2:
    • Store global ID as [X1] (with X1 in the label)
    • Store local designator as [X1].2
    • A global X1.2 would become [X1.2] and [X1.2].2

Even if the user creates a global ID [X1].2, it'll be stored as [[X1].2], and the local designator will be [[X1].2].2, so there are no collisions possible. (It just requires care when parsing those names, if it ever comes to that.)

But unless you're modifying the user's content in some way when storing it, there's always a chance they can enter a string that, unmodified, collides with IDs generated from other unmodified names.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants