Re: [patch] [gdbserver] Fix multi-GB error log files [doc review]

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Fri, 22 Apr 2011 23:41:45 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: pedro@codesourcery.com, gdb-patches@sourceware.org, dan@codesourcery.com
> 
> > Also, this text should have an index entry for this new option.
> 
> I do not see --debug, --remote-debug or --wrapper documented either so please
> fix those first to have a template.

I did that (with the patch shown below), but please note that we
already have GDB options indexed, so you have the template already.

> > Finally, do we want to mention this in NEWS?
> 
> Done.

Thanks.

>  *** Changes since GDB 7.3
>  
> +* GDBserver has started to keep its listening port allocated.  You can free the
> +  listening port for its reusal by the new GDBserver option --once.  In such
> +  case GDB will no longer be able to reconnect to such GDBserver.

I would rephrase:

  GDBserver now keeps its listening port open, unless you start
  GDBserver with the --once option.  Keeping the listening port open
  allows subsequent reconnections from another GDB session. 

> +                                Option @option{--multi} is not directly related
> +to @kbd{target extended-remote} (therefore @kbd{target remote} is also
> +compatible) and vice versa.

It's not clear to me how this sentence is related to the surrounding
text.  What potential problem did you try to prevent by that?

In any case, please say "the @option{--multi} option", not "option
@option{--multi}".

> +In multi-process mode @code{gdbserver} does not automatically exit unless you
> +use the option @option{--once}.  You can terminate it by using
> +@code{monitor exit} (@pxref{Monitor Commands for gdbserver}).
> +
> +@subsubsection TCP port allocation lifecycle of @code{gdbserver}
> +
> +This section applies only when @code{gdbserver} is run to listen on a TCP port.
> +
> +@code{gdbserver} normally terminates after all of its debugged processes have
> +terminated in @kbd{target remote} mode.  On the other hand for @kbd{target
                                                        ^
Missing comma there.

> +extended-remote} @code{gdbserver} stays running even with no processes left.
                   ^
And here.

> +@value{GDBN} normally terminates the spawned debugged process on its exit which
                                                                            ^
And there.

> +Thefrefore when the connection drop unexpectedly and @value{GDBN} cannot ask
   ^^^^^^^^^^
A typo.  And also comma missing after "therefore" and after
"unexpectedly".  Also, "drops", not "drop".

> +@code{gdbserver} to kill its debugged processes @code{gdbserver} stays running
                                                  ^
Missing comma.

> +When @code{gdbserver} stays running @value{GDBN} can connect to it again later.
                                      ^
And here.

> +Such reconnecting is useful for features like @ref{disconnected tracing}.  For
> +completeness at most one @value{GDBN} can be connected at a time.
               ^
And here.

> +By default @code{gdbserver} keeps the listening TCP port open so that is is
             ^                                                  ^
And there.

> +always available in the case a reconnect is needed.

"... port open, so that additional connections are possible."

>                                                       There exists also
> +a @code{gdbserver} option @option{--once} which will free the listening TCP
> +port immediately after first @value{GDBN} connects.

"However, if you start @code{gdbserver} with the @option{--once}
option, it will stop listening for any further connection attempts
after connecting to the first @value{GDBN} session."

>                                                   In such case later new
> +@value{GDBN} will no longer be able to reconnect to such @code{gdbserver}.

"This means no further connections to @code{gdbserver} will be
possible after the first one."

> +                                                The purpose of option
> +@option{--once} is to enable reusing the same port number for connections to
> +multiple @code{gdbserver}s running at the same host.

"The purpose of the @option{--once} option is ..."

However, is the above the only purpose of this option?  If not, saying
"the purpose" is inaccurate.  How about the following rewording:

  The @option{--once} option allows reusing the same port number for
  connecting to multiple instances of @code{gdbserver} running on the
  same host, since each instance closes its port after the first
  connection.

Thanks.

Here's what I committed a few minutes ago:

2011-04-23  Eli Zaretskii  <eliz@gnu.org>

	* gdb.texinfo (Server): Improve indexing.  Index all optional
	switches to gdbserver.

Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.823
retrieving revision 1.824
diff -u -r1.823 -r1.824
--- gdb/doc/gdb.texinfo	20 Apr 2011 18:05:26 -0000	1.823
+++ gdb/doc/gdb.texinfo	23 Apr 2011 05:47:43 -0000	1.824
@@ -16135,6 +16135,7 @@
 
 @subsection Running @code{gdbserver}
 @cindex arguments, to @code{gdbserver}
+@cindex @code{gdbserver}, command-line arguments
 
 Run @code{gdbserver} on the target system.  You need a copy of the
 program you want to debug, including any libraries it requires.
@@ -16181,6 +16182,8 @@
 @code{target remote} command.
 
 @subsubsection Attaching to a Running Program
+@cindex attach to a program, @code{gdbserver}
+@cindex @option{--attach}, @code{gdbserver} option
 
 On some targets, @code{gdbserver} can also attach to running programs.
 This is accomplished via the @code{--attach} argument.  The syntax is:
@@ -16193,7 +16196,6 @@
 to point @code{gdbserver} at a binary for the running process.
 
 @pindex pidof
-@cindex attach to a program by name
 You can debug processes by name instead of process ID if your target has the
 @code{pidof} utility:
 
@@ -16206,8 +16208,8 @@
 @code{-s} option to only return the first process ID.
 
 @subsubsection Multi-Process Mode for @code{gdbserver}
-@cindex gdbserver, multiple processes
-@cindex multiple processes with gdbserver
+@cindex @code{gdbserver}, multiple processes
+@cindex multiple processes with @code{gdbserver}
 
 When you connect to @code{gdbserver} using @code{target remote},
 @code{gdbserver} debugs the specified program only once.  When the
@@ -16224,6 +16226,7 @@
 arguments are supported, except for wildcard expansion and I/O
 redirection (@pxref{Arguments}).
 
+@cindex @option{--multi}, @code{gdbserver} option
 To start @code{gdbserver} without supplying an initial command to run
 or process ID to attach, use the @option{--multi} command line option.
 Then you can connect using @kbd{target extended-remote} and start
@@ -16235,12 +16238,15 @@
 
 @subsubsection Other Command-Line Arguments for @code{gdbserver}
 
+@cindex @option{--debug}, @code{gdbserver} option
 The @option{--debug} option tells @code{gdbserver} to display extra
-status information about the debugging process.  The
-@option{--remote-debug} option tells @code{gdbserver} to display
+status information about the debugging process.
+@cindex @option{--remote-debug}, @code{gdbserver} option
+The @option{--remote-debug} option tells @code{gdbserver} to display
 remote protocol debug output.  These options are intended for
 @code{gdbserver} development and for bug reports to the developers.
 
+@cindex @option{--wrapper}, @code{gdbserver} option
 The @option{--wrapper} option specifies a wrapper to launch programs
 for debugging.  The option should be followed by the name of the
 wrapper, then any command-line arguments to pass to the wrapper, then