From 0967dc8bfe7d518fc5affa59be4d175cd8c4d103 Mon Sep 17 00:00:00 2001
From: Kirk Rodrigues <2454684+kirkrodrigues@users.noreply.github.com>
Date: Mon, 2 Dec 2024 14:06:46 -0500
Subject: [PATCH] Simplify to clarify.

---
 .../reference-json-search-syntax.md           | 45 ++++++++++++++-----
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/docs/src/user-guide/reference-json-search-syntax.md b/docs/src/user-guide/reference-json-search-syntax.md
index a9f942cb9..18d0e4267 100644
--- a/docs/src/user-guide/reference-json-search-syntax.md
+++ b/docs/src/user-guide/reference-json-search-syntax.md
@@ -33,24 +33,18 @@ To search for a key or value with multiple words, you must quote the key/value w
 "multi-word key": "multi-word value"
 ```
 
-Keys or values with the following literal characters must escape the characters using a `\`
- (backslash): `\`, `"`.
-
-Unquoted keys or values must also escape the following characters: `(`, `)`, `:`, `<`, `>`, `{`,
- `}`.
-
-Values containing `?` and `*` can escape these characters with a `\` to differentiate them from the
- `?` and `*` characters used to specify arbitrary single character match and wildcard match.
-
-Keys containing `.` can escape the `.` with `\` to differentiate from the special `.` character that
-indicates nested keys.
-
 :::{caution}
 Currently, a query that contains spaces is interpreted as a substring search, i.e., it will match
 log events that contain the value as a *substring*. In a future version of CLP, these queries will
 be interpreted as _exact_ searches unless they include [wildcards](#wildcards-in-values).
 :::
 
+:::{note}
+Certain characters have special meanings when used in keys or values, so to search for the
+characters literally, you must escape them. For a list of such characters, see
+[Escaping special characters](#escaping-special-characters).
+:::
+
 ### Querying nested kv-pairs
 
 If the kv-pair is nested in one or more objects, you can specify the key in one of two ways:
@@ -170,6 +164,33 @@ There are three supported boolean operators:
 
 You can use parentheses (`()`) to apply an operator to a group of expressions.
 
+### Escaping special characters
+
+Keys containing the following literal characters must escape the characters using a `\` (backslash):
+
+* `\`
+* `"`
+* `.`
+
+Values containing the following literal characters must escape the characters using a `\`
+(backslash):
+
+* `\`
+* `"`
+* `?`
+* `*`
+
+_Unquoted_ keys or values containing the following literal characters must also escape the
+characters using a `\` (backslash):
+
+* `(`
+* `)`
+* `:`
+* `<`
+* `>`
+* `{`
+* `}`
+
 ## Examples
 
 **Search for log events that contain a specific key-value pair:**