chore(markdown): Updated settings docs

markdown/dev/reference/api/settings/complete/en.md

@@ -2,15 +2,20 @@
 title: complete
 ---
 
-Set this to `false` to draft a base outline of the pattern, rather than a fully detailed pattern.
+The `complete` setting controls the level of details that's included on your pattern.
 This has different uses, such as generating patterns to be cut out with a laser cutter.
 
-The default is `true`.  Setting this to `false` will force [sa](#sa) to be set to `false`.
+The default `complete` setting is `true`. 
+Set this to `false` to draft a base outline of the pattern, rather than a fully detailed pattern.
+
+<Note>
+Setting this to `false` will force [sa](/reference/api/settings/sa) to be set to `false`.
+</Note>
 
 ```js
-import brian from "@freesewing/brian";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   complete: false
 })
 ```

markdown/dev/reference/api/settings/embed/en.md

@@ -2,15 +2,20 @@
 title: embed
 ---
 
-Set to `true` to make SVG output suitable for embedding in a web page.
+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.
 
-This removes the `width` and `height` attributes from the SVG tag, which allows
+The default for `embed` is `false` which will include the `width` and `height`
-you to inject the SVG into an HTML document, and it will responsively scale.
+attributes in the SVG tag, thereby making it suitable for printing.
+
+When set to `true` the `width` and `height` attributes will not be added
+which allows you to inject the SVG into an HTML document, where it will 
+responsively scale.
 
 ```js
-import brian from "@freesewing/brian";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   embed: true
 })
 ```

markdown/dev/reference/api/settings/idprefix/en.md

@@ -2,7 +2,8 @@
 title: idPrefix
 ---
 
-Prefixes all IDs in the SVG with the string you pass it. (defaults to `fs-`).
+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-`.
 
 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).
@@ -10,9 +11,9 @@ especially when using `xlink:href` references (such as for text on paths and sni
 This allows you to specify an ID prefix so you can sidestep ID collisions.
 
 ```js
-import brian from "@freesewing/brian";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   idPrefix: "something-else"
 })
 ```

markdown/dev/reference/api/settings/layout/en.md

@@ -2,8 +2,8 @@
 title: layout
 ---
 
-Allows you to control the way pattern parts are laid out on the pattern.
+The `layout` setting allows you to control the way pattern parts are 
-There are 3 scenarios:
+layed out on the pattern. There are 3 scenarios:
 
 - layout is truthy: Do layout algorithmically
 - layout is falsy: Do not do any layout apart from stacking all parts together
@@ -11,7 +11,7 @@ There are 3 scenarios:
 
 Let's look at each in detail:
 
-##### layout is truthy
+## 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 +20,7 @@ Don't expect miracles here.
 It's one of those things humans are far better at than 
 computers.
 
-##### layout is falsy
+## layout is falsy
 
 This will cause all parts to be laid out on top of each other.
 
@@ -28,7 +28,7 @@ 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
+## layout is a layout object
 
 This allows you to control the layout by passing a layout object.
 This object should be structures as such:
@@ -62,11 +62,11 @@ For each part in the `parts` attribute of our layout object, there are 4 possibl
  - flipX: Will flip/mirror the part horizontally
  - flipY: Will flip/mirror the part vertically
 
-<Note>
+<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.
 
-</Note>
+</Related>

markdown/dev/reference/api/settings/locale/en.md

@@ -2,15 +2,17 @@
 title: locale
 ---
 
-A 2-letter language code that indicates what language the user wants.
+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.
 
 ```js
-import brian from "@freesewing/brian";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   locale: "es"
 })
 ```

markdown/dev/reference/api/settings/margin/en.md

@@ -2,8 +2,10 @@
 title: margin
 ---
 
-Allows you to specify a part margin (in mm). The default is 2mm.  
+The `margin` setting allows you to specify a part margin (in mm). 
-Each part will have this margin applied. This means that:
+Each part will have this margin applied. The default is `2mm`. 
+
+This means 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)
@@ -11,9 +13,9 @@ Each part will have this margin applied. This means that:
 Note that setting the margin to zero (or below) will cause parts to overlap.
 
 ```js
-import brian from "@freesewing/brian";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   margin: 5
 })
 ```

markdown/dev/reference/api/settings/measurements/en.md

@@ -2,12 +2,14 @@
 title: measurements
 ---
 
-The measurements to draft for. The pattern configuration lists all required measurements.
+The `measurements` settings should hold and object with the 
+measurements to draft the pattern for. 
+The pattern configuration lists all required measurements.
 
 ```js
-import brian from "@freesewing/brian";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   measurements: {
     chestCircumference: 1080
     shoulderSlope: 55

markdown/dev/reference/api/settings/only/en.md

@@ -2,14 +2,16 @@
 title: only
 ---
 
-Allows you to specify one or more parts to draft/render, rather than the entire pattern.
+The `only` setting allows you to specify one or more parts to 
+draft/render, rather than the entire pattern.
 
-Accepts a part name as string, or an array of part names.
+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";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   only: ["front", "sleeve"]
 })
 ```

markdown/dev/reference/api/settings/options/en.md

@@ -2,12 +2,15 @@
 title: options
 ---
 
-The pattern options as specified in the pattern configuration.
+The `options` setting allows you to specify the pattern-specific options
+that have been implemented by the pattern designer.
+
+The available options are listed in the pattern configuration.
 
 ```js
-import brian from "@freesewing/brian";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   options: {
     chestEase: 120
   }

markdown/dev/reference/api/settings/paperless/en.md

@@ -2,12 +2,16 @@
 title: paperless
 ---
 
+The `paperless` options 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`.
 
 ```js
-import brian from "@freesewing/brian";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   paperless: true
 })
 ```

markdown/dev/reference/api/settings/sa/en.md

@@ -2,15 +2,13 @@
 title: sa
 ---
 
-The seam allowance in mm.
+The `sa` setting controls the seam allowance. It expects a value in mm
-
+or `false` or `0` to disable seam allowance altogether.
-Not setting this, setting it to `false`, or to zero, will draft a pattern without seam allowance.
-
 
 ```js
-import brian from "@freesewing/brian";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   sa: 10
 })
 ```
@@ -19,4 +17,9 @@ let pattern = new brian({
 
 This is ignored if [settings.complete](#complete) is `false`
 
+<Comment by="joost">
+Is it though?
+I suspect this is not clearly enforced and we should clarify that.
+</Comment>
+
 </Note>

markdown/dev/reference/api/settings/scale/en.md

@@ -0,0 +1,37 @@
+---
+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.
+
+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.
+
+```js
+import Brian from "@freesewing/brian";
+
+const pattern = new Brian({
+  scale: 0.5
+})
+```
+

markdown/dev/reference/api/settings/units/en.md

@@ -2,14 +2,16 @@
 title: units
 ---
 
-Either `metric` (the default) or `imperial`.
+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.
+Note that this is only used to format the output. 
+Freesewing expects mm as input.
 
 ```js
-import brian from "@freesewing/brian";
+import Brian from "@freesewing/brian";
 
-let pattern = new brian({
+const pattern = new Brian({
   units: "imperial"
 })
 ```