This is an automated email from the ASF dual-hosted git repository.

davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-kamelets.git


The following commit(s) were added to refs/heads/main by this push:
     new 6b6cbdfa6 chore: describe the template, crypto and PDF Kamelets for 
people and AI assistants (#3143)
6b6cbdfa6 is described below

commit 6b6cbdfa6a3a9ad34c370f51d849e1fdaf47d0c6
Author: Claus Ibsen <[email protected]>
AuthorDate: Tue Nov 17 11:25:57 2026 +0100

    chore: describe the template, crypto and PDF Kamelets for people and AI 
assistants (#3143)
    
    * chore: describe the template, crypto and PDF Kamelets for people and AI 
assistants
    
    Rewrites the descriptions and options of 10 Kamelets to the standard of
    docs/modules/ROOT/pages/documenting.adoc (#3140): freemarker, velocity,
    mvel and string-template template actions, jolt-transformation-action,
    jslt-action, xj-identity-action, crypto-encrypt-action,
    crypto-decrypt-action and pdf-action. Each was run, on Camel 4.24 and
    4.23, to check what it says: the syntax with which each template language
    reads the body and the headers, and what it does with a missing value; the
    kind of body each JSON action accepts and gives; the key lengths of the
    crypto actions; and the font names pdf-action accepts.
    
    chunk-template-action and xj-template-action are left out: their templates
    do not work as written, and they will be described with their fixes.
    
    Co-Authored-By: Claude Opus 5.5 <[email protected]>
    
    * chore: escape a brace before a name in Kamelet descriptions
    
    The documentation page renders descriptions and partial pages as
    AsciiDoc, where {body} is an attribute reference that fails the
    documentation check: write $\{body}, as the Camel documentation does.
    
    Co-Authored-By: Claude Opus 5.5 <[email protected]>
    
    ---------
    
    Co-authored-by: Claude Opus 5.5 <[email protected]>
---
 kamelets/crypto-decrypt-action.kamelet.yaml        | 15 ++++++--
 kamelets/crypto-encrypt-action.kamelet.yaml        | 15 ++++++--
 kamelets/freemarker-template-action.kamelet.yaml   | 13 +++++--
 kamelets/jolt-transformation-action.kamelet.yaml   | 17 ++++++---
 kamelets/jslt-action.kamelet.yaml                  | 13 +++++--
 kamelets/mvel-template-action.kamelet.yaml         | 13 +++++--
 kamelets/pdf-action.kamelet.yaml                   | 19 +++++++---
 kamelets/string-template-action.kamelet.yaml       | 13 +++++--
 kamelets/velocity-template-action.kamelet.yaml     | 13 +++++--
 kamelets/xj-identity-action.kamelet.yaml           | 11 ++++--
 .../main/resources/META-INF/kamelets-index.json    | 40 +++++++++++-----------
 .../kamelets/crypto-decrypt-action.kamelet.yaml    | 15 ++++++--
 .../kamelets/crypto-encrypt-action.kamelet.yaml    | 15 ++++++--
 .../freemarker-template-action.kamelet.yaml        | 13 +++++--
 .../jolt-transformation-action.kamelet.yaml        | 17 ++++++---
 .../resources/kamelets/jslt-action.kamelet.yaml    | 13 +++++--
 .../kamelets/mvel-template-action.kamelet.yaml     | 13 +++++--
 .../resources/kamelets/pdf-action.kamelet.yaml     | 19 +++++++---
 .../kamelets/string-template-action.kamelet.yaml   | 13 +++++--
 .../kamelets/velocity-template-action.kamelet.yaml | 13 +++++--
 .../kamelets/xj-identity-action.kamelet.yaml       | 11 ++++--
 21 files changed, 252 insertions(+), 72 deletions(-)

diff --git a/kamelets/crypto-decrypt-action.kamelet.yaml 
b/kamelets/crypto-decrypt-action.kamelet.yaml
index 30d181a8c..d3174a96a 100644
--- a/kamelets/crypto-decrypt-action.kamelet.yaml
+++ b/kamelets/crypto-decrypt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "Crypto Decrypt Action"
-    description: Decrypt the payload using the Java Cryptographic Extension 
(JCE) and a fixed key.
+    description: |-
+      Decrypts the body of each message that `crypto-encrypt-action` 
encrypted, with the same algorithm and secret key.
+
+      Use it to get back the original data that was encrypted with 
`crypto-encrypt-action`, for example after reading it from storage or receiving 
it from another system.
+
+      Input: the encrypted data exactly as `crypto-encrypt-action` produced 
it, as bytes or a stream. If it was encoded on the way, for example in Base64, 
decode it first.
+
+      Output: the body is the original data, as bytes (a stream). The headers 
are kept.
+
+      Good to know: data that was changed, or a different `algorithm` or `key` 
than when encrypting, fails the message with "Message authentication failed". 
The key is a secret; keep it in a vault or a secret, not in plain configuration.
     required:
       - algorithm
       - key
@@ -38,12 +47,12 @@ spec:
     properties:
       algorithm:
         title: Algorithm
-        description: The JCE algorithm name indicating the cryptographic 
algorithm that will be used.
+        description: "The name of the encryption algorithm the data was 
encrypted with, such as `AES`, or `DESede` for Triple DES. Give the name alone: 
a full form such as `AES/CBC/PKCS5Padding` fails each message."
         type: string
         example: "AES"
       key:
         title: Secret Key
-        description: The secret key to use to decrypt the payload. The length 
must match the requirements of the selected algorithm (for example 16, 24 or 32 
bytes for AES).
+        description: "The secret key the data was encrypted with, as text. Its 
length must fit the algorithm: for `AES`, 16, 24 or 32 characters (plain ASCII 
characters count as one byte each), and for `DESede`, 24."
         type: string
         format: password
         x-descriptors:
diff --git a/kamelets/crypto-encrypt-action.kamelet.yaml 
b/kamelets/crypto-encrypt-action.kamelet.yaml
index 49a785d14..756129ff3 100644
--- a/kamelets/crypto-encrypt-action.kamelet.yaml
+++ b/kamelets/crypto-encrypt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "Crypto Encrypt Action"
-    description: Encrypt the payload using the Java Cryptographic Extension 
(JCE) and a fixed key.
+    description: |-
+      Encrypts the body of each message with a secret key, such as an AES key, 
for `crypto-decrypt-action` to decrypt later with the same key.
+
+      Use it to protect sensitive data, such as personal or payment details, 
before it is stored or sent through a system you do not fully trust, and 
decrypt it later with `crypto-decrypt-action` and the same `algorithm` and 
`key`.
+
+      Input: text or bytes.
+
+      Output: the body is the encrypted data, as bytes (a stream), a little 
longer than the input. It is not text: to send it where only text fits, encode 
it, for example in Base64. The headers are kept.
+
+      Good to know: the key is a secret; anyone who has it can decrypt the 
data, so keep it in a vault or a secret, not in plain configuration. The 
encrypted data carries a check value, so `crypto-decrypt-action` fails on data 
that was changed or decrypted with another key. A key of the wrong length fails 
each message, not the start.
     required:
       - algorithm
       - key
@@ -38,12 +47,12 @@ spec:
     properties:
       algorithm:
         title: Algorithm
-        description: The JCE algorithm name indicating the cryptographic 
algorithm that will be used.
+        description: "The name of the encryption algorithm, such as `AES`, or 
`DESede` for Triple DES. Give the name alone: a full form such as 
`AES/CBC/PKCS5Padding` fails each message. Use the same value in 
`crypto-decrypt-action`."
         type: string
         example: "AES"
       key:
         title: Secret Key
-        description: The secret key to use to encrypt the payload. The length 
must match the requirements of the selected algorithm (for example 16, 24 or 32 
bytes for AES).
+        description: "The secret key, as text. Its length must fit the 
algorithm: for `AES`, 16, 24 or 32 characters (plain ASCII characters count as 
one byte each), and for `DESede`, 24. Use the same key in 
`crypto-decrypt-action`."
         type: string
         format: password
         x-descriptors:
diff --git a/kamelets/freemarker-template-action.kamelet.yaml 
b/kamelets/freemarker-template-action.kamelet.yaml
index eec62844a..2ac812947 100644
--- a/kamelets/freemarker-template-action.kamelet.yaml
+++ b/kamelets/freemarker-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "Freemarker Template Action"
-    description: Apply a Freemarker Template.
+    description: |-
+      Builds a new message body from a FreeMarker template, filling in values 
from the incoming message.
+
+      Use it to turn data into text for people or for another system, such as 
an email, a report or a small XML or JSON document, when you already have 
FreeMarker templates or need its loops and conditions. For simple templates, 
`mustache-template-action` is an alternative; to reshape JSON into other JSON, 
`jslt-action` is often simpler.
+
+      Input: any body. The template sees the body as `$\{body}` and a header 
as `${headers.name}`, for example `Dear ${headers.customer}, your order 
$\{body} has shipped.`
+
+      Output: the body is the text the template produced. The headers are kept.
+
+      Good to know: a value the template uses that is missing, such as a 
header that is not set, fails the message; give a default with 
`${headers.customer!""}`. A template file that cannot be found fails the 
message too. The template is loaded from a file, the classpath or a URL given 
by the `template` option; it cannot come from the message.
     required:
       - template
     type: object
@@ -39,7 +48,7 @@ spec:
         title: Template
         description: "Where to load the FreeMarker template from, not the 
FreeMarker template itself: `file://` followed by the path of a file, 
`classpath://` followed by a resource in the application, or an `http://` or 
`https://` URL."
         type: string
-        example: "file:////template.ftl"
+        example: "file:///opt/templates/order.ftl"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
   dependencies:
   - "camel:freemarker"
diff --git a/kamelets/jolt-transformation-action.kamelet.yaml 
b/kamelets/jolt-transformation-action.kamelet.yaml
index d6e122884..bcf5c7f26 100644
--- a/kamelets/jolt-transformation-action.kamelet.yaml
+++ b/kamelets/jolt-transformation-action.kamelet.yaml
@@ -30,20 +30,29 @@ metadata:
 spec:
   definition:
     title: "Jolt Transformation Action"
-    description: Apply a Jolt Transformation.
+    description: |-
+      Reshapes each JSON message into other JSON, as a Jolt specification 
describes: moves, renames, removes fields or adds defaults.
+
+      Use it to map the JSON of one system to the JSON another system expects, 
for example to rename fields or move them into a nested object, when you 
already have Jolt specifications. `jslt-action` does the same with a query 
language, and is often easier to write.
+
+      Input: parsed JSON, a Map (or a List). Since Camel 4.24, JSON text, 
bytes and a stream work too. With older versions they do not fail but give an 
empty body, and so does the parsed JSON of `json-deserialize-action`.
+
+      Output: the body is the result as parsed JSON, a Map (or a List), not 
JSON text. Add `json-serialize-action` after it to get JSON text. The headers 
are kept.
+
+      Good to know: the specification cannot read headers, only the body. It 
is loaded from a file, the classpath or a URL given by the `template` option; 
it cannot come from the message.
     required:
       - template
     type: object
     properties:
       template:
         title: Template
-        description: "Where to load the Jolt specification from, not the Jolt 
specification itself: `file://` followed by the path of a file, `classpath://` 
followed by a resource in the application, or an `http://` or `https://` URL."
+        description: "Where to load the Jolt specification from, not the Jolt 
specification itself: `file://` followed by the path of a file, `classpath://` 
followed by a resource in the application, or an `http://` or `https://` URL. 
With the default `transform`, the file holds a JSON array of steps, such as 
`[{\"operation\": \"shift\", \"spec\": {\"name\": \"customer.fullName\"}}]`."
         type: string
-        example: "file:////template.json"
+        example: "file:///opt/templates/order-spec.json"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
       transform:
         title: Transform DSL
-        description: Specifies the Transform DSL of the endpoint resource. If 
none is specified, Chainr is used.
+        description: "The kind of Jolt specification in the `template` file. 
`Chainr`, the default, is a list of steps, each with an `operation` (such as 
`shift`, `default` or `remove`) and a `spec`. The others take the spec of one 
operation alone: `Shiftr` moves and renames fields, `Defaultr` adds default 
values, `Removr` removes fields, and `Sortr` sorts the fields by name."
         type: string
         default: "Chainr"
         enum: ["Chainr", "Shiftr", "Defaultr", "Removr", "Sortr"]
diff --git a/kamelets/jslt-action.kamelet.yaml 
b/kamelets/jslt-action.kamelet.yaml
index 2658082b9..32c8e9b40 100644
--- a/kamelets/jslt-action.kamelet.yaml
+++ b/kamelets/jslt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "JSLT Action"
-    description: Apply a JSLT query or transformation on JSON.
+    description: |-
+      Turns each JSON message into new JSON with a JSLT transformation, a 
query language for JSON that picks, renames and computes fields.
+
+      Use it to map the JSON of one system to the JSON another system expects, 
for example to keep only some fields, rename them or count the items of an 
order. To build text rather than JSON, use `mustache-template-action`; 
`jolt-transformation-action` reshapes JSON with Jolt specifications instead.
+
+      Input: JSON text, bytes or a stream. The transformation sees the body as 
`.` and a header as `$headers.name`, for example `{"customer": .name, "items": 
size(.items), "source": $headers.origin}`.
+
+      Output: the body is the result as JSON text. The headers are kept.
+
+      Good to know: parsed JSON (a Map or a JsonNode, such as the output of 
`json-deserialize-action`) fails the message: give the JSON as text. A field 
whose value is missing, such as a header that is not set, is left out of the 
result. The transformation is loaded from a file, the classpath or a URL given 
by the `template` option; it cannot come from the message.
     required:
       - template
     type: object
@@ -39,7 +48,7 @@ spec:
         title: Template
         description: "Where to load the JSLT transformation from, not the JSLT 
transformation itself: `file://` followed by the path of a file, `classpath://` 
followed by a resource in the application, or an `http://` or `https://` URL."
         type: string
-        example: "file://template.json"
+        example: "file:///opt/templates/order.jslt"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
   dependencies:
   - "camel:jslt"
diff --git a/kamelets/mvel-template-action.kamelet.yaml 
b/kamelets/mvel-template-action.kamelet.yaml
index 215a4bb83..bc32eb5bf 100644
--- a/kamelets/mvel-template-action.kamelet.yaml
+++ b/kamelets/mvel-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "Mvel Template Action"
-    description: Apply a Mvel Template.
+    description: |-
+      Builds a new message body from an MVEL template, filling in values from 
the incoming message.
+
+      Use it to turn data into text for people or for another system, such as 
the text of an email or a small XML or JSON document, when you already have 
MVEL templates. For simple templates, `mustache-template-action` is an 
alternative; to reshape JSON into other JSON, `jslt-action` is often simpler.
+
+      Input: any body. The template sees the body as `@\{body}` and a header 
as `@{headers.name}`, for example `Dear @{headers.customer}, your order 
@\{body} has shipped.`
+
+      Output: the body is the text the template produced. The headers are kept.
+
+      Good to know: a header the template uses that is not set fails the 
message, and so does a template file that cannot be found. The template is 
loaded from a file, the classpath or a URL given by the `template` option; it 
cannot come from the message.
     required:
       - template
     type: object
@@ -39,7 +48,7 @@ spec:
         title: Template
         description: "Where to load the MVEL template from, not the MVEL 
template itself: `file://` followed by the path of a file, `classpath://` 
followed by a resource in the application, or an `http://` or `https://` URL."
         type: string
-        example: "file:////template.mvel"
+        example: "file:///opt/templates/order.mvel"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
   dependencies:
   - "camel:mvel"
diff --git a/kamelets/pdf-action.kamelet.yaml b/kamelets/pdf-action.kamelet.yaml
index d0ddc4a5b..93d5a7593 100644
--- a/kamelets/pdf-action.kamelet.yaml
+++ b/kamelets/pdf-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "PDF Action"
-    description: Create a PDF.
+    description: |-
+      Turns the text of each message into a PDF document, with one font, font 
size and page size for the whole text.
+
+      Use it to produce a simple printable document, such as a receipt, a 
report or a log, that is then stored as a file or sent by email. To lay out the 
text first, put a template action before it, such as `mustache-template-action`.
+
+      Input: the body is the text to write, as text. Each line of the text 
starts a new line in the PDF, and a new page starts when a page is full.
+
+      Output: the body is the PDF document, as bytes. The headers are kept as 
they are; a `Content-Type` header set before is not changed to PDF.
+
+      Good to know: long lines are not wrapped; they run past the right edge 
of the page. Set `font` to one of the names its description lists, such as 
`HELVETICA`: the default value `Helvetica` fails each message.
     required:
       - font
       - fontSize
@@ -39,19 +48,21 @@ spec:
     properties:
       font:
         title: Font
-        description: The font to use while generating the PDF. One of Courier, 
Courier-Bold, Courier-Oblique, Courier-BoldOblique, Helvetica, Helvetica-Bold, 
Helvetica-Oblique, Helvetica-BoldOblique, Times-Roman, Times-Bold, 
Times-Italic, Times-BoldItalic, Symbol, ZapfDingbats
+        description: "The font of the whole text, one of the standard PDF 
fonts: `COURIER`, `COURIER_BOLD`, `COURIER_OBLIQUE`, `COURIER_BOLD_OBLIQUE`, 
`HELVETICA`, `HELVETICA_BOLD`, `HELVETICA_OBLIQUE`, `HELVETICA_BOLD_OBLIQUE`, 
`TIMES_ROMAN`, `TIMES_BOLD`, `TIMES_ITALIC`, `TIMES_BOLD_ITALIC`, `SYMBOL` or 
`ZAPF_DINGBATS`. Write the name in capitals with underscores: `Helvetica` or 
`Times-Roman` fails each message."
         type: string
         default: HELVETICA
+        example: "HELVETICA"
       fontSize:
         title: Font Size
-        description: The Font size to use while generating the PDF
+        description: "The size of the text, in points, such as `12` or `10.5`. 
72 points make one inch."
         type: string
         default: 14.0
       pageSize:
         title: Page Size
-        description: The Page size to use while generating the PDF. One of 
LETTER, LEGAL, A0, A1, A2, A3, A4, A5, A6
+        description: "The size of the pages: `A0` to `A6` (`A4` is 210 by 297 
millimetres), `LETTER` (8.5 by 11 inches) or `LEGAL` (8.5 by 14 inches)."
         type: string
         default: A4
+        enum: ["LETTER", "LEGAL", "A0", "A1", "A2", "A3", "A4", "A5", "A6"]
   dependencies:
   - "camel:pdf"
   - "camel:kamelet"
diff --git a/kamelets/string-template-action.kamelet.yaml 
b/kamelets/string-template-action.kamelet.yaml
index ea14a4148..3604580ba 100644
--- a/kamelets/string-template-action.kamelet.yaml
+++ b/kamelets/string-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "String Template Action"
-    description: Apply a String Template.
+    description: |-
+      Builds a new message body from a StringTemplate template, filling in 
values from the incoming message.
+
+      Use it to turn data into text for people or for another system, such as 
the text of an email or a small XML or JSON document, when you already have 
StringTemplate templates. For simple templates, `mustache-template-action` is 
an alternative; to reshape JSON into other JSON, `jslt-action` is often simpler.
+
+      Input: any body. The template sees the body as `<body>` and a header as 
`<headers.name>`, for example `Dear <headers.customer>, your order <body> has 
shipped.`
+
+      Output: the body is the text the template produced. The headers are 
kept, and a `CamelStringTemplateResourceUri` header is added with the location 
of the template.
+
+      Good to know: a header the template uses that is not set gives nothing 
in the text. A template file that cannot be found fails the message. The 
template is loaded from a file, the classpath or a URL given by the `template` 
option; it cannot come from the message.
     required:
       - template
     type: object
@@ -39,7 +48,7 @@ spec:
         title: Template
         description: "Where to load the StringTemplate template from, not the 
StringTemplate template itself: `file://` followed by the path of a file, 
`classpath://` followed by a resource in the application, or an `http://` or 
`https://` URL."
         type: string
-        example: "file:////template.tm"
+        example: "file:///opt/templates/order.st"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
   dependencies:
   - "camel:stringtemplate"
diff --git a/kamelets/velocity-template-action.kamelet.yaml 
b/kamelets/velocity-template-action.kamelet.yaml
index 1658ebc48..7e87edd85 100644
--- a/kamelets/velocity-template-action.kamelet.yaml
+++ b/kamelets/velocity-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "Velocity Template Action"
-    description: Apply a Velocity Template.
+    description: |-
+      Builds a new message body from an Apache Velocity template, filling in 
values from the incoming message.
+
+      Use it to turn data into text for people or for another system, such as 
an email, a report or a small XML or JSON document, when you already have 
Velocity templates or need its loops and conditions. For simple templates, 
`mustache-template-action` is an alternative; to reshape JSON into other JSON, 
`jslt-action` is often simpler.
+
+      Input: any body. The template sees the body as `$\{body}` and a header 
as `${headers.name}`, for example `Dear ${headers.customer}, your order 
$\{body} has shipped.`
+
+      Output: the body is the text the template produced. The headers are kept.
+
+      Good to know: a value the template uses that is missing, such as a 
header that is not set, stays in the text as written, for example 
`${headers.customer}`; write `$!{headers.customer}` to get nothing instead. A 
template file that cannot be found fails the message. The template is loaded 
from a file, the classpath or a URL given by the `template` option; it cannot 
come from the message.
     required:
       - template
     type: object
@@ -39,7 +48,7 @@ spec:
         title: Template
         description: "Where to load the Velocity template from, not the 
Velocity template itself: `file://` followed by the path of a file, 
`classpath://` followed by a resource in the application, or an `http://` or 
`https://` URL."
         type: string
-        example: "file:////template.vm"
+        example: "file:///opt/templates/order.vm"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
   dependencies:
   - "camel:velocity"
diff --git a/kamelets/xj-identity-action.kamelet.yaml 
b/kamelets/xj-identity-action.kamelet.yaml
index 739cb2ba2..afd7547d6 100644
--- a/kamelets/xj-identity-action.kamelet.yaml
+++ b/kamelets/xj-identity-action.kamelet.yaml
@@ -31,14 +31,21 @@ metadata:
 spec:
   definition:
     title: "XJ Identity Action"
-    description: Apply the XJ Identity Transformation to transform JSON to XML 
and XML to JSON.
+    description: |-
+      Converts each message from XML to JSON, or from JSON to XML, with a 
fixed mapping and no template to write.
+
+      Use it to pass XML to a system that expects JSON, or the other way 
round, when the default mapping is good enough. To control the result, such as 
the names of the elements or which fields to keep, use `xj-template-action` 
with an XSLT stylesheet.
+
+      Input: XML or JSON as text, bytes or a stream, as `direction` says. 
Parsed JSON, such as a Map, fails the message.
+
+      Output: the body is JSON text or XML text. From XML, the root element is 
dropped, its attributes and child elements become fields, repeated elements 
become an array, and all values are text: `<order id="7"><qty>2</qty></order>` 
gives `{"id":"7","qty":"2"}`. To XML, each JSON value becomes an `object` 
element that keeps its name and type in `xj:name` and `xj:type` attributes, 
such as `<object xj:name="qty" xj:type="int">2</object>`. The headers are kept.
     required:
       - direction
     type: object
     properties:
       direction:
         title: Direction
-        description: The transform direction.
+        description: "Which way to convert: `XML2JSON` turns XML into JSON, 
and `JSON2XML` turns JSON into XML."
         type: string
         enum: ["XML2JSON", "JSON2XML"]
   dependencies:
diff --git 
a/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json 
b/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json
index d6b42583c..4739111ed 100644
--- a/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json
+++ b/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json
@@ -654,8 +654,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Crypto Decrypt Action",
-    "summary" : "Decrypt the payload using the Java Cryptographic Extension 
(JCE) and a fixed key.",
-    "description" : "Decrypt the payload using the Java Cryptographic 
Extension (JCE) and a fixed key.",
+    "summary" : "Decrypts the body of each message that 
`crypto-encrypt-action` encrypted, with the same algorithm and secret key.",
+    "description" : "Decrypts the body of each message that 
`crypto-encrypt-action` encrypted, with the same algorithm and secret 
key.\n\nUse it to get back the original data that was encrypted with 
`crypto-encrypt-action`, for example after reading it from storage or receiving 
it from another system.\n\nInput: the encrypted data exactly as 
`crypto-encrypt-action` produced it, as bytes or a stream. If it was encoded on 
the way, for example in Base64, decode it first.\n\nOutput: the body  [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -664,8 +664,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Crypto Encrypt Action",
-    "summary" : "Encrypt the payload using the Java Cryptographic Extension 
(JCE) and a fixed key.",
-    "description" : "Encrypt the payload using the Java Cryptographic 
Extension (JCE) and a fixed key.",
+    "summary" : "Encrypts the body of each message with a secret key, such as 
an AES key, for `crypto-decrypt-action` to decrypt later with the same key.",
+    "description" : "Encrypts the body of each message with a secret key, such 
as an AES key, for `crypto-decrypt-action` to decrypt later with the same 
key.\n\nUse it to protect sensitive data, such as personal or payment details, 
before it is stored or sent through a system you do not fully trust, and 
decrypt it later with `crypto-decrypt-action` and the same `algorithm` and 
`key`.\n\nInput: text or bytes.\n\nOutput: the body is the encrypted data, as 
bytes (a stream), a little longer  [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -894,8 +894,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Freemarker Template Action",
-    "summary" : "Apply a Freemarker Template.",
-    "description" : "Apply a Freemarker Template.",
+    "summary" : "Builds a new message body from a FreeMarker template, filling 
in values from the incoming message.",
+    "description" : "Builds a new message body from a FreeMarker template, 
filling in values from the incoming message.\n\nUse it to turn data into text 
for people or for another system, such as an email, a report or a small XML or 
JSON document, when you already have FreeMarker templates or need its loops and 
conditions. For simple templates, `mustache-template-action` is an alternative; 
to reshape JSON into other JSON, `jslt-action` is often simpler.\n\nInput: any 
body. The template se [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -1414,8 +1414,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Jolt Transformation Action",
-    "summary" : "Apply a Jolt Transformation.",
-    "description" : "Apply a Jolt Transformation.",
+    "summary" : "Reshapes each JSON message into other JSON, as a Jolt 
specification describes: moves, renames, removes fields or adds defaults.",
+    "description" : "Reshapes each JSON message into other JSON, as a Jolt 
specification describes: moves, renames, removes fields or adds 
defaults.\n\nUse it to map the JSON of one system to the JSON another system 
expects, for example to rename fields or move them into a nested object, when 
you already have Jolt specifications. `jslt-action` does the same with a query 
language, and is often easier to write.\n\nInput: parsed JSON, a Map (or a 
List). Since Camel 4.24, JSON text, bytes an [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -1424,8 +1424,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "JSLT Action",
-    "summary" : "Apply a JSLT query or transformation on JSON.",
-    "description" : "Apply a JSLT query or transformation on JSON.",
+    "summary" : "Turns each JSON message into new JSON with a JSLT 
transformation, a query language for JSON that picks, renames and computes 
fields.",
+    "description" : "Turns each JSON message into new JSON with a JSLT 
transformation, a query language for JSON that picks, renames and computes 
fields.\n\nUse it to map the JSON of one system to the JSON another system 
expects, for example to keep only some fields, rename them or count the items 
of an order. To build text rather than JSON, use `mustache-template-action`; 
`jolt-transformation-action` reshapes JSON with Jolt specifications 
instead.\n\nInput: JSON text, bytes or a stream. [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -1864,8 +1864,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Mvel Template Action",
-    "summary" : "Apply a Mvel Template.",
-    "description" : "Apply a Mvel Template.",
+    "summary" : "Builds a new message body from an MVEL template, filling in 
values from the incoming message.",
+    "description" : "Builds a new message body from an MVEL template, filling 
in values from the incoming message.\n\nUse it to turn data into text for 
people or for another system, such as the text of an email or a small XML or 
JSON document, when you already have MVEL templates. For simple templates, 
`mustache-template-action` is an alternative; to reshape JSON into other JSON, 
`jslt-action` is often simpler.\n\nInput: any body. The template sees the body 
as `@\\{body}` and a header as [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -1974,8 +1974,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "PDF Action",
-    "summary" : "Create a PDF.",
-    "description" : "Create a PDF.",
+    "summary" : "Turns the text of each message into a PDF document, with one 
font, font size and page size for the whole text.",
+    "description" : "Turns the text of each message into a PDF document, with 
one font, font size and page size for the whole text.\n\nUse it to produce a 
simple printable document, such as a receipt, a report or a log, that is then 
stored as a file or sent by email. To lay out the text first, put a template 
action before it, such as `mustache-template-action`.\n\nInput: the body is the 
text to write, as text. Each line of the text starts a new line in the PDF, and 
a new page starts when [...]
     "group" : "PDF",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -2424,8 +2424,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "String Template Action",
-    "summary" : "Apply a String Template.",
-    "description" : "Apply a String Template.",
+    "summary" : "Builds a new message body from a StringTemplate template, 
filling in values from the incoming message.",
+    "description" : "Builds a new message body from a StringTemplate template, 
filling in values from the incoming message.\n\nUse it to turn data into text 
for people or for another system, such as the text of an email or a small XML 
or JSON document, when you already have StringTemplate templates. For simple 
templates, `mustache-template-action` is an alternative; to reshape JSON into 
other JSON, `jslt-action` is often simpler.\n\nInput: any body. The template 
sees the body as `<body>` [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -2544,8 +2544,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Velocity Template Action",
-    "summary" : "Apply a Velocity Template.",
-    "description" : "Apply a Velocity Template.",
+    "summary" : "Builds a new message body from an Apache Velocity template, 
filling in values from the incoming message.",
+    "description" : "Builds a new message body from an Apache Velocity 
template, filling in values from the incoming message.\n\nUse it to turn data 
into text for people or for another system, such as an email, a report or a 
small XML or JSON document, when you already have Velocity templates or need 
its loops and conditions. For simple templates, `mustache-template-action` is 
an alternative; to reshape JSON into other JSON, `jslt-action` is often 
simpler.\n\nInput: any body. The templat [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -2574,8 +2574,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "XJ Identity Action",
-    "summary" : "Apply the XJ Identity Transformation to transform JSON to XML 
and XML to JSON.",
-    "description" : "Apply the XJ Identity Transformation to transform JSON to 
XML and XML to JSON.",
+    "summary" : "Converts each message from XML to JSON, or from JSON to XML, 
with a fixed mapping and no template to write.",
+    "description" : "Converts each message from XML to JSON, or from JSON to 
XML, with a fixed mapping and no template to write.\n\nUse it to pass XML to a 
system that expects JSON, or the other way round, when the default mapping is 
good enough. To control the result, such as the names of the elements or which 
fields to keep, use `xj-template-action` with an XSLT stylesheet.\n\nInput: XML 
or JSON as text, bytes or a stream, as `direction` says. Parsed JSON, such as a 
Map, fails the mess [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/crypto-decrypt-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/crypto-decrypt-action.kamelet.yaml
index 30d181a8c..d3174a96a 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/crypto-decrypt-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/crypto-decrypt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "Crypto Decrypt Action"
-    description: Decrypt the payload using the Java Cryptographic Extension 
(JCE) and a fixed key.
+    description: |-
+      Decrypts the body of each message that `crypto-encrypt-action` 
encrypted, with the same algorithm and secret key.
+
+      Use it to get back the original data that was encrypted with 
`crypto-encrypt-action`, for example after reading it from storage or receiving 
it from another system.
+
+      Input: the encrypted data exactly as `crypto-encrypt-action` produced 
it, as bytes or a stream. If it was encoded on the way, for example in Base64, 
decode it first.
+
+      Output: the body is the original data, as bytes (a stream). The headers 
are kept.
+
+      Good to know: data that was changed, or a different `algorithm` or `key` 
than when encrypting, fails the message with "Message authentication failed". 
The key is a secret; keep it in a vault or a secret, not in plain configuration.
     required:
       - algorithm
       - key
@@ -38,12 +47,12 @@ spec:
     properties:
       algorithm:
         title: Algorithm
-        description: The JCE algorithm name indicating the cryptographic 
algorithm that will be used.
+        description: "The name of the encryption algorithm the data was 
encrypted with, such as `AES`, or `DESede` for Triple DES. Give the name alone: 
a full form such as `AES/CBC/PKCS5Padding` fails each message."
         type: string
         example: "AES"
       key:
         title: Secret Key
-        description: The secret key to use to decrypt the payload. The length 
must match the requirements of the selected algorithm (for example 16, 24 or 32 
bytes for AES).
+        description: "The secret key the data was encrypted with, as text. Its 
length must fit the algorithm: for `AES`, 16, 24 or 32 characters (plain ASCII 
characters count as one byte each), and for `DESede`, 24."
         type: string
         format: password
         x-descriptors:
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/crypto-encrypt-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/crypto-encrypt-action.kamelet.yaml
index 49a785d14..756129ff3 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/crypto-encrypt-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/crypto-encrypt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "Crypto Encrypt Action"
-    description: Encrypt the payload using the Java Cryptographic Extension 
(JCE) and a fixed key.
+    description: |-
+      Encrypts the body of each message with a secret key, such as an AES key, 
for `crypto-decrypt-action` to decrypt later with the same key.
+
+      Use it to protect sensitive data, such as personal or payment details, 
before it is stored or sent through a system you do not fully trust, and 
decrypt it later with `crypto-decrypt-action` and the same `algorithm` and 
`key`.
+
+      Input: text or bytes.
+
+      Output: the body is the encrypted data, as bytes (a stream), a little 
longer than the input. It is not text: to send it where only text fits, encode 
it, for example in Base64. The headers are kept.
+
+      Good to know: the key is a secret; anyone who has it can decrypt the 
data, so keep it in a vault or a secret, not in plain configuration. The 
encrypted data carries a check value, so `crypto-decrypt-action` fails on data 
that was changed or decrypted with another key. A key of the wrong length fails 
each message, not the start.
     required:
       - algorithm
       - key
@@ -38,12 +47,12 @@ spec:
     properties:
       algorithm:
         title: Algorithm
-        description: The JCE algorithm name indicating the cryptographic 
algorithm that will be used.
+        description: "The name of the encryption algorithm, such as `AES`, or 
`DESede` for Triple DES. Give the name alone: a full form such as 
`AES/CBC/PKCS5Padding` fails each message. Use the same value in 
`crypto-decrypt-action`."
         type: string
         example: "AES"
       key:
         title: Secret Key
-        description: The secret key to use to encrypt the payload. The length 
must match the requirements of the selected algorithm (for example 16, 24 or 32 
bytes for AES).
+        description: "The secret key, as text. Its length must fit the 
algorithm: for `AES`, 16, 24 or 32 characters (plain ASCII characters count as 
one byte each), and for `DESede`, 24. Use the same key in 
`crypto-decrypt-action`."
         type: string
         format: password
         x-descriptors:
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/freemarker-template-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/freemarker-template-action.kamelet.yaml
index eec62844a..2ac812947 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/freemarker-template-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/freemarker-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "Freemarker Template Action"
-    description: Apply a Freemarker Template.
+    description: |-
+      Builds a new message body from a FreeMarker template, filling in values 
from the incoming message.
+
+      Use it to turn data into text for people or for another system, such as 
an email, a report or a small XML or JSON document, when you already have 
FreeMarker templates or need its loops and conditions. For simple templates, 
`mustache-template-action` is an alternative; to reshape JSON into other JSON, 
`jslt-action` is often simpler.
+
+      Input: any body. The template sees the body as `$\{body}` and a header 
as `${headers.name}`, for example `Dear ${headers.customer}, your order 
$\{body} has shipped.`
+
+      Output: the body is the text the template produced. The headers are kept.
+
+      Good to know: a value the template uses that is missing, such as a 
header that is not set, fails the message; give a default with 
`${headers.customer!""}`. A template file that cannot be found fails the 
message too. The template is loaded from a file, the classpath or a URL given 
by the `template` option; it cannot come from the message.
     required:
       - template
     type: object
@@ -39,7 +48,7 @@ spec:
         title: Template
         description: "Where to load the FreeMarker template from, not the 
FreeMarker template itself: `file://` followed by the path of a file, 
`classpath://` followed by a resource in the application, or an `http://` or 
`https://` URL."
         type: string
-        example: "file:////template.ftl"
+        example: "file:///opt/templates/order.ftl"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
   dependencies:
   - "camel:freemarker"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/jolt-transformation-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/jolt-transformation-action.kamelet.yaml
index d6e122884..bcf5c7f26 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/jolt-transformation-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/jolt-transformation-action.kamelet.yaml
@@ -30,20 +30,29 @@ metadata:
 spec:
   definition:
     title: "Jolt Transformation Action"
-    description: Apply a Jolt Transformation.
+    description: |-
+      Reshapes each JSON message into other JSON, as a Jolt specification 
describes: moves, renames, removes fields or adds defaults.
+
+      Use it to map the JSON of one system to the JSON another system expects, 
for example to rename fields or move them into a nested object, when you 
already have Jolt specifications. `jslt-action` does the same with a query 
language, and is often easier to write.
+
+      Input: parsed JSON, a Map (or a List). Since Camel 4.24, JSON text, 
bytes and a stream work too. With older versions they do not fail but give an 
empty body, and so does the parsed JSON of `json-deserialize-action`.
+
+      Output: the body is the result as parsed JSON, a Map (or a List), not 
JSON text. Add `json-serialize-action` after it to get JSON text. The headers 
are kept.
+
+      Good to know: the specification cannot read headers, only the body. It 
is loaded from a file, the classpath or a URL given by the `template` option; 
it cannot come from the message.
     required:
       - template
     type: object
     properties:
       template:
         title: Template
-        description: "Where to load the Jolt specification from, not the Jolt 
specification itself: `file://` followed by the path of a file, `classpath://` 
followed by a resource in the application, or an `http://` or `https://` URL."
+        description: "Where to load the Jolt specification from, not the Jolt 
specification itself: `file://` followed by the path of a file, `classpath://` 
followed by a resource in the application, or an `http://` or `https://` URL. 
With the default `transform`, the file holds a JSON array of steps, such as 
`[{\"operation\": \"shift\", \"spec\": {\"name\": \"customer.fullName\"}}]`."
         type: string
-        example: "file:////template.json"
+        example: "file:///opt/templates/order-spec.json"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
       transform:
         title: Transform DSL
-        description: Specifies the Transform DSL of the endpoint resource. If 
none is specified, Chainr is used.
+        description: "The kind of Jolt specification in the `template` file. 
`Chainr`, the default, is a list of steps, each with an `operation` (such as 
`shift`, `default` or `remove`) and a `spec`. The others take the spec of one 
operation alone: `Shiftr` moves and renames fields, `Defaultr` adds default 
values, `Removr` removes fields, and `Sortr` sorts the fields by name."
         type: string
         default: "Chainr"
         enum: ["Chainr", "Shiftr", "Defaultr", "Removr", "Sortr"]
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/jslt-action.kamelet.yaml 
b/library/camel-kamelets/src/main/resources/kamelets/jslt-action.kamelet.yaml
index 2658082b9..32c8e9b40 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/jslt-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/jslt-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "JSLT Action"
-    description: Apply a JSLT query or transformation on JSON.
+    description: |-
+      Turns each JSON message into new JSON with a JSLT transformation, a 
query language for JSON that picks, renames and computes fields.
+
+      Use it to map the JSON of one system to the JSON another system expects, 
for example to keep only some fields, rename them or count the items of an 
order. To build text rather than JSON, use `mustache-template-action`; 
`jolt-transformation-action` reshapes JSON with Jolt specifications instead.
+
+      Input: JSON text, bytes or a stream. The transformation sees the body as 
`.` and a header as `$headers.name`, for example `{"customer": .name, "items": 
size(.items), "source": $headers.origin}`.
+
+      Output: the body is the result as JSON text. The headers are kept.
+
+      Good to know: parsed JSON (a Map or a JsonNode, such as the output of 
`json-deserialize-action`) fails the message: give the JSON as text. A field 
whose value is missing, such as a header that is not set, is left out of the 
result. The transformation is loaded from a file, the classpath or a URL given 
by the `template` option; it cannot come from the message.
     required:
       - template
     type: object
@@ -39,7 +48,7 @@ spec:
         title: Template
         description: "Where to load the JSLT transformation from, not the JSLT 
transformation itself: `file://` followed by the path of a file, `classpath://` 
followed by a resource in the application, or an `http://` or `https://` URL."
         type: string
-        example: "file://template.json"
+        example: "file:///opt/templates/order.jslt"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
   dependencies:
   - "camel:jslt"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/mvel-template-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/mvel-template-action.kamelet.yaml
index 215a4bb83..bc32eb5bf 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/mvel-template-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/mvel-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "Mvel Template Action"
-    description: Apply a Mvel Template.
+    description: |-
+      Builds a new message body from an MVEL template, filling in values from 
the incoming message.
+
+      Use it to turn data into text for people or for another system, such as 
the text of an email or a small XML or JSON document, when you already have 
MVEL templates. For simple templates, `mustache-template-action` is an 
alternative; to reshape JSON into other JSON, `jslt-action` is often simpler.
+
+      Input: any body. The template sees the body as `@\{body}` and a header 
as `@{headers.name}`, for example `Dear @{headers.customer}, your order 
@\{body} has shipped.`
+
+      Output: the body is the text the template produced. The headers are kept.
+
+      Good to know: a header the template uses that is not set fails the 
message, and so does a template file that cannot be found. The template is 
loaded from a file, the classpath or a URL given by the `template` option; it 
cannot come from the message.
     required:
       - template
     type: object
@@ -39,7 +48,7 @@ spec:
         title: Template
         description: "Where to load the MVEL template from, not the MVEL 
template itself: `file://` followed by the path of a file, `classpath://` 
followed by a resource in the application, or an `http://` or `https://` URL."
         type: string
-        example: "file:////template.mvel"
+        example: "file:///opt/templates/order.mvel"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
   dependencies:
   - "camel:mvel"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/pdf-action.kamelet.yaml 
b/library/camel-kamelets/src/main/resources/kamelets/pdf-action.kamelet.yaml
index d0ddc4a5b..93d5a7593 100644
--- a/library/camel-kamelets/src/main/resources/kamelets/pdf-action.kamelet.yaml
+++ b/library/camel-kamelets/src/main/resources/kamelets/pdf-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "PDF Action"
-    description: Create a PDF.
+    description: |-
+      Turns the text of each message into a PDF document, with one font, font 
size and page size for the whole text.
+
+      Use it to produce a simple printable document, such as a receipt, a 
report or a log, that is then stored as a file or sent by email. To lay out the 
text first, put a template action before it, such as `mustache-template-action`.
+
+      Input: the body is the text to write, as text. Each line of the text 
starts a new line in the PDF, and a new page starts when a page is full.
+
+      Output: the body is the PDF document, as bytes. The headers are kept as 
they are; a `Content-Type` header set before is not changed to PDF.
+
+      Good to know: long lines are not wrapped; they run past the right edge 
of the page. Set `font` to one of the names its description lists, such as 
`HELVETICA`: the default value `Helvetica` fails each message.
     required:
       - font
       - fontSize
@@ -39,19 +48,21 @@ spec:
     properties:
       font:
         title: Font
-        description: The font to use while generating the PDF. One of Courier, 
Courier-Bold, Courier-Oblique, Courier-BoldOblique, Helvetica, Helvetica-Bold, 
Helvetica-Oblique, Helvetica-BoldOblique, Times-Roman, Times-Bold, 
Times-Italic, Times-BoldItalic, Symbol, ZapfDingbats
+        description: "The font of the whole text, one of the standard PDF 
fonts: `COURIER`, `COURIER_BOLD`, `COURIER_OBLIQUE`, `COURIER_BOLD_OBLIQUE`, 
`HELVETICA`, `HELVETICA_BOLD`, `HELVETICA_OBLIQUE`, `HELVETICA_BOLD_OBLIQUE`, 
`TIMES_ROMAN`, `TIMES_BOLD`, `TIMES_ITALIC`, `TIMES_BOLD_ITALIC`, `SYMBOL` or 
`ZAPF_DINGBATS`. Write the name in capitals with underscores: `Helvetica` or 
`Times-Roman` fails each message."
         type: string
         default: HELVETICA
+        example: "HELVETICA"
       fontSize:
         title: Font Size
-        description: The Font size to use while generating the PDF
+        description: "The size of the text, in points, such as `12` or `10.5`. 
72 points make one inch."
         type: string
         default: 14.0
       pageSize:
         title: Page Size
-        description: The Page size to use while generating the PDF. One of 
LETTER, LEGAL, A0, A1, A2, A3, A4, A5, A6
+        description: "The size of the pages: `A0` to `A6` (`A4` is 210 by 297 
millimetres), `LETTER` (8.5 by 11 inches) or `LEGAL` (8.5 by 14 inches)."
         type: string
         default: A4
+        enum: ["LETTER", "LEGAL", "A0", "A1", "A2", "A3", "A4", "A5", "A6"]
   dependencies:
   - "camel:pdf"
   - "camel:kamelet"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/string-template-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/string-template-action.kamelet.yaml
index ea14a4148..3604580ba 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/string-template-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/string-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "String Template Action"
-    description: Apply a String Template.
+    description: |-
+      Builds a new message body from a StringTemplate template, filling in 
values from the incoming message.
+
+      Use it to turn data into text for people or for another system, such as 
the text of an email or a small XML or JSON document, when you already have 
StringTemplate templates. For simple templates, `mustache-template-action` is 
an alternative; to reshape JSON into other JSON, `jslt-action` is often simpler.
+
+      Input: any body. The template sees the body as `<body>` and a header as 
`<headers.name>`, for example `Dear <headers.customer>, your order <body> has 
shipped.`
+
+      Output: the body is the text the template produced. The headers are 
kept, and a `CamelStringTemplateResourceUri` header is added with the location 
of the template.
+
+      Good to know: a header the template uses that is not set gives nothing 
in the text. A template file that cannot be found fails the message. The 
template is loaded from a file, the classpath or a URL given by the `template` 
option; it cannot come from the message.
     required:
       - template
     type: object
@@ -39,7 +48,7 @@ spec:
         title: Template
         description: "Where to load the StringTemplate template from, not the 
StringTemplate template itself: `file://` followed by the path of a file, 
`classpath://` followed by a resource in the application, or an `http://` or 
`https://` URL."
         type: string
-        example: "file:////template.tm"
+        example: "file:///opt/templates/order.st"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
   dependencies:
   - "camel:stringtemplate"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/velocity-template-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/velocity-template-action.kamelet.yaml
index 1658ebc48..7e87edd85 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/velocity-template-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/velocity-template-action.kamelet.yaml
@@ -30,7 +30,16 @@ metadata:
 spec:
   definition:
     title: "Velocity Template Action"
-    description: Apply a Velocity Template.
+    description: |-
+      Builds a new message body from an Apache Velocity template, filling in 
values from the incoming message.
+
+      Use it to turn data into text for people or for another system, such as 
an email, a report or a small XML or JSON document, when you already have 
Velocity templates or need its loops and conditions. For simple templates, 
`mustache-template-action` is an alternative; to reshape JSON into other JSON, 
`jslt-action` is often simpler.
+
+      Input: any body. The template sees the body as `$\{body}` and a header 
as `${headers.name}`, for example `Dear ${headers.customer}, your order 
$\{body} has shipped.`
+
+      Output: the body is the text the template produced. The headers are kept.
+
+      Good to know: a value the template uses that is missing, such as a 
header that is not set, stays in the text as written, for example 
`${headers.customer}`; write `$!{headers.customer}` to get nothing instead. A 
template file that cannot be found fails the message. The template is loaded 
from a file, the classpath or a URL given by the `template` option; it cannot 
come from the message.
     required:
       - template
     type: object
@@ -39,7 +48,7 @@ spec:
         title: Template
         description: "Where to load the Velocity template from, not the 
Velocity template itself: `file://` followed by the path of a file, 
`classpath://` followed by a resource in the application, or an `http://` or 
`https://` URL."
         type: string
-        example: "file:////template.vm"
+        example: "file:///opt/templates/order.vm"
         pattern: "^(http|https|file|classpath|ref|bean)://.*"
   dependencies:
   - "camel:velocity"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/xj-identity-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/xj-identity-action.kamelet.yaml
index 739cb2ba2..afd7547d6 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/xj-identity-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/xj-identity-action.kamelet.yaml
@@ -31,14 +31,21 @@ metadata:
 spec:
   definition:
     title: "XJ Identity Action"
-    description: Apply the XJ Identity Transformation to transform JSON to XML 
and XML to JSON.
+    description: |-
+      Converts each message from XML to JSON, or from JSON to XML, with a 
fixed mapping and no template to write.
+
+      Use it to pass XML to a system that expects JSON, or the other way 
round, when the default mapping is good enough. To control the result, such as 
the names of the elements or which fields to keep, use `xj-template-action` 
with an XSLT stylesheet.
+
+      Input: XML or JSON as text, bytes or a stream, as `direction` says. 
Parsed JSON, such as a Map, fails the message.
+
+      Output: the body is JSON text or XML text. From XML, the root element is 
dropped, its attributes and child elements become fields, repeated elements 
become an array, and all values are text: `<order id="7"><qty>2</qty></order>` 
gives `{"id":"7","qty":"2"}`. To XML, each JSON value becomes an `object` 
element that keeps its name and type in `xj:name` and `xj:type` attributes, 
such as `<object xj:name="qty" xj:type="int">2</object>`. The headers are kept.
     required:
       - direction
     type: object
     properties:
       direction:
         title: Direction
-        description: The transform direction.
+        description: "Which way to convert: `XML2JSON` turns XML into JSON, 
and `JSON2XML` turns JSON into XML."
         type: string
         enum: ["XML2JSON", "JSON2XML"]
   dependencies:

Reply via email to