From a6504fd6c9c7b2ea2bb69a40038009ce3d4135dd Mon Sep 17 00:00:00 2001
From: Martin Rieder <74277074+martinrieder@users.noreply.github.com>
Date: Tue, 2 Jul 2024 01:56:12 +0200
Subject: [PATCH] Correct indentation and <...> brackets

---
 docs/syntax.md | 344 ++++++++++++++++++++++++-------------------------
 1 file changed, 171 insertions(+), 173 deletions(-)

diff --git a/docs/syntax.md b/docs/syntax.md
index d34813a..25e1fc8 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -31,150 +31,153 @@ Their respective attribute assignments need to be indented using space character
 Make sure they are aligned correctly in the document hierarchy, i.e. by two spaces for each level!
 
 ```yaml
-connectors:  # dictionary of all used connectors
-  <str>   :    # unique connector designator/name
-    ...          # connector attributes (see below)
-  <str>   :
-    ...
-  ...
+connectors:        # dictionary of all used connectors
+  <str>:           # unique connector designator/name
+    <str>: <...>   # connector attributes (see below)
+  <str>:
+    <str>: <...>
+  <...>  
 
-cables:      # dictionary of all used cables and wires
-  <str>   :    # unique cable designator/name
-    ...          # cable attributes (see below)
-  <str>   :
-    ...
-  ...
+cables:            # dictionary of all used cables and wires
+  <str>:           # unique cable designator/name
+    <str>: <...>   # cable attributes (see below)
+  <str>:
+    <str>: <...>
+  <...>
 
-connections:  # list of all connections to be made
-              # between cables and connectors
+connections:  # list of all connection sets (see below)
   -
-    ...         # connection set (see below)
+    - <...>         # <connector> or <cable>
+    - <...>         # <cable>     or <connector> 
   -
-    ...
-  ...
+    - <...>
+  <...>
 
 additional_bom_items:  # custom items to add to BOM
-  - <bom-item>           # BOM item (see below)
-  ...
+  - <bom-item>         # BOM item (see below)
+    <str>: <...>
 
-metadata:  # dictionary of meta-information describing the harness
-  <key>   : <value>  # any number of key value pairs (see below)
-  ...
+metadata:         # dictionary of meta-information describing the harness
+  <key>: <value>  # any number of key value pairs (see below)
+  <...>
 
-options:  # dictionary of common attributes for the whole harness
-  <str>   : <value>  # optional harness attributes (see below)
-  ...
+options:          # dictionary of common attributes for the whole harness
+  <str>: <value>  # optional harness attributes (see below)
+  <...>
 
-tweak:  # optional tweaking of .gv output
-  ...
+tweak:            # optional tweaking of .gv output
+  <...>
 ```
