Re: [PATCH v2 16/16] Document pseudo-terminal and interrupting changes

[Eli Zaretskii via Gdb-patches <gdb-patches@sourceware.org>]

> From: Pedro Alves <pedro@palves.net>
> Date: Mon, 14 Jun 2021 22:24:10 +0100
> 
> +Depending on the operating system and configuration, either:
> +
> +@itemize
> +
> +@item
> +@value{GDBN} switches the terminal to its own terminal modes to
> +interact with you, but it records the terminal modes your program was
> +using and switches back to them when you continue running your
> +program.  This is the default on most systems.
> +
> +@item
> +@value{GDBN} creates a pseudo-terminal, sets your program to use it
> +for standard input and standard output, and forwards input and output
> +to and from @value{GDBN}'s terminal at appropriate times.  This is the
> +default on GNU/Linux.

This doesn't read well.  I suggest to make "Either" and "Or" part of
the text, like this:

  Depending on the operating system and configuration:

  @itemize

  @item
  Either @value{GDBN} switches the terminal ...

  @item
  Or @value{GDB} creates a pseudo-terminal ...

> +@value{GDBN} creates a pseudo-terminal, sets your program to use it
> +for standard input and standard output
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This begs the question about the standard error stream.

> +On some operating systems, by default, @value{GDBN} creates a
> +pseudo-terminal, and sets your program to use it for standard input
> +and standard output.  @value{GDBN} takes care of forwarding input and
> +output to and from @value{GDBN}'s terminal at appropriate times, so
> +this is largely transparent.

The 2 different behaviors are described somewhat inconsistently: in
one place you say "most systems" vs "GNU/Linux", in another place
"some operating systems" instead of "GNU/Linux", and in yet another
place you say "on systems where GDB creates a pseudo-terminal".  Can
you describe the pseudo-terminal feature consistently as a GNU/Linux
feature?

Also, describing the feature in a single place, and just having a
cross-reference to there in other places will go a long way towards
making the description clear and complete.

> +On such systems, in some cases, like for example if you need to run
> +your program and then detach it, and you want the program to remain
> +associated with a terminal, you may prefer that @value{GDBN} starts
> +your program using the same device for standard input and output as
> +@value{GDBN} is using.

IMHO, this is a misfeature.  If the terminal from which GDB was run
remains on the system, it would be an unpleasant surprise for the user
that the program gets hit by SIGHUP when you detach.  I think we
should try to avoid this side effect, if that's feasible.

> +@node Interrupting
> +@section Interrupting

Once again, I'd prefer to talk about "stopping" instead.  Or maybe
even "getting control to GDB".

> +Depending on operating system and configuration, this results in
> +interrupting the program with either a @code{SIGINT} signal:
> +
> +@smallexample
> +Program received signal SIGINT, Interrupt.
> +@end smallexample
> +
> +@noindent
> +or plainly suspending the program:
> +
> +@smallexample
> +Program stopped.
> +@end smallexample

This seems to be inaccurate.  On MS-Windows, for example, I see
something different:

  Thread 4 received signal SIGTRAP, Trace/breakpoint trap.

So maybe you want to say that the above is only true for Posix hosts.
Or maybe just be more vague and don't try quoting the messages?

> +On systems where interrupting the program results in a plain
> +suspension instead of the program receiving a @code{SIGINT} signal,
> +you can still pass a @code{SIGINT} signal to the program after it
> +stops, using either the @code{signal SIGINT} or @code{queue-signal
> +SIGINT} commands.  @xref{Signaling,,Giving your Program a Signal}.

This begs a question I already asked elsewhere: I'd expect that
continuing the program after it was stopped like that will deliver
SIGINT to the program, without any special commands.  Isn't that so?
Your text seems to imply that it isn't, which I find surprising --
after all, the user pressed Ctrl-C, so "normally" the debuggee should
be hit with SIGINT, as if we were not debugging it.

> +@value{GDBN} on MS-Windows supports @kbd{C-@key{BREAK}} as an
> +alternative interrupt key sequence.  @xref{interrupt debuggee on
> +MS-Windows}.

I'm not sure I understand the significance of this note: after all, a
Windows program can install a Ctrl-BREAK handler exactly like it does
with Ctrl-C.  Is this only about SetConsoleMode?

Thanks.