doc: Massage section on "Escape codes" (#912)

* Add introductory text to the tables

And mention characters that don't have escapes

* Turn tables around

Tables should be structured by what the user wants, not by what the code does.

* Address Julow review #1

- Merge tables, no matter which rule requires escaping; "in the usual way for XML" applies to both
- 3 escapes not mandatory removed from table to new ¶ below
- Found one more symbol → legend

* doc: Clarify escaping of comma and colon per #915

1 files changed, 18 insertions, 19 deletions

diff --git a/doc/Possible-key-values.md b/doc/Possible-key-values.md
index 0898341..98345dc 100644
--- a/doc/Possible-key-values.md
+++ b/doc/Possible-key-values.md
@@ -25,31 +25,30 @@ Key values can be any of the following:
   + `⏯:keyevent:85` A play/pause key (which has no effect in most apps).
   + `my@:'my.email@domain.com'` A key that sends an arbitrary string
 
-- A macro, `symbol:key_def1,key_def2,...`.
-  This results in a key that behaves as if the sequence of `key_def` had been pressed in order.
+- A macro, `legend:key_def1,key_def2,...`.
+  This results in a key with legend `legend` that behaves as if the sequence of `key_def` had been pressed in order.
 
   Examples:
   + `CA:ctrl,a,ctrl,c` A key with legend CA that sends the sequence `ctrl+a`, `ctrl+c`.
   + `Cd:ctrl,backspace` A key with legend Cd that sends the shortcut `ctrl+backspace`.
 
-## Escape codes
-Value | Escape code for
+### Escape codes
+
+When defining a key value, several characters have special effects. If you want a character not to have its usual effect but to be taken literally, you should "escape" it in the usual way for XML:
+
+To get this character... | ...you can type
 :---- | :------
-`\?`  | `?`
-`\#`  | `#`
-`\@`  | `@`
-`\n`  | Literal newline character. This is different from `enter` and `action` in certain apps.
-`\t`  | Literal tab character. This is different from `tab` in certain apps.
-`\\`  | `\`
-
-XML escape codes also work, including:
-
-Value    | Escape code for
-:------- | :------
-`&`  | `&`
-`&lt;`   | `<`
-`&gt;`   | `>`
-`&quot;` | `"`
+A literal newline character, which is different from `enter` and `action` in certain apps. | `\n`
+A literal tab character, which is different from `tab` in certain apps. | `\t`
+`\` | `\\`
+`&` | `&amp;`
+`<` | `&lt;`
+`>` | `&gt;`
+`"` | `&quot;`
+
+The characters `?`, `#`, and `@` do not need to be escaped when writing custom layouts. Internally, they can be escaped by prepending backslash (by typing `\?`, `\#`, and `\@`).
+
+The characters `,` and `:` can be escaped in a key value, using single quotes. For example, this macro defines a key with legend `http` that sends a string containing `:`: `<key c="http:home,'https://'" />` For simplicity, `,` and `:` cannot be escaped in the key legend.
 
 ## Modifiers
 System modifiers are sent to the app, which can take app-specific action.