chore: Updated title macro docs

markdown/dev/howtos/code/adding-text/en.md

@@ -9,31 +9,24 @@ provides the [Point.addText()](/reference/api/point/addtext) and
 [Path.addText()](/reference/api/path/addtext) methods to let you add text to
 points and paths.
 
-<Example caption="An example of adding text" tutorial>
+In addition, [the `title` macro](/reference/macros/title) not only lets you add a
-```design/src/part.mjs
+title to your part, it also allows you to add notes.
-function draftPart = ({ 
-  Point,
-  points,
-  Path, 
-  paths,
-  part 
-}) {
 
-  points.demo = new Point(70,10)
+## Wrapping lines
-  // highlight-start
-    .addText('Text on a point', 'center')
-  // highlight-end
 
-  paths.demo = new Path()
+SVG does not provide any line-wrapping, so you will need to be mindful of that when you add longer text.
-    .move(new Point(0,0))
-    .line(new Point(100, 40))
-    .addClass('note dotted stroke-sm')
-  // highlight-start
-    .addText('Text on a path', 'center')
-  // highlight-end
 
+To facilitate this, FreeSewing will enforce a line break when you use `\n` in your text.
+
+## Translation
+
+Text that is added to a pattern typically requires translation. 
+You should break up your text in such a way that it remains possible to translate it.
+
+You can do that either via repeated calls to `addText()` or you can pass an array of strings, or even a nested array of strings, and FreeSewing will translate all individual pieces prior to contatenating them.
+
+<Note compact noP>
+
+Refer to [the `insertText` hook](/reference/hooks/inserttext#notes) for details.
+</Note>
 
-  return part
-}
-```
-</Example>

markdown/dev/reference/macros/en.md

@@ -47,6 +47,24 @@ Now you can use these macros in your part:
 }
 ```
 
+## Removing macros and the role of the macro id
+
+Many macros accept an `id` parameter as part of their configuration.  This `id`
+is used to generate the names for paths, points, or snippets that are added to
+the part by the macro.  This way, macro-added content is deterministic, and can
+be removed again.
+
+Each macro typically has an `rm`-prefixed counterpart that removes the (changed
+done by) the macro.  For example, you can add a bartack with the `bartack`
+macro, and it can be removed with the `rmbartack` macro.  For this removal to
+work, and id must be set in the macro, and it must be passed when removing the
+macro.
+
+For macros that are typically used once per part (such as the `title` macro)
+you can rely on the default id.  For macros typically used multiple times (such
+as the various dimension macros) you should set an id that is unique within the
+part for each invocation.
+
 ## Macros we maintain
 
 Below is a list of macros from [the plugins we maintain](/reference/plugins).

markdown/dev/reference/macros/title/en.md

@@ -11,17 +11,26 @@ part of [core-plugins](/reference/plugins/core) (so it is available by default).
 
 ```js
 macro('title', {
-  String id = 'title',
+  String align = 'left',
-  String align,
+  Boolean append = false,
-  Boolean append,
   Point at,
-  Boolean cutlist
+  String brand = 'FreeSewing',
-  String nr,
+  Boolean cutlist = true,
-  String prefix,
+  Number dy = 8,
-  Number rotation,
-  Number scale,
-  String title,
   Boolean force = false,
+  String id = 'title',
+  Mixed notes = false,
+  String nr,
+  Number rotation = 0,
+  Number scale = 1,
+  String title = 'plugin-annotations:noName',
+  classes = {
+    String date: 'text-sm fill-current',
+    String name: 'fill-note',
+    String notes: 'text-md fill-current',
+    String nr: 'text-4xl fill-note font-bold',
+    String title: 'text-lg fill-current font-bold',
+  }
 })
 ```
 
@@ -34,7 +43,7 @@ macro('title', {
   // This is where name/version/etc. is supposed to be stored
   store.set('data.version', 3)
   store.set('data.name', 'Example')
-  store.set('data.for', 'Person')
+  store.set('data.for', 'Sorcha')
 
   macro('title', {
     nr: 9,
@@ -45,7 +54,7 @@ macro('title', {
   // Prevent clipping
   paths.diag = new Path()
     .move(new Point(-20,-50))
-    .move(new Point(80,35))
+    .move(new Point(120,35))
 
   return part
 }
@@ -56,19 +65,30 @@ macro('title', {
 
 | Property   | Default | Type                | Description |
 | ----------:| :-----: | ------------------- | ----------- |
-| `align'    | 'left'  | String              | Horizontal text alignment. Valid values: 'left', 'right', 'center' |
+| `align`    | `left`  | String              | Horizontal text alignment. One of `left`, `right`, or `center` |
-| `append`   | `false` | Boolean             | Set this to `true` to append the `nr` to any text already set in Point `at`'s attributes, rather than overwrite it |
+| `append`   | `false` | Boolean             | Set this to `true` to append the `nr`, rather than overwrite it |
 | `at`       |         | [Point](/reference/api/point) | The point at which to insert the title |
-| `cutlist`  | `true`  | Boolean             | Whether to include cutting instructions |
+| `brand`    | `FreeSewing`  | String | Brand name will prefix the design name |
-| `id`       | `title` | `string` | The ID of this macro instance |
+| `classes.date`  | `text-sm fill-current`  | String | CSS classes for the date |
+| `classes.name`  | `fill-note`  | String | CSS classes for the name |
+| `classes.notes`  | `text-md fill-current`  | String | CSS classes for the notes |
+| `classes.nr`  | `text-4xl fill-note font-bold`  | String | CSS classes for the nr |
+| `classes.title`  | `text-lg fill-current font-bold`  | String | CSS classes for the title |
+| `cutlist`  | `true`  | Boolean             | Set this to `true` to prepend notes with the cutting instructions |
+| `dy`       | `8`     | Number              | SVG-equivalent of line height, controls the vertical spacing between text lines |
+| `force`    | `false` | `boolean`           | Set this to `true` to display the macro output even when `complete` is `false` |
+| `id`       | `title` | `string` | The ID of this macro instance. See [Removing macros and the role of the macro id](/reference/macros#removing-macros-and-the-role-of-the-macro-id) |
+| `notes`    | | String | Any notes to go under the title |
 | `nr`       |         | String              | The number of the pattern part |
-| `title`    |         | String              | The name of the pattern part. If title is not set or is an empty string, this won't be rendered, and the version will go beneath the nr.|
+| `rotation` | `0`     | Number              | Rotation in degrees |
+| `scale`    | 1       | Number              | An optional scaling factor to make the title bigger/smaller |
+| `title`    | `plugin-annotations:noName` | String | The name of the pattern part |
 | `prefix`   |         | String              | A prefix to add to the created points. This allow for more than 1 title per part, as long as you give them a different prefix.|
-| `rotation` | 0       | Number | An optional rotation in degrees |
+
-| `scale`    | 1       | Number | An optional scaling factor |
-| `force`      | `false`    | `boolean`  | Set this to `true` to display the macro output even when `complete` is `false` |
 
 ## Notes
 
-This macro takes the `complete` setting into account and won't output anything when both complete and `force` are `false`.
+- This macro takes the `complete` setting into account and won't output anything when both complete and `force` are `false`.
+- This macro will check the value of `store.version` and `store.name` for the design version and name. These are auto-set by core.
+- This macro will check the value of `store.for` for info of who this pattern was generated for. This is something to be done at run-time by your frontend.