From c7d643bf293ce1c5984641b29c7ae8dbd74f27f5 Mon Sep 17 00:00:00 2001
From: Martin Rieder <74277074+martinrieder@users.noreply.github.com>
Date: Fri, 14 Jun 2024 15:13:19 +0200
Subject: [PATCH 1/6] Image syntax description missing `scale` and `fixedsize`

---
 docs/syntax.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/syntax.md b/docs/syntax.md
index 2c92fd34..53234bb5 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -536,6 +536,8 @@ image:
   height: <int>      # range: 1~65535; unit: points
   # if only one dimension (width/height) is specified, the image is scaled proportionally.
   # if both width and height are specified, the image is stretched to fit.
+  scale: <str>     # Which dimension to scale ['false', 'true', 'width', 'height', 'both']
+  fixedsize: <bool>  # If only one dimension is specified, compute the other
 ```
 
 For more fine grained control over the image parameters, please see [`advanced_image_usage.md`](advanced_image_usage.md).

From 7da3554b76a88125506647e797d02a4b300a3f5c Mon Sep 17 00:00:00 2001
From: Martin Rieder <74277074+martinrieder@users.noreply.github.com>
Date: Tue, 2 Jul 2024 01:40:21 +0200
Subject: [PATCH 2/6] Write some clarification for syntax.md

---
 docs/syntax.md | 61 +++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 46 insertions(+), 15 deletions(-)

diff --git a/docs/syntax.md b/docs/syntax.md
index 53234bb5..93325a46 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -1,7 +1,35 @@
 # WireViz Syntax
 
+WireViz input files are created as plain text based on YAML, which does not require any special editor. International character sets and technical symbols are also supported through UTF-8.
+See the following sections of this document about further details:
+
+  - **[Main sections](#main-sections)**
+  - [Colors](#colors)
+  - [Cable color codes](#cable-color-codes)
+  - [Images](#images)
+  - [Multiline Strings](#multiline-strings)
+  - [Inheritance](#inheritance)
+
+The YAML syntax is human readable and supports version control because of its hierarchical structure.
+The input files would normally be saved using a text editor to the file extension `.yml` or `.yaml`.
+
+See the [tutorial page](../tutorial/readme.md) for sample code, as well as the [example gallery](../examples/readme.md) to see more of what WireViz can do.
+
 ## Main sections
 
+The main sections at the highest hierarchical level of the document may contain any of the following:
+
+  - [Connectors](#connector-attributes)
+  - [Cables](#cable-attributes)
+  - [Connections](#connection-sets)
+  - [Metadata](#metadata-entries)
+  - [Options](#options)
+  - [BOM items and additional components](#bom-items-and-additional-components)
+  - [GraphViz tweaking](#graphviz-tweaking-experimental)
+
+Their respective attribute assignments need to be indented using space characters on every line.
+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
@@ -154,6 +182,15 @@ tweak:  # optional tweaking of .gv output
 
 A connection set is used to connect multiple components together. Multiple connections can be easily created in parallel within one connection set, by specifying a list of individual pins (for `connectors`) or wires (for `cables`) for every component along the way.
 
+- Each connection set is a list of components.
+- The minimum number of items is one.
+- The maximum number of items is unlimited.
+- Items must alternatingly belong to the `connectors` and the `cables` sections.
+- When a connection set defines multiple parallel connections, the number of specified `<pin>`s and `<wire>`s for each component in the set must match. When specifying only one designator, one is auto-generated for each connection of the set.
+- `<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.
+- For `<arrow>`, see below.
+
 ```yaml
 connections:
   -                # Each list entry is a connection set
@@ -191,15 +228,6 @@ connections:
   ...    
 ```
 
-- Each connection set is a list of components.
-- The minimum number of items is one.
-- The maximum number of items is unlimited.
-- Items must alternatingly belong to the `connectors` and the `cables` sections.
-- When a connection set defines multiple parallel connections, the number of specified `<pin>`s and `<wire>`s for each component in the set must match. When specifying only one designator, one is auto-generated for each connection of the set.
-- `<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.
-- For `<arrow>`, see below.
-
 ### Single connections
 
 #### Connectors
@@ -279,7 +307,7 @@ If multiple identical copies of a connector or cable are needed, it is possible
 
 Autogenerated instances of components can be explicitly assigned a designator; this way, they can be referenced in multiple connection sets. However, it is also possible to generate unnamed instances of components. This is especially useful for components that do not need to be referenced in more than one connection set, and where naming each individual instance is an unnecessary complication.
 
-Example (see `connections` section):
+Example (see [`connections`](#connection-sets) section):
 
 ```yaml
 connectors:
@@ -447,6 +475,9 @@ Alternatively items can be added to just the BOM by putting them in the section
 
 ## GraphViz tweaking (experimental)
 
+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
@@ -472,10 +503,7 @@ Alternatively items can be added to just the BOM by putting them in the section
 
 ## Colors
 
-Colors are defined via uppercase, two character strings.
-Striped/banded wires can be specified by simply concatenating multiple colors, with no space inbetween, eg. `GNYE` for green-yellow.
-
-The following colors are understood:
+Colors are defined via uppercase, two character strings. The following colors are understood:
 
 - `BK` ![##000000](https://via.placeholder.com/15/000000/000000?text=+) (black)
 - `WH` ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=+) (white)
@@ -502,12 +530,15 @@ The following colors are understood:
 <!-- color list generated with a helper script: -->
 <!-- https://gist.github.com/formatc1702/3c93fb4c5e392364899283f78672b952 -->
 
+Striped/banded wires can be specified by simply concatenating multiple colors, 
+with no space inbetween, eg. `GNYE` for green-yellow.
+
 It is also possible to specify colors as hexadecimal RGB values, e.g. `#112233` or `#FFFF00:#009900`.
 Remember quoting strings containing a `#` in the YAML file.
 
 ## Cable color codes
 
-Supported color codes:
+Supported values for different international color coding standards are:
 
 - `DIN` for [DIN 47100](https://en.wikipedia.org/wiki/DIN_47100)
 

From f5e4c061c1def874817d9fce764c192727fe527b Mon Sep 17 00:00:00 2001
From: Martin Rieder <74277074+martinrieder@users.noreply.github.com>
Date: Tue, 2 Jul 2024 01:48:14 +0200
Subject: [PATCH 3/6] Add color coding letters to syntax.md

---
 docs/syntax.md | 33 ++++++++++++++++++++++++++-------
 1 file changed, 26 insertions(+), 7 deletions(-)

diff --git a/docs/syntax.md b/docs/syntax.md
index 93325a46..d34813ac 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -540,13 +540,32 @@ Remember quoting strings containing a `#` in the YAML file.
 
 Supported values for different international color coding standards are:
 
-- `DIN` for [DIN 47100](https://en.wikipedia.org/wiki/DIN_47100)
-
-  ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=+) ![##895956](https://via.placeholder.com/15/895956/000000?text=+) ![##00ff00](https://via.placeholder.com/15/00ff00/000000?text=+) ![##ffff00](https://via.placeholder.com/15/ffff00/000000?text=+) ![##999999](https://via.placeholder.com/15/999999/000000?text=+) ![##ff66cc](https://via.placeholder.com/15/ff66cc/000000?text=+) ![##0066ff](https://via.placeholder.com/15/0066ff/000000?text=+) ![##ff0000](https://via.placeholder.com/15/ff0000/000000?text=+) ![##000000](https://via.placeholder.com/15/000000/000000?text=+) ![##8000ff](https://via.placeholder.com/15/8000ff/000000?text=+) ...
-
-- `IEC` for [IEC 60757](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) ("ROY G BIV")
-
-  ![##895956](https://via.placeholder.com/15/895956/000000?text=+) ![##ff0000](https://via.placeholder.com/15/ff0000/000000?text=+) ![##ff8000](https://via.placeholder.com/15/ff8000/000000?text=+) ![##ffff00](https://via.placeholder.com/15/ffff00/000000?text=+) ![##00ff00](https://via.placeholder.com/15/00ff00/000000?text=+) ![##0066ff](https://via.placeholder.com/15/0066ff/000000?text=+) ![##8000ff](https://via.placeholder.com/15/8000ff/000000?text=+) ![##999999](https://via.placeholder.com/15/999999/000000?text=+) ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=+) ![##000000](https://via.placeholder.com/15/000000/000000?text=+) ...
+- `DIN` for [DIN 47100](https://en.wikipedia.org/wiki/DIN_47100) (WT/BN/GN/YE/GY/PK/BU/RD/BK/VT/...)
+
+  ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=WT) 
+  ![##895956](https://via.placeholder.com/15/895956/000000?text=BN) 
+  ![##00ff00](https://via.placeholder.com/15/00ff00/000000?text=GN) 
+  ![##ffff00](https://via.placeholder.com/15/ffff00/000000?text=YE) 
+  ![##999999](https://via.placeholder.com/15/999999/000000?text=GY) 
+  ![##ff66cc](https://via.placeholder.com/15/ff66cc/000000?text=PK) 
+  ![##0066ff](https://via.placeholder.com/15/0066ff/000000?text=BU) 
+  ![##ff0000](https://via.placeholder.com/15/ff0000/000000?text=RD) 
+  ![##000000](https://via.placeholder.com/15/000000/ffffff?text=BK) 
+  ![##8000ff](https://via.placeholder.com/15/8000ff/000000?text=VT) 
+
+- `IEC` for [IEC 60757](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) 
+  (BN/RD/OR/YE/GN/BU/VT/GY/WT/BK/...)
+
+  ![##895956](https://via.placeholder.com/15/895956/000000?text=BN) 
+  ![##ff0000](https://via.placeholder.com/15/ff0000/000000?text=RD) 
+  ![##ff8000](https://via.placeholder.com/15/ff8000/000000?text=OR) 
+  ![##ffff00](https://via.placeholder.com/15/ffff00/000000?text=YE) 
+  ![##00ff00](https://via.placeholder.com/15/00ff00/000000?text=GN) 
+  ![##0066ff](https://via.placeholder.com/15/0066ff/000000?text=BU) 
+  ![##8000ff](https://via.placeholder.com/15/8000ff/000000?text=VT) 
+  ![##999999](https://via.placeholder.com/15/999999/000000?text=GY) 
+  ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=WT) 
+  ![##000000](https://via.placeholder.com/15/000000/ffffff?text=BK) 
 
 - `TEL` and `TELALT`  for [25-pair color code](https://en.wikipedia.org/wiki/25-pair_color_code)
 - `T568A` and `T568B` for [TIA/EIA-568](https://en.wikipedia.org/wiki/TIA/EIA-568#Wiring) (e.g. Ethernet)

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 4/6] Correct indentation and <...> brackets

---
 docs/syntax.md | 366 ++++++++++++++++++++++++-------------------------
 1 file changed, 182 insertions(+), 184 deletions(-)

diff --git a/docs/syntax.md b/docs/syntax.md
index d34813ac..25e1fc85 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>   :
-    ...
-  ...
-
-cables:      # dictionary of all used cables and wires
-  <str>   :    # unique cable designator/name
-    ...          # cable attributes (see below)
-  <str>   :
-    ...
-  ...
-
-connections:  # list of all connections to be made
-              # between cables and connectors
+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
+    <str>: <...>   # cable attributes (see below)
+  <str>:
+    <str>: <...>
+  <...>
+
+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>   
-
-  # 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
-
-  # 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
-
-  # loops
-  loops: <List>  # every list item is itself a list of exactly two pins
-                 # on the connector that are to be shorted
+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)
+
+    # 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
+
+    # 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
 ```
 
 ## 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>   
-
-  # 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)
-
-  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
+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)
+
+    # 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
+
+    # 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.

From f65bde6f09dd43645a5b310748a2cd4ecc258c9d Mon Sep 17 00:00:00 2001
From: Martin Rieder <74277074+martinrieder@users.noreply.github.com>
Date: Tue, 2 Jul 2024 02:04:39 +0200
Subject: [PATCH 5/6] Add color boxes and a syntax.md link to README.md

---
 docs/README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 51 insertions(+), 4 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 732f6714..1ba372bb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,17 +13,64 @@ WireViz is a tool for easily documenting cables, wiring harnesses and connector
 
 ## Features
 
-* WireViz input files are fully text based
+* WireViz input files contain fully text based [YAML syntax](syntax.md)
   * No special editor required
   * Human readable
   * Easy version control
-  * YAML syntax
-  * UTF-8 input and output files for special character support
+  * UTF-8 special character support
 * Understands and uses color abbreviations as per [IEC 60757](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) (black=BK, red=RD, ...)
+
+    ![##000000](https://via.placeholder.com/15/000000/ffffff?text=BK)
+    ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=WH)
+    ![##999999](https://via.placeholder.com/15/999999/000000?text=GY)
+    ![##ff66cc](https://via.placeholder.com/15/ff66cc/000000?text=PK)
+    ![##ff0000](https://via.placeholder.com/15/ff0000/000000?text=RD)
+    ![##ff8000](https://via.placeholder.com/15/ff8000/000000?text=OG)
+    ![##ffff00](https://via.placeholder.com/15/ffff00/000000?text=YE)
+    ![##708000](https://via.placeholder.com/15/708000/000000?text=OL)
+    ![##00ff00](https://via.placeholder.com/15/00ff00/000000?text=GN)
+    ![##00ffff](https://via.placeholder.com/15/00ffff/000000?text=TQ)
+    ![##a0dfff](https://via.placeholder.com/15/a0dfff/000000?text=LB)
+    ![##0066ff](https://via.placeholder.com/15/0066ff/000000?text=BU)
+    ![##8000ff](https://via.placeholder.com/15/8000ff/000000?text=VT)
+    ![##895956](https://via.placeholder.com/15/895956/000000?text=BN)
+    ![##ceb673](https://via.placeholder.com/15/ceb673/000000?text=BG)
+    ![##f5f0d0](https://via.placeholder.com/15/f5f0d0/000000?text=IV)
+    ![##708090](https://via.placeholder.com/15/708090/000000?text=SL)
+    ![##d6775e](https://via.placeholder.com/15/d6775e/000000?text=CU)
+    ![##aaaaaa](https://via.placeholder.com/15/aaaaaa/000000?text=SN)
+    ![##84878c](https://via.placeholder.com/15/84878c/000000?text=SR)
+    ![##ffcf80](https://via.placeholder.com/15/ffcf80/000000?text=GD)
+
   <!-- * Optionally outputs colors as abbreviation (e.g. 'YE'), full name (e.g. 'yellow') or hex value (e.g. '#ffff00'), with choice of UPPER or lower case (#158) -->
 * Auto-generates standard wire color schemes and allows custom ones if needed
   * [DIN 47100](https://en.wikipedia.org/wiki/DIN_47100) (WT/BN/GN/YE/GY/PK/BU/RD/BK/VT/...)
-  * [IEC 60757](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system)   (BN/RD/OR/YE/GN/BU/VT/GY/WT/BK/...)
+
+    ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=WT) 
+    ![##895956](https://via.placeholder.com/15/895956/000000?text=BN) 
+    ![##00ff00](https://via.placeholder.com/15/00ff00/000000?text=GN) 
+    ![##ffff00](https://via.placeholder.com/15/ffff00/000000?text=YE) 
+    ![##999999](https://via.placeholder.com/15/999999/000000?text=GY) 
+    ![##ff66cc](https://via.placeholder.com/15/ff66cc/000000?text=PK) 
+    ![##0066ff](https://via.placeholder.com/15/0066ff/000000?text=BU) 
+    ![##ff0000](https://via.placeholder.com/15/ff0000/000000?text=RD) 
+    ![##000000](https://via.placeholder.com/15/000000/ffffff?text=BK) 
+    ![##8000ff](https://via.placeholder.com/15/8000ff/000000?text=VT) 
+  
+  * [IEC 60757](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) 
+    (BN/RD/OR/YE/GN/BU/VT/GY/WT/BK/...)
+
+    ![##895956](https://via.placeholder.com/15/895956/000000?text=BN) 
+    ![##ff0000](https://via.placeholder.com/15/ff0000/000000?text=RD) 
+    ![##ff8000](https://via.placeholder.com/15/ff8000/000000?text=OR) 
+    ![##ffff00](https://via.placeholder.com/15/ffff00/000000?text=YE) 
+    ![##00ff00](https://via.placeholder.com/15/00ff00/000000?text=GN) 
+    ![##0066ff](https://via.placeholder.com/15/0066ff/000000?text=BU) 
+    ![##8000ff](https://via.placeholder.com/15/8000ff/000000?text=VT) 
+    ![##999999](https://via.placeholder.com/15/999999/000000?text=GY) 
+    ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=WT) 
+    ![##000000](https://via.placeholder.com/15/000000/ffffff?text=BK) 
+  
   * [25 Pair Color Code](https://en.wikipedia.org/wiki/25-pair_color_code#Color_coding) (BUWH/WHBU/OGWH/WHOG/GNWH/WHGN/BNWH/...)
   * [TIA/EIA 568 A/B](https://en.wikipedia.org/wiki/TIA/EIA-568#Wiring)  (Subset of 25-Pair, used in CAT-5/6/...)
 * Understands wire gauge in mm² or AWG

From 6a5b51f303752f65a5aa25e5d68b7ffc0125f005 Mon Sep 17 00:00:00 2001
From: Martin Rieder <74277074+martinrieder@users.noreply.github.com>
Date: Sat, 6 Jul 2024 18:21:14 +0200
Subject: [PATCH 6/6] Revert commit about 'scale` and `fixedsize`

Co-authored-by: kvid <kvid@users.noreply.github.com>
---
 docs/syntax.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/syntax.md b/docs/syntax.md
index 25e1fc85..eacb9674 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -584,8 +584,6 @@ image:
   height: <int>      # range: 1~65535; unit: points
   # if only one dimension (width/height) is specified, the image is scaled proportionally.
   # if both width and height are specified, the image is stretched to fit.
-  scale: <str>     # Which dimension to scale ['false', 'true', 'width', 'height', 'both']
-  fixedsize: <bool>  # If only one dimension is specified, compute the other
 ```
 
 For more fine grained control over the image parameters, please see [`advanced_image_usage.md`](advanced_image_usage.md).