From 15b6ed0419b96994c024f2953162ea18c37abb2e Mon Sep 17 00:00:00 2001
From: Joost De Cock <joost@joost.at>
Date: Sun, 2 Oct 2022 17:41:04 +0200
Subject: [PATCH] chore(markdown): Updated settings docs for v3

---
 .../dev/reference/settings/complete/en.md     | 10 ++--
 markdown/dev/reference/settings/embed/en.md   | 11 ++---
 markdown/dev/reference/settings/en.md         | 49 +++++++++++++++++--
 .../dev/reference/settings/idprefix/en.md     | 19 +++++--
 markdown/dev/reference/settings/layout/en.md  | 43 ++++++++++------
 markdown/dev/reference/settings/locale/en.md  | 29 ++++++++---
 markdown/dev/reference/settings/margin/en.md  | 43 +++++++++-------
 .../dev/reference/settings/measurements/en.md | 33 +++++++++++--
 markdown/dev/reference/settings/only/en.md    | 25 ++++++++--
 markdown/dev/reference/settings/options/en.md | 32 ++++++++----
 .../dev/reference/settings/paperless/en.md    | 18 +++++--
 markdown/dev/reference/settings/sa/en.md      | 29 +++++++----
 markdown/dev/reference/settings/scale/en.md   | 36 +++++++-------
 markdown/dev/reference/settings/units/en.md   | 22 +++++++--
 14 files changed, 281 insertions(+), 118 deletions(-)

diff --git a/markdown/dev/reference/settings/complete/en.md b/markdown/dev/reference/settings/complete/en.md
index 97a6ea88543..9768605611d 100644
--- a/markdown/dev/reference/settings/complete/en.md
+++ b/markdown/dev/reference/settings/complete/en.md
@@ -3,9 +3,9 @@ title: complete
 ---
 
 The `complete` setting controls the level of detail that is included on a
-pattern. Set `complete` to `false` to limiting the level of detail on the
-pattern.  This has different uses, such as generating patterns to be cut out
-with a laser cutter.
+pattern. Set `complete` to `false` to limit the level of detail on the pattern.
+This has different use cases, such as generating patterns to be cut out with a
+laser cutter.
 
 ## Signature
 
@@ -21,7 +21,7 @@ Set this to `false` to draft a base outline of the pattern, rather than a fully
 
 ## Example
 ```js
-import Aaron from "@freesewing/aaron"
+import { Aaron } from "@freesewing/aaron"
 
 const pattern = new Aaron({
   complete: false
@@ -30,6 +30,6 @@ const pattern = new Aaron({
 
 ## Notes
 
-Setting `complete` to `false` will force [sa](/reference/api/settings/sa) to
+Setting `complete` to `false` will force [sa](/reference/settings/sa) to
 also be set to `false`.
 
diff --git a/markdown/dev/reference/settings/embed/en.md b/markdown/dev/reference/settings/embed/en.md
index 359f2b9b0ef..4d85dbc832d 100644
--- a/markdown/dev/reference/settings/embed/en.md
+++ b/markdown/dev/reference/settings/embed/en.md
@@ -2,9 +2,8 @@
 title: embed
 ---
 
-The `embed` setting controls the properties of the SVG document. Set it to
-`true` to make SVG output suitable for embedding in a web page by omitting the
-`height` and `width` properties.
+The `embed` setting controls whether to generate an SVG document suitable for
+printing, or for embedding on a web page.
 
 ## Signature
 
@@ -24,13 +23,9 @@ scale.
 ## Example
 
 ```js
