VSinerva/freesewing
1
0
Fork 0
Code Activity

chore(markdown): Updated settings docs for v3

Browse source
This commit is contained in:
Joost De Cock 2022-10-02 17:41:04 +02:00
parent d988f11062
commit 15b6ed0419
14 changed files with 281 additions and 118 deletions
Download patch file Download diff file Expand all files Collapse all files

10
markdown/dev/reference/settings/complete/en.md
View file

@ -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`.

11
markdown/dev/reference/settings/embed/en.md
View file

@ -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.

49
markdown/dev/reference/settings/en.md
View file

@ -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>

19
markdown/dev/reference/settings/idprefix/en.md
View file

@ -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"
})
```

43
markdown/dev/reference/settings/layout/en.md
View file

@ -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>

29
markdown/dev/reference/settings/locale/en.md
View file

@ -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.

43
markdown/dev/reference/settings/margin/en.md
View file

@ -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.

33
markdown/dev/reference/settings/measurements/en.md
View file

@ -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.

25
markdown/dev/reference/settings/only/en.md
View file

@ -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.

32
markdown/dev/reference/settings/options/en.md
View file

@ -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

18
markdown/dev/reference/settings/paperless/en.md
View file

@ -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
})
```

29
markdown/dev/reference/settings/sa/en.md
View file

@ -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>

36
markdown/dev/reference/settings/scale/en.md
View file

@ -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.

22
markdown/dev/reference/settings/units/en.md
View file

@ -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.