From 381719523fee63e8f3d95a7d4000ebafddc8ba0b Mon Sep 17 00:00:00 2001 From: Luke Kershaw <35707277+l-kershaw@users.noreply.github.com> Date: Tue, 3 Jan 2023 23:13:02 +0000 Subject: [PATCH 1/3] draft expansion of units/variables docs --- docs/config-overview.md | 9 ++--- docs/units.md | 78 ++++++++++++++++++++++++++++++++++++++--- 2 files changed, 79 insertions(+), 8 deletions(-) diff --git a/docs/config-overview.md b/docs/config-overview.md index 4e74231..ab6a54c 100644 --- a/docs/config-overview.md +++ b/docs/config-overview.md @@ -9,15 +9,16 @@ If you prefer JSON over YAML, feel free to use it, conversion is trivial and the The important thing is that the data can contain the following keys: ```yaml -points: # required units: # optional +variables: # optional +points: # required outlines: #optional cases: #optional pcbs: #optional ``` -### [`units`](units) -Allows users to set additional units which can be used in the rest of your config +### [`units` and `variables`](units) +Allows users to set additional units and variables which can be used in the rest of your config ### [`points`](points) Describes the core of the layout: the positions of the keys. @@ -37,4 +38,4 @@ Used to configure KiCAD PCB templates. In the following sections we'll have an in-depth look into each of these. There's also a completely separate [preprocessing](preprocessing.md) step to help reduce unnecessary repetition. Of course, if the declarative nature of the config is still not terse enough (despite the preprocessor, the built-in YAML references, and the Ergogen-based inheritance detailed below), there's nothing stopping you from writing code that generates the config. -It brings the game to yet another abstraction level higher, so that you can use branching, loops, and parametric functions to compose a "drier" keyboard definition. \ No newline at end of file +It brings the game to yet another abstraction level higher, so that you can use branching, loops, and parametric functions to compose a "drier" keyboard definition. diff --git a/docs/units.md b/docs/units.md index b506065..2b85545 100644 --- a/docs/units.md +++ b/docs/units.md @@ -4,7 +4,7 @@ sidebar_position: 3 # Units -We start with an optional `units` clause, where we can define units to use in relative calculations. +We start with an optional `units` clause, where we can define units to use in relative calculations. The four predefined ones are `U`, `u`, `cx`, and `cy`. ```yaml U: 19.05 # 19.05 MX spacing @@ -16,8 +16,78 @@ cy: 17 # 17mm Choc Y spacing But we can add any other (or modify these predefined ones), or even use an existing measure in calculating a new value (for example, `double: 2 u`). Recall how each string that can be interpreted as a math formula will be treated like a number, so this is a great way to add math-level variables to your config. +For example, the following units may be useful if you expect to only use "1.5u" key-caps: ```yaml units: - a: cy - 7 - b: a * 1.5 -``` \ No newline at end of file + kx: u + 0.5 + ky: u * 1.5 +``` + +# Variables + +Variables are processed identically to units, but allow a user to separate those values that they expect to be changed during development +(for example, stagger of adjacent columns) from those that they expect to stay the same (for example, the size of the keycaps). +```yaml +variables: + ring_stagger: u * 1/2 + middle_stagger: u * 1/4 + # ... +``` + +Like with units, you can perform mathematical operations within these variables. +For example: +```yaml +variables: + # probably a more complicated splay value than required + pinky_splay: atan(1/3) * 180/pi + + # a very important calculation for thumb key positioning + a: pi^2 + b: e^pi + c: (1+sqrt(5))/2 + thumb_x: (-b + sqrt(b^2-4*a*c))/(2*a) + thumb_y: 1/a + 1/b + 1/c +``` + +# Internal default values + +There are several internal default values that are used when arranging [points](points). +```yaml + $default_stagger: 0 + $default_spread: u + $default_splay: 0 + $default_height: u-1 + $default_width: u-1 + $default_padding: u + $default_autobind: 10 +``` + +While these can be modified directly within the `units` or `variables` section; +they can only be reassigned using math involving the predefined units `U`, `u`, `cx`, and `cy`. +Reassigning these defaults using user defined units/variables will not work. +For example, the following is valid (though probably unhelpful): +```yaml +units: + $default_stagger: u/8 + $default_spread: u*1.1 + $default_splay: 10 + $default_height: u*0.95 + $default_width: u*0.95 + $default_padding: u+3 + $default_autobind: u/4 +``` +The following is invalid: +```yaml +units: + kx: u+1 + $default_stagger: kx/8 + $default_spread: kx*1.1 + $default_splay: 10 + $default_height: kx*0.95 + $default_width: kx*0.95 + $default_padding: kx+3 + $default_autobind: kx/4 +``` + +Since some of these internal default values are defined in terms of `u`, +even if you aren't directly using `u`, you may find it helpful to redefine it. From 7e3cd03112a5ad1c0521ce23bca7998fd0bc1e5b Mon Sep 17 00:00:00 2001 From: Luke Kershaw <35707277+l-kershaw@users.noreply.github.com> Date: Tue, 3 Jan 2023 23:24:15 +0000 Subject: [PATCH 2/3] add admonition syntax --- docs/units.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/units.md b/docs/units.md index 2b85545..4217f97 100644 --- a/docs/units.md +++ b/docs/units.md @@ -62,9 +62,12 @@ There are several internal default values that are used when arranging [points]( $default_autobind: 10 ``` +:::caution While these can be modified directly within the `units` or `variables` section; they can only be reassigned using math involving the predefined units `U`, `u`, `cx`, and `cy`. Reassigning these defaults using user defined units/variables will not work. +::: + For example, the following is valid (though probably unhelpful): ```yaml units: @@ -89,5 +92,7 @@ units: $default_autobind: kx/4 ``` +:::tip Since some of these internal default values are defined in terms of `u`, even if you aren't directly using `u`, you may find it helpful to redefine it. +::: From 5770e90fc087852e90440396ad13449eadefe8f4 Mon Sep 17 00:00:00 2001 From: Luke Kershaw <35707277+l-kershaw@users.noreply.github.com> Date: Tue, 3 Jan 2023 23:27:12 +0000 Subject: [PATCH 3/3] tweak caution admonition --- docs/units.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/units.md b/docs/units.md index 4217f97..cc12ee5 100644 --- a/docs/units.md +++ b/docs/units.md @@ -62,9 +62,9 @@ There are several internal default values that are used when arranging [points]( $default_autobind: 10 ``` -:::caution While these can be modified directly within the `units` or `variables` section; they can only be reassigned using math involving the predefined units `U`, `u`, `cx`, and `cy`. +:::caution Reassigning these defaults using user defined units/variables will not work. :::