add documentation for new format

Author: dragoncoder047

.vscode/settings.json

@@ -4,6 +4,7 @@
         "clrall",
         "clrmask",
         "MOSFET",
+        "nanofarads",
         "NFET",
         "PFET",
         "polylinegon",

format.md

@@ -15,56 +15,120 @@ Crossed:         Joined:       Corner:     Crossed:      Crossed:    Dangling en
     |               |                         |             |
 ```
 
-## Components
-
-### Small components
+### Wire Tags
 
-Small components are notated with their reference designator: one or more uppercase letters followed by an ID, which can either be a number, or a period followed by some text.
+Wire tags look like `<name=` or `=name>` and are attached to specific wires. All wires tagged with the same `name` belong to the same net. Currently this only affects rendering.
 
-They are always written horizontally even if the terminals are on the top and bottom.
+## Components
 
-IDs are allowed to be duplicated and result in the same component values.
+Components are notated with their reference designator: one or more uppercase letters followed by an ID (a nonnegative integer) optionally followed by a suffix (which can be composed of uppercase letters and underscores)
 
-Components can be padded on either side with `#`'s to make them bigger.
+* They are always written horizontally even if the terminals are on the top and bottom.
+* IDs are allowed to be duplicated and result in the same component values.
+* Components can be padded (horizontally and vertically) `#`'s to make them bigger and control the shape (for components that support shapes).
 
 Examples:
 
 * `C33`
 * `Q1001`
-* `L.Coil`
+* `L5`
 * `F3#`
-* `D7#####`
-* `U1#####`
-* `####R.Heater####`
+* `####D7#####`
+* `R333A`
+* ```txt
+      # ######
+       # ########
+    ----# #########
+        # #U1G1#####----
+    ----# #########
+       # ########
+      # ######
+  ```
 
-Components are able to accept "flags", which are other punctuation characters and lowercase letters touching them.
+Components' terminals are annotated with "flags", which are other punctuation characters and lowercase letters touching them.
 
-* Polarized components (caps, diodes, etc.) accept a `+` to indicate the polarity,
-* Transistors use lowercase letters to indicate collector/emitter/base (for BJTs) or source/gate/drain (for FETs).
+* Polarized components (caps, diodes, etc.) use a `+` for one terminal to indicate the polarity,
+* Transistors use 3 lowercase letters to indicate collector/emitter/base (for bipolar transistors) or source/gate/drain (for field-effect transistors).
 
-### Big components
+## Annotations
 
-* Big components are indicated with a box made of `~` (top and bottom), `:` (sides), and `.` (corners).
-* The inside of the box can contain anything you want, but it must include exactly one reference designator as to what component it is.
+### Text Annotations
 
-## Reference designators
+You can include arbitrary text in the diagram by `[enclosing it in brackets like this]`.
 
-To include component values, pin numbers, etc, somewhere in the drawing but not touching any wires or other components, you can write component values - these are formatted as the reference designator (same as in circuit) followed by a `:` and the value parameter (which stops at the first whitespace). *I usually put these in a "BOM section" below the circuit itself but you could also put them right next to the component.*
+### Line Annotations
 
-For simple components, this is usually just a value rating, but *without* the units (only the Metric prefix). For more specific components (mostly semiconductor devices) this is usually the part number and/or some string to determine how to draw the component.
+To outline certain areas with lines (that are not wires), you can draw lines with colons/tildes (for straight lines), and periods/single quotes (for corners) like so:
 