+
 ## Connector attributes
 
 ```yaml
-<str>   :  # unique connector designator/name
-  # general information about a connector (all optional)
-  type: <str>   
-  subtype: <str>   
-  color: <color>  # see below
-  image: <image>  # see below
-  notes: <str>   
+connectors:
+  <str>:  # unique connector designator/name
+    # general information about a connector (all optional)
+    type: <str>   
+    subtype: <str>   
+    color: <color>  # see below
+    image: <image>  # see below
+    notes: <str>   
 
-  # product information (all optional)
-  ignore_in_bom: <bool>  # if set to true the connector is not added to the BOM
-  pn: <str>              # [internal] part number
-  manufacturer: <str>    # manufacturer name
-  mpn: <str>             # manufacturer part number
-  supplier: <str>        # supplier name
-  spn: <str>             # supplier part number
-  additional_components: # additional components
-    - <additional-component> # additional component (see below)
+    # product information (all optional)
+    ignore_in_bom: <bool>  # if set to true the connector is not added to the BOM
+    pn: <str>              # [internal] part number
+    manufacturer: <str>    # manufacturer name
+    mpn: <str>             # manufacturer part number
+    supplier: <str>        # supplier name
+    spn: <str>             # supplier part number
+    additional_components: # additional components
+      - <additional-component> # additional component (see below)
 
-  # pinout information
-  # at least one of the following must be specified
-  pincount: <int>    # if omitted, is set to length of specified list(s)
-  pins: <List>       # if omitted, is autofilled with [1, 2, ..., pincount]
-  pinlabels: <List>  # if omitted, is autofilled with blanks
+    # pinout information
+    # at least one of the following must be specified
+    pincount: <int>    # if omitted, is set to length of specified list(s)
+    pins: <List>       # if omitted, is autofilled with [1, 2, ..., pincount]
+    pinlabels: <List>  # if omitted, is autofilled with blanks
 
-  # pin color marks (optional)
-  pincolors: <List>  # list of colors to be assigned to the respective pins;
-                     # if list length is lower than connector pinout,
-                     # no color marks will be added to remaining pins
+    # pin color marks (optional)
+    pincolors: <List>  # list of colors to be assigned to the respective pins;
+                      # if list length is lower than connector pinout,
+                      # no color marks will be added to remaining pins
 
-  # rendering information (all optional)
-  bgcolor: <color>       # Background color of diagram connector box
-  bgcolor_title: <color> # Background color of title in diagram connector box
-  style: <style>         # may be set to simple for single pin connectors
-  show_name: <bool>      # defaults to true for regular connectors,
-                         # false for simple connectors
-  show_pincount: <bool>  # defaults to true for regular connectors
-                         # false for simple connectors
-  hide_disconnected_pins: <bool>  # defaults to false
+    # rendering information (all optional)
+    bgcolor: <color>       # Background color of diagram connector box
+    bgcolor_title: <color> # Background color of title in diagram connector box
+    style: <style>         # may be set to simple for single pin connectors
+    show_name: <bool>      # defaults to true for regular connectors,
+                          # false for simple connectors
+    show_pincount: <bool>  # defaults to true for regular connectors
+                          # false for simple connectors
+    hide_disconnected_pins: <bool>  # defaults to false
 
-  # loops
-  loops: <List>  # every list item is itself a list of exactly two pins
-                 # on the connector that are to be shorted
+    # loops
+    loops: <List>  # every list item is itself a list of exactly two pins
+                  # on the connector that are to be shorted
 ```
 
 ## Cable attributes
 
 ```yaml
-<str>   :  # unique cable designator/name
-  # general information about a connector (all optional)
-  category: <category>  # may be set to bundle;
-                        # generates one BOM item for every wire in the bundle
-                        # instead of a single item for the entire cable;
-                        # renders with a dashed outline
-  type: <str>   
-  gauge: <int/float/str>  # allowed formats:
-                          # <int/float> mm2  is understood
-                          # <int> AWG        is understood
-                          # <int/float>      is assumed to be mm2
-                          # <str>            custom units and formats are allowed
-                          #                  but unavailable for auto-conversion
-  show_equiv: <bool>      # defaults to false; can auto-convert between mm2 and AWG
-                          # and display the result when set to true
-  length: <int/float>[ <unit>]  # <int/float> is assumed to be in meters unless <unit> is specified
-                                # e.g. length: 2.5 -> assumed to be 2.5 m
-                                # or   length: 2.5 ft -> "ft" is used as the unit
-                                # Units are not converted during BOM generation;
-                                # different units result in separate BOM entries.
-  shield: <bool/color>  # defaults to false
-                        # setting to true will display the shield as a thin black line
-                        # using a color (see below) will render the shield in that color
-                        # A shield can be accessed by using 's' as the wire ID
-  color: <color>  # see below
-  image: <image>  # see below
-  notes: <str>   
+cables:
+  <str>:  # unique cable designator/name
+    # general information about a connector (all optional)
+    category: <category>  # may be set to bundle;
+                          # generates one BOM item for every wire in the bundle
+                          # instead of a single item for the entire cable;
+                          # renders with a dashed outline
+    type: <str>   
+    gauge: <int/float/str>  # allowed formats:
+                            # <int/float> mm2  is understood
+                            # <int> AWG        is understood
+                            # <int/float>      is assumed to be mm2
+                            # <str>            custom units and formats are allowed
+                            #                  but unavailable for auto-conversion
+    show_equiv: <bool>      # defaults to false; can auto-convert between mm2 and AWG
+                            # and display the result when set to true
+    length: <int/float>[ <unit>]  # <int/float> is assumed to be in meters unless <unit> is specified
+                                  # e.g. length: 2.5 -> assumed to be 2.5 m
+                                  # or   length: 2.5 ft -> "ft" is used as the unit
+                                  # Units are not converted during BOM generation;
+                                  # different units result in separate BOM entries.
+    shield: <bool/color>  # defaults to false
+                          # setting to true will display the shield as a thin black line
+                          # using a color (see below) will render the shield in that color
+                          # A shield can be accessed by using 's' as the wire ID
+    color: <color>  # see below
+    image: <image>  # see below
+    notes: <str>   
 
-  # product information (all optional)
-  ignore_in_bom: <bool>  # if set to true the cable or wires are not added to the BOM
-  pn: <str>              # [internal] part number
-  manufacturer: <str>    # manufacturer name
-  mpn: <str>             # manufacturer part number
-  supplier: <str>        # supplier name
-  spn: <str>             # supplier part number
-  additional_components: # additional components
-    - <additional-component> # additional component (see below)
+    # product information (all optional)
+    ignore_in_bom: <bool>  # if set to true the cable or wires are not added to the BOM
+    pn: <str>              # [internal] part number
+    manufacturer: <str>    # manufacturer name
+    mpn: <str>             # manufacturer part number
+    supplier: <str>        # supplier name
+    spn: <str>             # supplier part number
+    additional_components: # additional components
+      - <additional-component> # additional component (see below)
 
-  # conductor information
-  # the following combinations are permitted:
-  # wirecount only          no color information is specified
-  # colors only             wirecount is inferred from list length
-  # wirecount + color_code  colors are auto-generated based on the specified
-  #                         color code (see below) to match the wirecount
-  # wirecount + colors      colors list is trimmed or repeated to match the wirecount
-  wirecount: <int>
-  colors: <List>     # list of colors (see below)
-  color_code: <str>  # one of the supported cable color codes (see below)
+    # conductor information
+    # the following combinations are permitted:
+    # wirecount only          no color information is specified
+    # colors only             wirecount is inferred from list length
+    # wirecount + color_code  colors are auto-generated based on the specified
+    #                         color code (see below) to match the wirecount
+    # wirecount + colors      colors list is trimmed or repeated to match the wirecount
+    wirecount: <int>
+    colors: <List>     # list of colors (see below)
+    color_code: <str>  # one of the supported cable color codes (see below)
 
-  wirelabels: <List>  # optional; one label for each wire
+    wirelabels: <List>  # optional; one label for each wire
 
-  # rendering information (all optional)
-  bgcolor: <color>          # Background color of diagram cable box
-  bgcolor_title: <color>    # Background color of title in diagram cable box
-  show_name: <bool>         # defaults to true
-  show_wirecount: <bool>    # defaults to true
-  show_wirenumbers: <bool>  # defaults to true for cables; false for bundles
+    # rendering information (all optional)
+    bgcolor: <color>          # Background color of diagram cable box
+    bgcolor_title: <color>    # Background color of title in diagram cable box
+    show_name: <bool>         # defaults to true
+    show_wirecount: <bool>    # defaults to true
+    show_wirenumbers: <bool>  # defaults to true for cables; false for bundles
 
 ```
 
