Docs: Explain how the connections in the very first example in the README work

[DeflateAwning]

With no background on the schema, it's not clear at all what the connection paths mean. Even after checking the schema, it's not clear what the numbers are indexes to. Perhaps you could help explain that better?

[kvid]

Hi @DeflateAwning,
Please link to the documentation, example or tutorial you have read, but find unclear, and preferably cite the unclear parts or terms.

Since you mention the connection term, have you read the Connection sets documentation and the following two examples?

• Example 10 (simple Ethernet crossover cable)
• Example 14 (more advanced connections)

[DeflateAwning]

The "Connection sets" linked above in the syntax.md is not very clear and does not stand on its own well. What are pins? Can you use names instead of indexes? Where does it say pins/indexes start at 1 and not 0?

In the examples in the README, it would be helpful to have comments in the connections: part that explain what the numbers mean.

For example:

connections:
  -
    # Each number in the lists below is an index (starting from 1) into the Pin list for each connector.
    # First element of each list: connect X1's 5th Pin to W1 Pin 1 and X1 Pin 1.
    # Second element: connect X1's Pin 2 to W1 Pin 2, and X2 Pin 3.
    # ...
    - X1: [5,2,3]
    - W1: [1,2,3]
    - X2: [1,3,2]
  - # Connect the shield to X1's 5th net.
    - X1: 5
    - W1: s

[kvid]

@DeflateAwning wrote:

The "Connection sets" linked above in the syntax.md is not very clear and does not stand on its own well. What are pins? Can you use names instead of indexes? Where does it say pins/indexes start at 1 and not 0?

Quoted from the "Connection sets" linked above:

• <pin> may reference a pin's unique ID (as per the connector's pins attribute, auto-numbered from 1 by default) or its label (as per pinlabels).
• <wire> may reference a wire's number within a cable/bundle, its label (as per wirelabels) or, if unambiguous, its color.

See also the subsections Single connections and Multiple parallel connections within the same "Connection sets" section for more information about different combinations.

@DeflateAwning wrote:

In the examples in the README, it would be helpful to have comments in the connections: part that explain what the numbers mean.

For example:

connections:
  -
    # Each number in the lists below is an index (starting from 1) into the Pin list for each connector.
    # First element of each list: connect X1's 5th Pin to W1 Pin 1 and X1 Pin 1.
    # Second element: connect X1's Pin 2 to W1 Pin 2, and X2 Pin 3.
    # ...
    - X1: [5,2,3]
    - W1: [1,2,3]
    - X2: [1,3,2]
  - # Connect the shield to X1's 5th net.
    - X1: 5
    - W1: s

Thank you for this suggestion. For now, the demo 01 YAML is small and clean to enhance readability. Maybe a few small comments might improve the reader's understanding, but keep in mind that we already link to the syntax description just below the two demo cases.