warehack.ing/WireViz
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Write some clarification for syntax.md

Browse Source
This commit is contained in:
Martin Rieder 2024-07-02 01:40:21 +02:00
parent c7d643bf29
commit 7da3554b76
1 changed files with 46 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/syntax.md
View File

@ -1,7 +1,35 @@
# WireViz Syntax # 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 ## 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 ```yaml
connectors: # dictionary of all used connectors connectors: # dictionary of all used connectors
<str> : # unique connector designator/name <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. 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 ```yaml
connections: connections:
- # Each list entry is a connection set - # 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 ### Single connections
#### Connectors #### 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. 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 ```yaml
connectors: connectors:
@ -447,6 +475,9 @@ Alternatively items can be added to just the BOM by putting them in the section
## GraphViz tweaking (experimental) ## GraphViz tweaking (experimental)
This feature is experimental and might change or be removed in future versions.
```yaml ```yaml
# Optional tweaking of the .gv output. # Optional tweaking of the .gv output.
# This feature is experimental and might change # 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
Colors are defined via uppercase, two character strings. Colors are defined via uppercase, two character strings. The following colors are understood:
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:
- `BK` ![##000000](https://via.placeholder.com/15/000000/000000?text=+) (black) - `BK` ![##000000](https://via.placeholder.com/15/000000/000000?text=+) (black)
- `WH` ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=+) (white) - `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: --> <!-- color list generated with a helper script: -->
<!-- https://gist.github.com/formatc1702/3c93fb4c5e392364899283f78672b952 --> <!-- 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`. 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. Remember quoting strings containing a `#` in the YAML file.
## Cable color codes ## 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) - `DIN` for [DIN 47100](https://en.wikipedia.org/wiki/DIN_47100)