Move Fix Playbook-Part into Fix User Guide #37 (#48)

Also adjust the links in the documentation
metafacture · Sep 27, 2024 · a25532e · a25532e
1 parent 0d125bf
commit a25532e
Show file tree

Hide file tree

Showing 5 changed files with 46 additions and 46 deletions.
diff --git a/docs/Getting-Started.md b/docs/Getting-Started.md
@@ -12,7 +12,7 @@ The easiest way to get started with Metafacture is the Playground. Take a look a
 
 For commands available in the Flux, see [the Flux commands documentation](flux/flux-commands.html).
 
-For functions and usage of the Fix, see [the Fix functions and cookbook](fix/Fix-functions-and-Cookbook.html).
+For functions of the Fix, see [the Fix functions](fix/Fix-functions-and-Cookbook.html).
 
 For next steps get familar with [FLUX](flux/Flux-User-Guide.html) and [FIX](fix/Fix-User-Guide.html). And try out some Metafacture workflows.
 

diff --git a/docs/MF-in-5-min.md b/docs/MF-in-5-min.md
@@ -93,7 +93,7 @@ $ cat yaml2json.flux
 
 ## FIX LANGUAGE
 
-Many data conversions need a mapping from one field to another field plus optional conversions of the data inside these fields. Metafacture provides the transformation module `fix` that uses the Catmandu-inspired Fix language to assist in these mappings. See the [full list of Fix functions](fix/Fix-functions-and-Cookbook.html#functions).
+Many data conversions need a mapping from one field to another field plus optional conversions of the data inside these fields. Metafacture provides the transformation module `fix` that uses the Catmandu-inspired Fix language to assist in these mappings. See the [full list of Fix functions](fix/Fix-functions.html#functions).
 
 Fixes can be provided inline as text argument of the fix module in the Flux script, or as a pointer to a Fix script. A Fix script groups one or more fixes in a file.
 

diff --git a/docs/fix/Fix-User-Guide.md b/docs/fix/Fix-User-Guide.md
@@ -230,8 +230,6 @@ vars.put("rights", "CC-0");
 final Metafix metafix = new metafix("fixdef.fix", vars);
 ```
 
-
-
 ## Splitting Fixes for Reuse
 
 In a complex project setting there may be several Fixes in use,
@@ -244,7 +242,7 @@ Another scenario would be to reduce the size of a single fix file and create sev
 
 To accomodate for such reuse, Fix offers an include mechanism:
 
-``````
+```perl
 # Setup adds maps, macros and vars once
 do once("setup")
   include ("./fix/maps.fix")
@@ -254,3 +252,43 @@ end
 ```
 
 For performance reasons it is useful to integrate macros and maps that are used often in a `do once` bind.
+
+## Cookbook
+
+This page is a replication of the passages [Best practices and guidelines for working with Metafacture Fix](https://github.com/metafacture/metafacture-fix?tab=readme-ov-file#best-practices-and-guidelines-for-working-with-metafacture-fix) and [Glossary](https://github.com/metafacture/metafacture-fix?tab=readme-ov-file#glossary) of the Fix Readme.md. Status: [Fix Release 1.1.2](https://github.com/metafacture/metafacture-fix/releases/tag/1.1.2)
+
+### Best practices and guidelines for working with Metafacture Fix
+
+- We recommend to use double quotation marks for arguments and values in functions, binds and conditionals.
+- If using a `list` bind with a variable, the `var` option requires quotation marks (`do list(path: "<sourceField>", "var": "<variableName>")`).
+- Fix turns repeated fields into arrays internally but only marked arrays (with `[]` at the end of the field name) are also emitted as "arrays" (entities with indexed literals), all other arrays are emitted as repeated fields.
+- Every Fix file should end with a final newline.
+
+### Glossary
+
+#### Array wildcards
+
+Array wildcards resemble [Catmandu's concept of wildcards](http://librecat.org/Catmandu/#wildcards).
+
+When working with arrays and repeated fields you can use wildcards instead of an index number to select elements of an array.
+
+| Wildcard | Meaning |
+|----------|:--------|
+| `*` | Selects _all_ elements of an array. |
+| `$first` | Selects only the _first_ element of an array. |
+| `$last` | Selects only the _last_ element of an array. |
+| `$prepend` | Selects the position _before_ the first element of an array. Can only be used when adding new elements to an array. |
+| `$append` | Selects the position _after_ the last element of an array. Can only be used when adding new elements to an array. |
+
+#### Path wildcards
+
+Path wildcards resemble [Metamorph's concept of wildcards](https://github.com/metafacture/metafacture-core/wiki/Metamorph-User-Guide#addressing-pieces-of-data). They are not supported in Catmandu (it has [specialized Fix functions](https://librecat.org/Catmandu/#marc-mab-pica-paths) instead).
+
+You can use path wildcards to select fields matching a pattern. They only match path _segments_ (field names), though, not _whole_ paths of nested fields. These wildcards cannot be used to add new elements.
+
+| Wildcard | Meaning |
+|----------|:--------|
+| `*` | Placeholder for zero or more characters. |
+| `?` | Placeholder for exactly one character. |
+| `\|` | Alternation of multiple patterns. |
+| `[...]` | Enumeration of characters. |
diff --git a/docs/fix/Fix-functions-and-Cookbook.md → docs/fix/Fix-functions.md b/docs/fix/Fix-functions-and-Cookbook.md → docs/fix/Fix-functions.md
@@ -1,49 +1,11 @@
 ---
 layout: default
-title: Fix Functions and Cookbook
+title: Fix Functions
 parent: Fix
 nav_order: 2
 ---
 
-This page is a replication of the passage [Fix Functions and Cookbook](https://github.com/metafacture/metafacture-fix?tab=readme-ov-file#functions-and-cookbook) of the Fix Readme.md. Status: [Fix Release 1.1.2](https://github.com/metafacture/metafacture-fix/releases/tag/1.1.2)
-
-## Functions and cookbook
-
-### Best practices and guidelines for working with Metafacture Fix
-
-- We recommend to use double quotation marks for arguments and values in functions, binds and conditionals.
-- If using a `list` bind with a variable, the `var` option requires quotation marks (`do list(path: "<sourceField>", "var": "<variableName>")`).
-- Fix turns repeated fields into arrays internally but only marked arrays (with `[]` at the end of the field name) are also emitted as "arrays" (entities with indexed literals), all other arrays are emitted as repeated fields.
-- Every Fix file should end with a final newline.
-
-### Glossary
-
-#### Array wildcards
-
-Array wildcards resemble [Catmandu's concept of wildcards](http://librecat.org/Catmandu/#wildcards).
-
-When working with arrays and repeated fields you can use wildcards instead of an index number to select elements of an array.
-
-| Wildcard | Meaning |
-|----------|:--------|
-| `*` | Selects _all_ elements of an array. |
-| `$first` | Selects only the _first_ element of an array. |
-| `$last` | Selects only the _last_ element of an array. |
-| `$prepend` | Selects the position _before_ the first element of an array. Can only be used when adding new elements to an array. |
-| `$append` | Selects the position _after_ the last element of an array. Can only be used when adding new elements to an array. |
-
-#### Path wildcards
-
-Path wildcards resemble [Metamorph's concept of wildcards](https://github.com/metafacture/metafacture-core/wiki/Metamorph-User-Guide#addressing-pieces-of-data). They are not supported in Catmandu (it has [specialized Fix functions](https://librecat.org/Catmandu/#marc-mab-pica-paths) instead).
-
-You can use path wildcards to select fields matching a pattern. They only match path _segments_ (field names), though, not _whole_ paths of nested fields. These wildcards cannot be used to add new elements.
-
-| Wildcard | Meaning |
-|----------|:--------|
-| `*` | Placeholder for zero or more characters. |
-| `?` | Placeholder for exactly one character. |
-| `\|` | Alternation of multiple patterns. |
-| `[...]` | Enumeration of characters. |
+This page is a replication of the passage [Functions](https://github.com/metafacture/metafacture-fix?tab=readme-ov-file#functions) of the Fix Readme.md. Status: [Fix Release 1.1.2](https://github.com/metafacture/metafacture-fix/releases/tag/1.1.2)
 
 ### Functions
 

diff --git a/docs/fix/fix.md b/docs/fix/fix.md
@@ -13,7 +13,7 @@ If you are using **Metafacture as a Java library**, create a Metafix object and
 
 The transformation itself is declared in a fix-object which can be a file. For more information on how to declare transformations see [Metafix User Guide](Fix-User-Guide.html).
 
-See [here a list for all available FIX functions and a cookbook for using fix](Fix-functions-and-Cookbook.html).
+See [here a list for all available FIX functions](Fix-functions.html).
 
 {: .note }
 PS: There is also the transformation module MORPH. Have a look at [the old documentation](https://github.com/metafacture/metafacture-core/wiki/Metamorph-User-Guide) and the German cookbook by [Swissbib](https://swissbib.gitlab.io/metamorph-doku/).