-Examples:
+```txt
+   .~~~~~~~~~~.
+   :  .~~~    :
+   :  :       :
+   :  :       :
+   :  :    .~~'~~~~.
+   :  '~~~~'       :
+   '~~~~~~~~~~~~~~~'
+```
+
+Lines are allowed to cross wires. They are crossed the same way that wires cross each other.
+
+## Data
+
+Every drawing is required to have a "data section" appended after it. The data section contains mappings of values to tell Schemascii how to render each component (e.g. how thick to make the lines, what the components' values are, etc.)
+
+Here is some example data:
+
+```txt
+* {
+    %% these are global config options
+    color = black
+    width = 2; padding = 20;
+    format = symbol
+    mystring = "hello\nworld"
+}
+
+R* %% matches any resistor
+{tolerance = .05; wattage = 0.25}
+
+VR1 {
+    resistance = 0 - 10k; %% ranges on variable components
+    %% trailing comments are allowed
+}
+```
+
+In each RULE, the SELECTOR defines what components and/or drawing objects match; for the ones that match, the MAPPING (which is stored as a Python `dict`) is or'ed into the computed properties. Rules on the bottom take precedence (there is no such thing as specificity like there is in CSS).
+
+Selectors can match multiple scopes by using glob matching. Schemascii currently uses [`fnmatch`][fnmatch] to determine matching selectors but I'll probably change that.
+
+See [options.md][options] for what options are available in which scopes.
+
+Here is a rough grammar (space ignored):
+
+```ebnf
+DATA = RULE (eol+ RULE)* ;
+RULE = SELECTOR eol* MAPPING ;
+SELECTOR = symbol ;
+MAPPING = "{" ((NAME "=" VALUE)? eol)* "}" ;
+NAME = string | symbol ;
+VALUE = (number | string | symbol)* ;
+number = /(?:\d*\.)?\d+(?:[Ee][+-]?\d+)?/ ;
+string = /"(?:\\"|[^"])+"|\s+/ ;
+symbol = <any sequence of printing characters that isn't another kind of token>
+eol = ";" | comment? "\n"+ ;
+comment = "%%" <everything until newline> ;
+```
+
+### Metric values
 
-* `C33:2.2u` -- "2.2 &micro;F"
-* `Q1001:pnp:TIP102` -- "pnp", "npn", "pfet", or "nfet" to determine what kind of transistor, plus the part number; printed verbatim
-* `L51:0.33` -- this is rewritten to "330 mH" so that it has no decimal point.
-* `F3:1500m` -- rewritten: "1.5 A"
-* `D7:1N4001` -- again, part number
-* `U1:SN74LS08N,14,1,2,7,3` -- some components let you label pins with whatever you want (in this case just numbers). They start at the top-leftmost and follow **counterclockwise** to follow with the pin-numbering of most IC's.
-* `R2:10,5` -- this is formatted as "10 &ohm; 5 W". The second value is the rating; for resistors, this is a wattage, for most else, this is a maximum voltage.
+For many small components, the value of the component is just a number and some unit -- e.g. for resistors it's ohms (&ohm;). Schemascii includes built-in Metric normalization and units, so if the "value" is a Metric number it will be re-written to be as short as possible while still observing the conventions of typical component values. If the unit symbol is not included, it will be added.
 
-## Inline configuration values
+* `value = 0.33m` on an inductor --> "330 &micro;H" (integer values are preferred).
+* `value = 0.33` on a resistor --> "0.33 &ohm;" (no Metric multiplier is preferred).
+* `value = 1500mA` on a fuse --> "1.5 A" (using decimal point is shorter)
+* `value = 2.2 nF` on a capacitor --> "2200 pF" (capacitances aren't typically given in nanofarads)
+* `value = 10; power = 5` --> "10 &ohm; 5 W". Many components have "secondary" optional values; the name will be given in the [options][].
 
-**New in 0.2.0!**
+Also, if the value is not even a number -- such as `L1 {value = "detector coil"}`, the Metric-normalization code will not activate, and the value written will be used verbatim -- "L1 detector coil".
 
-You can specify configuration values for rendering the components inline in the document by writing `!name=value!` in your document. See the help output of the Schemascii CLI for the different options (in the README) or look at the config options at the top of [`configs.py`](https://github.com/dragoncoder047/schemascii/blob/main/schemascii/configs.py). The most common options I use are `scale` and `padding`.
+[fnmatch]: https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch
+[options]: options.md