[gdb/cli] Document \001 and \002 usage for set prompt

PR cli/28887 reports the following problem when using a custom prompt.

First, we set up the custom prompt (with ^ marking the position of the
blinking cursor on the line above):
...
$ gdb -q -ex "set prompt \033[31mgdb$ \033[0m"
gdb$
     ^
...

Then we type some string, and enter it into the command history:
...
gdb$ some long command
❌️ Undefined command: "some".  Try "help".
gdb$
     ^
...

We use C-p to fetch the previous command:
...
gdb$ some long command
                      ^
...
Sofar, so good.

Finally, we use C-a which should move the cursor to just after the prompt, but
instead we get:
...
gdb$ some long command
              ^
...

This is fixed by using \001 and \002:
...
(gdb) set prompt \001\033[31m\002gdb$ \001\033[0m\002
...
aka as RL_PROMPT_START_IGNORE and RL_PROMPT_END_IGNORE [1].

Add an example to the documentation showing the use of these markers.

The added example is the equivalent of the "\[\e[0;34m\](gdb)\[\e[0m\]"
example documented at gdb.prompt.substitute_string that can be used with
"set extended-prompt".

While working on this, I noticed that "show prompt" doesn't show back the
original string, using '\e' instead of '\033':
...
gdb$ show prompt
Gdb's prompt is "\001\e[31m\002gdb$ \001\e[0m\002".
...
and that the shown string can't be used as an argument to "set prompt":
...
gdb$ set prompt \001\e[31m\002gdb$ \001\e[0m\002
e[31mgdb$ e[0m
...

I've filed this as PR cli/33184.

Approved-By: Eli Zaretskii <eliz@gnu.org>
[1] https://tiswww.case.edu/php/chet/readline/readline.html

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 35b770f8138ae1bdb781fb5e815722df6790a5ef..2bbaf14c58473126fb1156173040fd9907289536 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -27659,6 +27659,16 @@ or a prompt that does not.
 @item set prompt @var{newprompt}
 Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
 
+For example, this will set a blue-colored ``(gdb)'' prompt:
+
+@smallexample
+set prompt \001\033[0;34m\002(gdb)\001\033[0m\002
+@end smallexample
+
+It uses @samp{\001} and @samp{\002} to begin and end a sequence of
+non-printing characters, to make sure they're not counted in the string
+length.
+
 @kindex show prompt
 @item show prompt
 Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}