-import Aaron from "@freesewing/aaron"
+import { Aaron } from "@freesewing/aaron"
 
 const pattern = new Aaron({
   embed: true
 })
 ```
-
-## Notes
-
-Do **not** use this for SVGs you want to print.
diff --git a/markdown/dev/reference/settings/en.md b/markdown/dev/reference/settings/en.md
index 199aca32232..e81e8b25a59 100644
--- a/markdown/dev/reference/settings/en.md
+++ b/markdown/dev/reference/settings/en.md
@@ -1,11 +1,52 @@
 ---
 title: Settings
-about: Documents all the settings your pattern can receive, including the pattern options, measurements, and design options
 ---
 
-FreeSewing is all about parametric design, and the settings are the parameters we pass to a pattern when drafting it.
-Perhaps the most important of all settings are the measurements, but there's other settings too.
+FreeSewing is all about parametric design, and the settings are the parameters
+we pass to a pattern when drafting it.  Perhaps the most important of all
+settings are the measurements, but there's other settings too.
 
-Below is a complete list of all supported settings:
+## Signature
+
+```js
+Object settings = {
+  Boolean complete=true,
+  Boolean embed=false,
+  Boolean idPrefix='fs-',
+  Object|Boolean layout=false
+  String locale='en',
+  Number margin=2,
+  Object measurements
+  Array only,
+  Object options,
+  Boolean paperless=false
+  Boolean sa=false
+  Number scale=1
+  String units='metric'
+}
+```
+
+## Properties
+
+Below is a complete list of all supported properties in a settings object:
 
 <ReadMore list />
+
+## Notes
+
+You can pass multiple settings objects to a pattern in an array:
+
+```js
+new pattern([
+  { 
+    // settings
+  },
+  { 
+    // different settings
+  },
+])
+```
+
+<Fixme>Add link to multiset docs</Fixme>
+
+
diff --git a/markdown/dev/reference/settings/idprefix/en.md b/markdown/dev/reference/settings/idprefix/en.md
index 7af1597022e..1ed12d154de 100644
--- a/markdown/dev/reference/settings/idprefix/en.md
+++ b/markdown/dev/reference/settings/idprefix/en.md
@@ -5,15 +5,26 @@ title: idPrefix
 The `idPrefix` setting allows you to specify a prefix that will be used
 for all IDs in the SVG output. Its default value is `fs-`.
 
+## Signature
+
+```js
+const settings = {
+  String idPrefix='fs-'
+}
+```
+
 When you embed multiple SVGs on a single page, the IDs can and will conflict,
-especially when using `xlink:href` references (such as for text on paths and snippets).
+especially when using `xlink:href` references (such as for text on paths and
+snippets).
 
 This allows you to specify an ID prefix so you can sidestep ID collisions.
 
-```js
-import Brian from "@freesewing/brian";
+## Example
 