@@ -197,7 +200,7 @@ connections:
     - <component>    # Each connection set is itself a list of items
     - <component>    # Items must alternatingly belong to the connectors and cables sections
                      # Arrows may be used instead of cables
-    -...
+    - <...>
 
   - # example (single connection)
     - <connector>: <pin>   # attach one pin of the connector
@@ -225,7 +228,7 @@ connections:
                                             # use double line arrow (==, <==, <==>, ==>)
     - <connector>
 
-  ...    
+  <...>    
 ```
 
 ### Single connections
@@ -293,7 +296,7 @@ connections:
     - <arrow>      # ==, <==, <==> or ==>
     - <connector>
   -
-    - ...
+    - <...>
     - <connector>: [<pin>, ...]  # designator and pinlist (pinlist is ignored)
                                  # useful when combining arrows and wires
     - <arrow>                    # ==, <==, <==> or ==>
@@ -359,7 +362,7 @@ Even if a component is not connected to any other components, it must be mention
 ```yaml
 connectors:
   X1:  # this connector will not be connected to any other components
-    ... 
+    <...> 
 
 connections:
 -
@@ -373,7 +376,7 @@ If any component is defined in the `connectors` or `cables` sections but not ref
 ## Metadata entries
 
 ```yaml
-  # Meta-information describing the harness
+metadata:  # Meta-information describing the harness
 
   # Each key/value pair replaces all key references in
   # the HTML output template with the belonging value.
@@ -388,8 +391,8 @@ See [HTML Output Templates](../src/wireviz/templates/) for how metadata entries
 ## Options
 
 ```yaml
-  # Common attributes for the whole harness.
-  # All entries are optional and have default values.
+options:  # Common attributes for the whole harness.
+          # All entries are optional and have default values.
 
   # Background color of diagram and HTML output
   bgcolor: <color>             # Default = 'WH'
@@ -426,51 +429,52 @@ See [HTML Output Templates](../src/wireviz/templates/) for how metadata entries
 
 ## BOM items and additional components
 
