Re: [PATCH v3 30/34] [DOC] Document support for running interpreters on separate UI channels

[Pedro Alves <palves@redhat.com>]

On 05/06/2016 02:04 PM, Eli Zaretskii wrote:
>> From: Pedro Alves <palves@redhat.com>
>> Date: Fri,  6 May 2016 13:35:00 +0100
>>
>> +Although you may only choose a single interpreter at startup, it is
>> +possible to run an independent interpreter on a separate channel.
> 
> "Channel"?  What's that?  Can we find a better word?
> 
> No other comments to the doc part.  Thanks.

Thanks Eli.  Here's an attempt at clarifying things, using
the same terminology already used in other related commands.

From b58b402641e5cb5d0cbdf3bc2a815ada244be4c5 Mon Sep 17 00:00:00 2001
From: Pedro Alves <palves@redhat.com>
Date: Thu, 5 May 2016 13:06:03 +0100
Subject: [PATCH 30/34] [DOC] Document support for running interpreters on
 separate UIs

gdb/ChangeLog:
yyyy-mm-dd  Pedro Alves  <palves@redhat.com>

	* NEWS: Mention support for running interpreters on separate
	UIs and the new new-ui command.

gdb/doc/ChangeLog:
yyyy-mm-dd  Pedro Alves  <palves@redhat.com>

	* gdb.texinfo (Interpreters): Update intepreter-exec section,
	document new-ui and explain use case.
---
 gdb/doc/gdb.texinfo | 56 +++++++++++++++++++++++++++++++++++++++++++----------
 gdb/NEWS            | 18 +++++++++++++++++
 2 files changed, 64 insertions(+), 10 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f74c41c..a302d6e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -24805,18 +24805,11 @@ The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
 @end table
 
 @cindex invoke another interpreter
-The interpreter being used by @value{GDBN} may not be dynamically
-switched at runtime.  Although possible, this could lead to a very
-precarious situation.  Consider an IDE using @sc{gdb/mi}.  If a user
-enters the command "interpreter-set console" in a console view,
-@value{GDBN} would switch to using the console interpreter, rendering
-the IDE inoperable!
 
 @kindex interpreter-exec
-Although you may only choose a single interpreter at startup, you may execute
-commands in any interpreter from the current interpreter using the appropriate
-command.  If you are running the console interpreter, simply use the
-@code{interpreter-exec} command:
+You may execute commands in any interpreter from the current
+interpreter using the appropriate command.  If you are running the
+console interpreter, simply use the @code{interpreter-exec} command:
 
 @smallexample
 interpreter-exec mi "-data-list-register-names"
@@ -24825,6 +24818,49 @@ interpreter-exec mi "-data-list-register-names"
 @sc{gdb/mi} has a similar command, although it is only available in versions of
 @value{GDBN} which support @sc{gdb/mi} version 2 (or greater).
 
+Note that @code{interpreter-exec} only changes the interpreter for the
+duration of the specified command.  It does not change the interpreter
+permanently.
+
+@cindex start a new independent interpreter
+
+Although you may only choose a single interpreter at startup, it is
+possible to run an independent interpreter on a specified input/output
+device (usually a tty).
+
+For example, consider a debugger GUI or IDE that wants to provide a
+@value{GDBN} console view.  It may do so by embedding a terminal
+emulator widget in its GUI, starting @value{GDBN} in the traditional
+command-line mode with stdin/stdout/stderr redirected to that
+terminal, and then creating an MI interpreter running on a specified
+input/output device.  The console interpreter created by @value{GDBN}
+at startup handles commands the user types in the terminal widget,
+while the GUI controls and synchronizes state with @value{GDBN} using
+the separate MI interpreter.
+
+To start a new secondary @dfn{user interface} running MI, use the
+@code{new-ui} command:
+
+@kindex new-ui
+@cindex new user interface
+@smallexample
+new-ui @var{interpreter} @var{tty}
+@end smallexample
+
+The @var{interpreter} parameter specifies the interpreter to run.
+This accepts the same values as the @code{interpreter-exec} command.
+For example, @samp{console}, @samp{mi}, @samp{mi2}, etc.  The
+@var{tty} parameter specifies the name of the bidirectional file the
+interpreter uses for input/output, usually the name of a
+pseudoterminal slave on Unix systems.  For example:
+
+@smallexample
+(@value{GDBP}) new-ui mi /dev/pts/9
+@end smallexample
+
+@noindent
+runs an MI interpreter on @file{/dev/pts/9}.
+
 @node TUI
 @chapter @value{GDBN} Text User Interface
 @cindex TUI
diff --git a/gdb/NEWS b/gdb/NEWS
index 7bf1e1a..c6ed63d 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -27,6 +27,20 @@
    Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3]
    0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68
 
+* Support for running interpreters on specified input/output devices
+
+  GDB now supports a new mechanism that allows frontends to provide
+  fully featured GDB console views, as a better alternative to
+  building such views on top of the "-interpreter-exec console"
+  command.  See the new "new-ui" command below.  With that command,
+  frontends can now start GDB in the traditional command-line mode
+  running in an embedded terminal emulator widget, and create a
+  separate MI interpreter running on a specified i/o device.  In this
+  way, GDB handles line editing, history, tab completion, etc. in the
+  console all by itself, and the GUI uses the separate MI interpreter
+  for its own control and synchronization, invisible to the command
+  line.
+
 * New commands
 
 skip -file file
@@ -40,6 +54,10 @@ skip -rfunction regular-expression
 maint info line-table REGEXP
   Display the contents of GDB's internal line table data struture.
 
+new-ui INTERP TTY
+  Start a new user interface instance running INTERP as interpreter,
+  using the TTY file for input/output.
+
 * Support for tracepoints and fast tracepoints on s390-linux and s390x-linux
   was added in GDBserver, including JIT compiling fast tracepoint's
   conditional expression bytecode into native code.
-- 
2.5.5