-const pattern = new Brian({
+```js
+import { Aaron } from "@freesewing/aaron";
+
+const pattern = new Aaron({
   idPrefix: "something-else"
 })
 ```
diff --git a/markdown/dev/reference/settings/layout/en.md b/markdown/dev/reference/settings/layout/en.md
index 0a098ab7bc4..f874ad4230e 100644
--- a/markdown/dev/reference/settings/layout/en.md
+++ b/markdown/dev/reference/settings/layout/en.md
@@ -3,15 +3,35 @@ title: layout
 ---
 
 The `layout` setting allows you to control the way pattern parts are
-layed out on the pattern. There are 3 scenarios:
+layed out on the pattern. Either automatic, explicit, or not at all.
+
+## Signature
+
+```js
+const settings = {
+  Boolean|Object layout=true
+}
+```
+
+There are 3 scenarios:
 
 - layout is truthy: Do layout algorithmically
 - layout is falsy: Do not do any layout apart from stacking all parts together
 - layout is an object: Layout the parts as detailed in the layout object
 
-Let's look at each in detail:
+## example
 
-## layout is truthy
+```js
+import { Aaron } from "@freesewing/aaron"
+
+const pattern = new aaron({
+  layout: false
+})
+```
+
+## Notes
+
+### Behavior when layout is truthy
 
 This is the default behaviour. Parts will be laid without overlap in
 a space that's a small as possible.
@@ -20,7 +40,7 @@ Don't expect miracles here.
 It's one of those things humans are far better at than
 computers.
 
-## layout is falsy
+### Behavior when layout is falsy
 
 This will cause all parts to be laid out on top of each other.
 
@@ -28,15 +48,15 @@ It is almost certainly not what you want, but having all parts piled
 on top of each other in the top left corner can be a good starting
 point for a custom layout.
 
-## layout is a layout object
+### Behavior when layout is a layout object
 
 This allows you to control the layout by passing a layout object.
 This object should be structures as such:
 
 ```js
-import brian from "@freesewing/brian";
+import { Aaron } from "@freesewing/aaron"
 
-let pattern = new brian({
+const pattern = new Aaron({
   layout: {
     parts: {
       front: {
@@ -61,12 +81,3 @@ For each part in the `parts` attribute of our layout object, there are 4 possibl
 - rotate: Expects a number, and will rotate the part by number degrees around its center point
 - flipX: Will flip/mirror the part horizontally
 - flipY: Will flip/mirror the part vertically
-
-<Related>
-
-It is a long-standing ambition of ours to build a layout component that allows
-users to manually do the layout of their pattern.
-
-Core already supports it, but building a React component for it is non-trivial.
-
-</Related>
diff --git a/markdown/dev/reference/settings/locale/en.md b/markdown/dev/reference/settings/locale/en.md
index 4ef9bde4142..28d5efaf3e2 100644
--- a/markdown/dev/reference/settings/locale/en.md
+++ b/markdown/dev/reference/settings/locale/en.md
@@ -2,17 +2,32 @@
 title: locale
 ---
 
-The `locale` setting allows you to specify the language of the pattern.
-It should contain a 2-letter language code that indicates what language the user wants.
-The default is `en`.
+The `locale` setting allows you to specify the language of the pattern.  It
+should contain a 2-letter language code that indicates what language the user
+wants. The default is `en`.
 
-This will be used to set the `xml:lang` attribute in the `svg` tag when rendering to SVG,
-and by [the i18n plugin](/reference/plugins/i18n/) to translate the pattern.
+## Signature
 
 ```js
-import Brian from "@freesewing/brian";
+const settings = {
+  String locale='en'
+}
+```
 
-const pattern = new Brian({
+## Example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+
+const pattern = new Aaron({
   locale: "es"
 })
 ```
+
+## Notes
+
+This will be used to set the `xml:lang` attribute in the `svg` tag when
+rendering to SVG, and by [the i18n plugin](/reference/plugins/i18n/) to
+translate the pattern.
+
+
diff --git a/markdown/dev/reference/settings/margin/en.md b/markdown/dev/reference/settings/margin/en.md
index ff49b2b4d2b..abfb265f991 100644
--- a/markdown/dev/reference/settings/margin/en.md
+++ b/markdown/dev/reference/settings/margin/en.md
@@ -5,29 +5,36 @@ title: margin
 The `margin` setting allows you to specify a part margin (in mm).
 Each part will have this margin applied. The default is `2mm`.
 
-This means that:
+## Signature
+
+```js
+const settings = {
+  Number margin=2
+}
+```
+
+## Example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+
+const pattern = new Aaron({
+  margin: 5
+})
+```
+
+## Notes
+
+The _margin_ implies that:
 
 - At the edge of the SVG, the margin will be `margin * 1` (2mm by default)
 - Between parts, the margin will be `margin * 2` (4mm by default)
 
 Note that setting the margin to zero (or below) will cause parts to overlap.
 
-```js
-import Brian from "@freesewing/brian";
-
-const pattern = new Brian({
-  margin: 5
-})
-```
-
-<Note>
-
-###### For paperless, the minimal margin is 10mm
-
 In paperless mode, the margin will not go below 10mm.
 
-That is because text is not taken into account when calculating the bounding box of the part.
-Since dimensions are typically the outermost elements in a paperless part,
-a too narrow margin would cause the dimension text to get cut off.
-
-</Note>
+That is because text is not taken into account when calculating the bounding
+box of the part.  Since dimensions are typically the outermost elements in a
+paperless part, a too narrow margin would cause the dimension text to get cut
+off.
diff --git a/markdown/dev/reference/settings/measurements/en.md b/markdown/dev/reference/settings/measurements/en.md
index 1e9e92c87c7..a52b4f24340 100644
--- a/markdown/dev/reference/settings/measurements/en.md
+++ b/markdown/dev/reference/settings/measurements/en.md
@@ -4,15 +4,38 @@ title: measurements
 
 The `measurements` settings should hold and object with the
 measurements to draft the pattern for.
-The pattern configuration lists all required measurements.
+
+## Signature
 
 ```js
-import Brian from "@freesewing/brian";
+const settings = {
+  Object measurements={
+    String measurementName: Number measurementValue,
+    ...
+  }
+}
+```
 
-const pattern = new Brian({
+## Example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+
+const pattern = new Aaron({
   measurements: {
-    chestCircumference: 1080
-    shoulderSlope: 55
+    biceps: 254,
+    chest: 871,
+    hpsToWaistBack: 380,
+    hips: 847,
+    neck: 320,
+    shoulderSlope: 13,
+    shoulderToShoulder: 399,
+    waistToHips: 120,
   }
 })
 ```
+
+## Notes
+
+Measurements should always be specified in millimeter, unless it's an angle
+measurement (like `shoulderSlope`) which should be provided in degrees.
diff --git a/markdown/dev/reference/settings/only/en.md b/markdown/dev/reference/settings/only/en.md
index 4dd29567616..a7b12b6834d 100644
--- a/markdown/dev/reference/settings/only/en.md
+++ b/markdown/dev/reference/settings/only/en.md
@@ -3,15 +3,30 @@ title: only
 ---
 
 The `only` setting allows you to specify one or more parts to
-draft/render, rather than the entire pattern.
+draft, rather than the entire pattern.
 
 It accepts either a single part name as a string, or an array of
 one or more part names.
 
-```js
-import Brian from "@freesewing/brian";
+## Signature
 
-const pattern = new Brian({
-  only: ["front", "sleeve"]
+```js
+const settings = {
+  Array|Boolean only=false
+}
+```
+
+## Example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+
+const pattern = new Aaron({
+  only: ['aaron.front']
 })
 ```
+
+## Notes
+
+When `only` is not specified, it defaults to `false` which means all parts will
+be included.
diff --git a/markdown/dev/reference/settings/options/en.md b/markdown/dev/reference/settings/options/en.md
index 0661631675a..aeea08651c8 100644
--- a/markdown/dev/reference/settings/options/en.md
+++ b/markdown/dev/reference/settings/options/en.md
@@ -5,20 +5,34 @@ title: options
 The `options` setting allows you to specify values for the pattern-specific
 options that have been implemented by the pattern designer.
 
-The available options are listed in the pattern configuration.
-Refer to the [the options section in the pattern configuration file][1] for
-all details about using options in FreeSewing.
-
-[1]: /reference/api/config/options
+## Signature
 
 ```js
-import Brian from "@freesewing/brian";
+const settings = {
+  Object options={}
+}
+```
 
-const pattern = new Brian({
+## Example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+
+const pattern = new Aaron({
   options: {
-    chestEase: 120
+    chestEase: 0.065,
+    necklineDrop: 0.17,
   }
 })
 ```
 
-<Note>Unlike measurements, options come with defaults.</Note>
+## Notes
+
+Unlike measurements, options come with defaults.
+
+The available options are listed in the part configuration.
+Refer to the [the options section in the part configuration][1] for
+all details about using options in FreeSewing.
+
+[1]: /reference/api/part/config/options
+
diff --git a/markdown/dev/reference/settings/paperless/en.md b/markdown/dev/reference/settings/paperless/en.md
index b448c03310a..29de9212cb7 100644
--- a/markdown/dev/reference/settings/paperless/en.md
+++ b/markdown/dev/reference/settings/paperless/en.md
@@ -2,16 +2,26 @@
 title: paperless
 ---
 
-The `paperless` options allows you to generate a variant of the pattern
+The `paperless` setting allows you to generate a variant of the pattern
 that does not require you to print it. It does that by including dimensions
 on the pattern, as wel as a grid overlay.
 
-Set this to `true` to draft a paperless pattern. The default is `false`.
+## Signature
 
 ```js
-import Brian from "@freesewing/brian";
+const settings = {
+  Boolean paperless=false
+}
+```
 
-const pattern = new Brian({
+Set this to `true` to draft a paperless pattern. The default is `false`.
+
+## Example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+
+const pattern = new Aaron({
   paperless: true
 })
 ```
diff --git a/markdown/dev/reference/settings/sa/en.md b/markdown/dev/reference/settings/sa/en.md
index 29e6ef73a9e..ae2122cbc18 100644
--- a/markdown/dev/reference/settings/sa/en.md
+++ b/markdown/dev/reference/settings/sa/en.md
@@ -2,24 +2,35 @@
 title: sa
 ---
 
-The `sa` setting controls the seam allowance. It expects a value in mm
-or `false` or `0` to disable seam allowance altogether.
+The `sa` setting controls the seam allowance. Either provide value in
+millimeter or set it to `false` or `0` to disable seam allowance altogether.
+
+## Signature
 
 ```js
-import Brian from "@freesewing/brian";
+const settings = {
+  Number|Boolean sa=false
+}
+```
 
-const pattern = new Brian({
+By default, the `sa` setting is `false` and seam allowance is no included.
+
+## Example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+
+const pattern = new Aaron({
   sa: 10
 })
 ```
 
-<Note>
+## Notes
 
 This is ignored if [settings.complete](/reference/api/settings/complete) is `false`
 
 <Comment by="joost">
-Is it though?
-I suspect this is not clearly enforced and we should clarify that.
+This is not strictly enforced and left of to the designer, so different designs
+may behave differently with regards to including seam allowance when `complete` is
+set to `false`.
 </Comment>
-
-</Note>
diff --git a/markdown/dev/reference/settings/scale/en.md b/markdown/dev/reference/settings/scale/en.md
index 2d41aa8c6fd..0331c13e357 100644
--- a/markdown/dev/reference/settings/scale/en.md
+++ b/markdown/dev/reference/settings/scale/en.md
@@ -2,18 +2,6 @@
 title: scale
 ---
 
-<Note>
-
-##### This setting is for future use
-
-This setting has been added to our core library in anticipation
-of a feature request that we've made part of [our v3
-roadmap](https://github.com/freesewing/freesewing/discussions/1278).
-
-It does not currently have any effect.
-
-</Note>
-
 The `scale` setting is an overal factor that will influence a variety of
 factors to better support very large or very small patterns.
 
@@ -21,16 +9,26 @@ To be clear, `scale` does not change the size of the pattern itself.
 It merely controls things like the various stroke width, the size of arrows
 on dimensions, the size of the text on the pattern, and so on.
 
-This is a feature request by those users that our generating pattern
-for dolls. At such small sizes, many snippets, text, or logos become
-so large (in comparison to the pattern) that they are problematic.
-
-This setting is aimed at addressing that.
+## Signature
 
 ```js
-import Brian from "@freesewing/brian";
+const settings = {
+  Number scale=1
+}
+```
 
-const pattern = new Brian({
+## Example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+
+const pattern = new Aaron({
   scale: 0.5
 })
 ```
+
+## Notes
+
+This is a feature request by those users that our generating pattern
+for dolls. At such small sizes, many snippets, text, or logos become
+so large (in comparison to the pattern) that they are problematic.
diff --git a/markdown/dev/reference/settings/units/en.md b/markdown/dev/reference/settings/units/en.md
index 795f1155279..44028cf18c8 100644
--- a/markdown/dev/reference/settings/units/en.md
+++ b/markdown/dev/reference/settings/units/en.md
@@ -5,13 +5,25 @@ title: units
 The `units` setting controls the units used on the pattern.
 It can be either `metric` (the default) or `imperial`.
 
-Note that this is only used to format the output.
-Freesewing expects mm as input.
+## Signature
 
 ```js
-import Brian from "@freesewing/brian";
+const settings = {
+  String units='metric'
+}
+```
 
-const pattern = new Brian({
-  units: "imperial"
+## Example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+
+const pattern = new Aaron({
+  units: 'imperial'
 })
 ```
+
+## Notes
+
+This setting only applies to formatting of the output.
+Freesewing expects all input to be in millimeter.