From 1b8381461dde6ba096587693af04257cbcddeb3d Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Thu, 20 Oct 2022 23:03:13 +1100
Subject: [PATCH] command-parsing: You *cannot* escape the delimiters of
 balanced strings.

Originally the page said:

> No other escaping takes place in balanced strings.

...but in the course of a general readability rewrite (56287da) this was
changed to:

> Characters may be escaped in the same manner as those for quoted strings.

...which is not actually true; probably this change made it in because there
were a lot of good changes in those commits and we didn't read them all closely
enough.

Now the documentation is correct again, and I've added some examples covering
the problems people occasionally ask about (see #2760).
---
 doc/pages/command-parsing.asciidoc | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/doc/pages/command-parsing.asciidoc b/doc/pages/command-parsing.asciidoc
index 9ab82abf..f02ff0c2 100644
--- a/doc/pages/command-parsing.asciidoc
+++ b/doc/pages/command-parsing.asciidoc
@@ -50,7 +50,34 @@ of `(`, `[`, `{` and `<`), it is parsed as a balanced string whose closing
 delimiter matches that of its opening delimiter (respectively, `)`, `]`,
 `}`, and `>`).
 
-Characters may be escaped in the same manner as those for quoted strings.
+There is no way to escape the opening and closing characters, even if they
+are nested inside some other kind of string. For example, this will **not**
+work, because the `{` in the map command interferes with the delimiters for the
+hook's command block:
+
+----
+# DOES NOT WORK
+hook global WinSetOption filetype=latex %{
+    map window user b 'o\begin{'
+}
+----
+
+You can solve this by using a different outer delimiter:
+
+----
+hook global WinSetOption filetype=latex %[
+    # Note different delimiter used -----^
+    map window user b o\begin{
+]
+----
+
+...or just by including matching delimiters inside comments:
+
+----
+hook global WinSetOption filetype=latex %{
+    map window user b o\begin{ # matched pair to keep Kakoune happy: }
+}
+----
 
 === Balanced Strings Examples