From 27bc1217b3aa64df7607295d7f92a198ea070d20 Mon Sep 17 00:00:00 2001
From: Arijit Basu <sayanarijit@gmail.com>
Date: Mon, 22 May 2023 09:50:42 +0530
Subject: [PATCH] Document jf syntax

---
 .../en/src/environment-variables-and-pipes.md |  3 +++
 docs/en/src/message.md                        | 24 +++++++++++++++----
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/docs/en/src/environment-variables-and-pipes.md b/docs/en/src/environment-variables-and-pipes.md
index f7253a3..99feed5 100644
--- a/docs/en/src/environment-variables-and-pipes.md
+++ b/docs/en/src/environment-variables-and-pipes.md
@@ -174,6 +174,8 @@ message using newline or null character (`\n` or `\0`).
 > directly to this file, as safely escaping YAML strings is a lot of work. Use
 > `xplr -m` / `xplr --pipe-msg-in` to pass messages to xplr in a safer way.
 >
+> It uses [jf][41] syntax to safely convert an YAML template into a valid message.
+>
 > Example: `"$XPLR" -m 'ChangeDirectory: %q' "${HOME:?}"`
 
 #### XPLR_PIPE_SELECTION_OUT
@@ -225,3 +227,4 @@ List of paths, filtered and sorted as displayed in the [files table][28].
 [38]: #xplr
 [39]: #xplr_vroot
 [40]: #xplr_initial_pwd
+[41]: https://github.com/sayanarijit/jf
diff --git a/docs/en/src/message.md b/docs/en/src/message.md
index 51063e5..87b0600 100644
--- a/docs/en/src/message.md
+++ b/docs/en/src/message.md
@@ -13,22 +13,35 @@ You can send these messages to an xplr session in the following ways:
 
 ### Format
 
-To send messages using the [key bindings][2] or
-[Lua function calls][3], messages are represented in
-[Lua][5] syntax. For example:
+To send messages using the [key bindings][2] or [Lua function calls][3],
+messages are represented in [Lua][5] syntax.
+
+For example:
 
 - `"Quit"`
 - `{ FocusPath = "/path/to/file" }`
 - `{ Call = { command = "bash", args = { "-c", "read -p test" } } }`
 
 However, to send messages using the [input pipe][4], they need to be
-represented using
-[YAML][6] (or [JSON][7]) syntax. For example:
+represented using [YAML][6] (or [JSON][7]) syntax.
+
+For example:
 
 - `Quit`
 - `FocusPath: "/path/to/file"`
 - `Call: { command: bash, args: ["-c", "read -p test"] }`
 
+Use `"$XPLR" -m TEMPLATE [VALUE]...` command-line option to safely format
+`TEMPLATE` into a valid message. If uses [jf][8] to parse and render the
+template. And `$XPLR` (rather than `xplr`) makes sure that the correct version
+of the binary is being used.
+
+For example:
+
+- `"$XPLR" -m Quit`
+- `"$XPLR" -m 'FocusPath: %q' "/path/to/file"`
+- `"$XPLR" -m 'Call: { command: %q, args: [%*q] }' bash -c "read -p test"`
+
 ## Also See:
 
 - [Full List of Messages][1]
@@ -40,3 +53,4 @@ represented using
 [5]: https://www.lua.org/
 [6]: http://yaml.org/
 [7]: https://www.json.org
+[8]: https://github.com/sayanarijit/jf