doc: add external example

Signed-off-by: Simon de Vlieger <[email protected]>

doc/03-omnifest/02-external.md

@@ -67,6 +67,64 @@ Into this YAML structure:
 dummy:
 ```
 
+## Example
+
+The following example demonstrates how an external can be used to implement string
+concatenation.
+
+Given the following script called `concat` in `/usr/local/libexec/otk/concat`:
+
+```bash
+#!/usr/bin/env bash
+
+output="$(jq -jr '.tree."otk.external.concat".parts[]' <<< "${1}")"
+echo "{\"tree\":{\"output\":\"$output\"}}"
+```
+
+and the following directive:
+
+```yaml
+examplestring:
+  otk.external.concat:
+    parts:
+      - list
+      - of
+      - strings
+```
+
+the script is called with the following data on stdin:
+
+```json
+{
+  "tree": {
+    "otk.external.concat": {
+      "parts": [
+        "list",
+        "of",
+        "strings"
+      ]
+    }
+  }
+}
+```
+
+which results in the following output:
+
+```json
+{
+  "tree": {
+    "string": "listofstrings"
+  }
+}
+```
+
+and the final omnifest will be:
+
+```yaml
+examplestring:
+  listofstrings
+```
+
 ## Paths
 
 `otk` will look for external directives in the following paths, stopping when