From 18c34408c52ec50fcc20cb49f938990e32a69951 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Tue, 11 Dec 2018 14:18:05 +1100
Subject: [PATCH] doc: Mention that commands requiring a client context are
 unhelpful in a draft context.

Fixes #2618.
---
 doc/pages/commands.asciidoc | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc
index e182696e2..b20892738 100644
--- a/doc/pages/commands.asciidoc
+++ b/doc/pages/commands.asciidoc
@@ -284,11 +284,20 @@ but not really useful in that context.
     prompt content will be passed as a single token. In other words,
     word splitting does not take place.
 
+    NOTE: The prompt is displayed in and receives input from the
+    current client context, so inside a draft context like
+    `evaluate-commands -draft`, it is invisible and only responds to
+    an `execute-keys` command in the same context.
+
 *on-key* <command>::
     wait for next key from user, then execute <command>, the key is
     available through the `key` value, accessible through `$kak_key`
     in shells, or `%val{key}` in commands.
 
+    NOTE: The key press must come from the current client context,
+    so inside a draft context like `evaluate-commands -draft`, it only
+    responds to an `execute-keys` command in the same context.
+
 *menu* [<switches>] <label1> <commands1> <label2> <commands2> ...::
     display a menu using labels, the selected label’s commands are
     executed. The *menu* command can take an *-auto-single* argument, to automatically
@@ -297,6 +306,11 @@ but not really useful in that context.
     last one being a command to execute when the item is selected (but
     not validated)
 
+    NOTE: The menu is displayed in and receives input from the
+    current client context, so inside a draft context like
+    `evaluate-commands -draft`, it is invisible and only responds to
+    an `execute-keys` command in the same context.
+
 *info* [<switches>] <text>::
     display text in an information box with the following *switches*:
 
@@ -329,6 +343,9 @@ but not really useful in that context.
         parse markup in both title (if provided) and text. (See
         <<faces#markup-strings,`:doc faces markup-strings`>>)
 
+    NOTE: The info box is displayed in the current client context,
+    so inside a draft context like `eval -draft`, it is invisible.
+
 *try* <commands> [catch <on_error_commands>]...::
     prevent an error in *commands* from aborting the whole command
     execution, execute *on_error_commands* instead. If nothing is to be