-Connectors (both regular, and auto-generated), cables, and wires of a bundle are automatically added to the BOM,
-unless the `ignore_in_bom` attribute is set to `true`.
+Connectors (both regular, and auto-generated), cables, and wires of a bundle are automatically added to the BOM, unless the `ignore_in_bom` attribute is set to `true`.
 Additional items can be added to the BOM as either part of a connector or cable or on their own.
 
 Parts can be added to a connector or cable in the section `<additional-component>` which will also list them in the graph.
 
 ```yaml
--
-  type: <str>  # type of additional component
-  # all the following are optional:
-  subtype: <str>  # additional description (only shown in bom)
-  qty: <int/float>  # qty to add to the bom (defaults to 1)
-  qty_multiplier: <str>  # multiplies qty by a feature of the parent component
-                  # when used in a connector:
-                  # pincount         number of pins of connector
-                  # populated        number of populated positions in a connector
-                  # unpopulated      number of unpopulated positions
-                  # when used in a cable:
-                  # wirecount        number of wires of cable/bundle
-                  # terminations     number of terminations on a cable/bundle
-                  # length           length of cable/bundle
-                  # total_length     sum of lengths of each wire in the bundle
-  unit: <str>
-  pn: <str>            # [internal] part number
-  manufacturer: <str>  # manufacturer name  
-  mpn: <str>           # manufacturer part number
-  supplier: <str>      # supplier name  
-  spn: <str>           # supplier part number
-  bgcolor: <color>     # Background color of entry in diagram component box
+additional_components:
+  -
+    type: <str>  # type of additional component
+    # all the following are optional:
+    subtype: <str>  # additional description (only shown in bom)
+    qty: <int/float>  # qty to add to the bom (defaults to 1)
+    qty_multiplier: <str>  # multiplies qty by a feature of the parent component
+                    # when used in a connector:
+                    # pincount         number of pins of connector
+                    # populated        number of populated positions in a connector
+                    # unpopulated      number of unpopulated positions
+                    # when used in a cable:
+                    # wirecount        number of wires of cable/bundle
+                    # terminations     number of terminations on a cable/bundle
+                    # length           length of cable/bundle
+                    # total_length     sum of lengths of each wire in the bundle
+    unit: <str>
+    pn: <str>            # [internal] part number
+    manufacturer: <str>  # manufacturer name  
+    mpn: <str>           # manufacturer part number
+    supplier: <str>      # supplier name  
+    spn: <str>           # supplier part number
+    bgcolor: <color>     # Background color of entry in diagram component box
 ```
 
 Alternatively items can be added to just the BOM by putting them in the section `<bom-item>` above.
 
 ```yaml
--
-  description: <str>              
-  # all the following are optional:
-  qty: <int/float>  # qty to add to the bom (defaults to 1)
-  unit: <str>   
-  designators: <List>
-  pn: <str>            # [internal] part number
-  manufacturer: <str>  # manufacturer name  
-  mpn: <str>           # manufacturer part number
-  supplier: <str>      # supplier name  
-  spn: <str>           # supplier part number
+additional_bom_items:
+  -
+    description: <str>              
+    # all the following are optional:
+    qty: <int/float>  # qty to add to the bom (defaults to 1)
+    unit: <str>   
+    designators: <List>
+    pn: <str>            # [internal] part number
+    manufacturer: <str>  # manufacturer name  
+    mpn: <str>           # manufacturer part number
+    supplier: <str>      # supplier name  
+    spn: <str>           # supplier part number
 ```
 
 ## GraphViz tweaking (experimental)
@@ -479,23 +483,17 @@ This feature is experimental and might change or be removed in future versions.
 
 
 ```yaml
-  # Optional tweaking of the .gv output.
-  # This feature is experimental and might change
-  # or be removed in future versions.
+tweak:   # Optional tweaking of the .gv output. 
 
   override:  # dict of .gv entries to override
-    # Each entry is identified by its leading string
-    # in lines beginning with a TAB character.
-    # The leading string might be in "quotes" in
-    # the .gv output. This leading string must be
+    # Each entry is identified by its leading string in lines beginning with a TAB character.
+    # The leading string might be in "quotes" in the .gv output. This leading string must be
     # followed by attributes in [square brackets].
-    # Entries with an attribute containing HTML are
-    # not supported.
+    # Entries with an attribute containing HTML are not supported.
     <str>:  # leading string of .gv entry
-      <str> : <str/null>  # attribute and its new value
-      # Any number of attributes can be overridden
-      # for each entry. Attributes not already existing
-      # in the entry will be appended to the entry.
+      <str>: <str/null>  # attribute and its new value
+      # Any number of attributes can be overridden for each entry. 
+      # Attributes not already existing in the entry will be appended to the entry.
       # Use null as new value to delete an attribute.
 
   append: <str/list> # string or list of strings to append to the .gv output
@@ -630,4 +628,4 @@ See [yaml-multiline.info](https://yaml-multiline.info/) for more information.
 
 ## Inheritance
 
-[YAML anchors and references](https://blog.daemonl.com/2016/02/yaml.html) are useful for defining and referencing information that is used more than once in a file, e.g. when using defining multiple connectors of the same type or family. See [Demo 02](../examples/demo02.yml) for an example.
+[YAML anchors and references](https://blog.daemonl.com/2016/02/yaml.html) are useful for defining and referencing information that is used more than once in a file, e.g. when using multiple connectors of the same type or family. See [Demo 02](../examples/demo02.yml) for an example.