From 45ebd9e142c9f0b58333404a6d40416599a0013a Mon Sep 17 00:00:00 2001 From: Joost De Cock Date: Tue, 28 Dec 2021 21:07:45 +0100 Subject: [PATCH] chore(markdown): Updated settings docs --- .../dev/reference/api/settings/complete/en.md | 13 +++++-- .../dev/reference/api/settings/embed/en.md | 15 +++++--- .../dev/reference/api/settings/idprefix/en.md | 7 ++-- .../dev/reference/api/settings/layout/en.md | 20 +++++----- .../dev/reference/api/settings/locale/en.md | 8 ++-- .../dev/reference/api/settings/margin/en.md | 10 +++-- .../reference/api/settings/measurements/en.md | 8 ++-- .../dev/reference/api/settings/only/en.md | 10 +++-- .../dev/reference/api/settings/options/en.md | 9 +++-- .../reference/api/settings/paperless/en.md | 8 +++- markdown/dev/reference/api/settings/sa/en.md | 15 +++++--- .../dev/reference/api/settings/scale/en.md | 37 +++++++++++++++++++ .../dev/reference/api/settings/units/en.md | 10 +++-- 13 files changed, 119 insertions(+), 51 deletions(-) create mode 100644 markdown/dev/reference/api/settings/scale/en.md diff --git a/markdown/dev/reference/api/settings/complete/en.md b/markdown/dev/reference/api/settings/complete/en.md index 414d047fa02..9f4e62b68aa 100644 --- a/markdown/dev/reference/api/settings/complete/en.md +++ b/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. + + +Setting this to `false` will force [sa](/reference/api/settings/sa) to be set to `false`. + ```js -import brian from "@freesewing/brian"; +import Brian from "@freesewing/brian"; -let pattern = new brian({ +const pattern = new Brian({ complete: false }) ``` diff --git a/markdown/dev/reference/api/settings/embed/en.md b/markdown/dev/reference/api/settings/embed/en.md index 6115fb7783f..802157a55f7 100644 --- a/markdown/dev/reference/api/settings/embed/en.md +++ b/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 -you to inject the SVG into an HTML document, and it will responsively scale. +The default for `embed` is `false` which will include the `width` and `height` +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 }) ``` diff --git a/markdown/dev/reference/api/settings/idprefix/en.md b/markdown/dev/reference/api/settings/idprefix/en.md index 676994fd645..69f2d710c81 100644 --- a/markdown/dev/reference/api/settings/idprefix/en.md +++ b/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" }) ``` diff --git a/markdown/dev/reference/api/settings/layout/en.md b/markdown/dev/reference/api/settings/layout/en.md index 79100b0e4e9..3af67b2a611 100644 --- a/markdown/dev/reference/api/settings/layout/en.md +++ b/markdown/dev/reference/api/settings/layout/en.md @@ -2,16 +2,16 @@ title: layout --- -Allows you to control the way pattern parts are laid out on the pattern. -There are 3 scenarios: +The `layout` setting allows you to control the way pattern parts are +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 - - layout is an object: Layout the parts as detailed in the layout object +- 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: -##### 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 - + 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. - + diff --git a/markdown/dev/reference/api/settings/locale/en.md b/markdown/dev/reference/api/settings/locale/en.md index bea3fcb1924..ee27ad2008b 100644 --- a/markdown/dev/reference/api/settings/locale/en.md +++ b/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" }) ``` diff --git a/markdown/dev/reference/api/settings/margin/en.md b/markdown/dev/reference/api/settings/margin/en.md index c994fdccdb9..6efcd740eaa 100644 --- a/markdown/dev/reference/api/settings/margin/en.md +++ b/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. -Each part will have this margin applied. This means that: +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: - 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 }) ``` diff --git a/markdown/dev/reference/api/settings/measurements/en.md b/markdown/dev/reference/api/settings/measurements/en.md index cf7850b4325..e0149b8c1dc 100644 --- a/markdown/dev/reference/api/settings/measurements/en.md +++ b/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 diff --git a/markdown/dev/reference/api/settings/only/en.md b/markdown/dev/reference/api/settings/only/en.md index 7b263333589..1880bb76c8c 100644 --- a/markdown/dev/reference/api/settings/only/en.md +++ b/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"] }) ``` diff --git a/markdown/dev/reference/api/settings/options/en.md b/markdown/dev/reference/api/settings/options/en.md index c1f4639414a..5693e8a339f 100644 --- a/markdown/dev/reference/api/settings/options/en.md +++ b/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 } diff --git a/markdown/dev/reference/api/settings/paperless/en.md b/markdown/dev/reference/api/settings/paperless/en.md index 83cf5a592d1..e437883da2d 100644 --- a/markdown/dev/reference/api/settings/paperless/en.md +++ b/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 }) ``` diff --git a/markdown/dev/reference/api/settings/sa/en.md b/markdown/dev/reference/api/settings/sa/en.md index 17316fc505f..239e811dcdc 100644 --- a/markdown/dev/reference/api/settings/sa/en.md +++ b/markdown/dev/reference/api/settings/sa/en.md @@ -2,15 +2,13 @@ title: sa --- -The seam allowance in mm. - -Not setting this, setting it to `false`, or to zero, will draft a pattern without seam allowance. - +The `sa` setting controls the seam allowance. It expects a value in mm +or `false` or `0` to disable seam allowance altogether. ```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` + +Is it though? +I suspect this is not clearly enforced and we should clarify that. + + diff --git a/markdown/dev/reference/api/settings/scale/en.md b/markdown/dev/reference/api/settings/scale/en.md new file mode 100644 index 00000000000..183aa7b48f0 --- /dev/null +++ b/markdown/dev/reference/api/settings/scale/en.md @@ -0,0 +1,37 @@ +--- +title: scale +--- + + + +##### 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. + + + +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 +}) +``` + diff --git a/markdown/dev/reference/api/settings/units/en.md b/markdown/dev/reference/api/settings/units/en.md index c7856333288..8efcec00e44 100644 --- a/markdown/dev/reference/api/settings/units/en.md +++ b/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" }) ```