[2/4] GDBServer: give more complete usage information

  On 03/21/2015 02:34 AM, Cleber Rosa wrote:
> --attach/--multi are currently only mentioned on the usage info first lines,
> the meaning of PROG is completely absent and COMM/PID text is unstructured.
> 
> The words and structure chosen may not be perfect but IMHO this is an improvement.

Thanks, indeed this is in clear need of TLC.

I don't think we should put the FOO BAR options under structured
output though.  I don't think it's usual.  Looking at a few core
utils's --help, I saw none that did that.  I think its better to just
extend the intro part to explain PROG, etc.

I went ahead and did that, along with a few more changes.  Let me
know what you think.

Thanks!

------------
From 2e305602202b753b29d4088ff722150dd7b7fccd Mon Sep 17 00:00:00 2001
From: Pedro Alves <palves@redhat.com>
Date: Sat, 21 Mar 2015 17:00:23 +0000
Subject: [PATCH] GDBServer: give more complete usage information

--attach/--multi are currently only mentioned on the usage info first
lines, the meaning of PROG is completely absent and the COMM text does
not mention 'stdio'.

A few options are missing:

 . '-/stdio' is not mentioned as COMM variant.

 . --disable-randomization / --no-disable-randomization is not mentioned.

Although the manual has a comment saying these are superceded by
QDisableRandomization, that only makes sense for "run" in
extended-remote mode.  When we start gdbserver passing it a PROG,
--disable-randomization / --no-disable-randomization do take effect.
So I think we should document these.

 . We show --debug / --remote-debug, so might as well show --disable-packet too.

GDB's --help has this "For more information, consult the GDB manual"
blurb that is missing in GDBserver's --help.

Then shuffle things around a bit into "Operating modes", "Other
options" and "Debug options" sections, similarly to GDB's --help
structure.

Before:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ ./gdbserver/gdbserver --help
Usage:  gdbserver [OPTIONS] COMM PROG [ARGS ...]
        gdbserver [OPTIONS] --attach COMM PID
        gdbserver [OPTIONS] --multi COMM

COMM may either be a tty device (for serial debugging), or
HOST:PORT to listen for a TCP connection.

Options:
  --debug               Enable general debugging output.
  --debug-format=opt1[,opt2,...]
                        Specify extra content in debugging output.
                          Options:
                            all
                            none
                            timestamp
  --remote-debug        Enable remote protocol debugging output.
  --version             Display version information and exit.
  --wrapper WRAPPER --  Run WRAPPER to start new programs.
  --once                Exit after the first connection has closed.
Report bugs to "<http://www.gnu.org/software/gdb/bugs/>".
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ ./gdbserver/gdbserver --help
Usage:  gdbserver [OPTIONS] COMM PROG [ARGS ...]
        gdbserver [OPTIONS] --attach COMM PID
        gdbserver [OPTIONS] --multi COMM

COMM may either be a tty device (for serial debugging),
HOST:PORT to listen for a TCP connection, or '-' or 'stdio' to use
stdin/stdout of gdbserver.
PROG is the executable program.  ARGS are arguments passed to inferior.
PID is the process ID to attach to, when --attach is specified.

Operating modes:

  --attach              Attach to running process PID.
  --multi               Start server without a specific program, and
                        only quit when explicitly commanded.
  --once                Exit after the first connection has closed.
  --help                Print this message and then exit.
  --version             Display version information and exit.

Other options:

  --wrapper WRAPPER --  Run WRAPPER to start new programs.
  --disable-randomization
                        Run PROG with address space randomization disabled.
  --no-disable-randomization
                        Don't disable address space randomization when
                        starting PROG.

Debug options:

  --debug               Enable general debugging output.
  --debug-format=opt1[,opt2,...]
                        Specify extra content in debugging output.
                          Options:
                            all
                            none
                            timestamp
  --remote-debug        Enable remote protocol debugging output.
  --disable-packet=opt1[,opt2,...]
                        Disable support for RSP packets or features.
                          Options:
                            vCont, Tthread, qC, qfThreadInfo and
                            threads (disable all threading packets).

For more information, consult the GDB manual (available as on-line
info or a printed manual).
Report bugs to "<http://www.gnu.org/software/gdb/bugs/>".
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

gdb/gdbserver/ChangeLog:
2015-03-20  Pedro Alves  <palves@redhat.com>
	    Cleber Rosa  <crosa@redhat.com>

	* server.c (gdbserver_usage): Reorganize and extend the usage
	message.
---
 gdb/gdbserver/server.c | 40 +++++++++++++++++++++++++++++++++-------
 1 file changed, 33 insertions(+), 7 deletions(-)
  

On 03/21/2015 02:05 PM, Pedro Alves wrote:
> I went ahead and did that, along with a few more changes.  Let me
> know what you think.

Pedro,

This is so much better than my (knowingly limited) improvements! Please 
go ahead with your version, and I'll happily drop that patch from my series.

Thanks!
Cleber Rosa.
  

On 03/24/2015 11:15 AM, Cleber Rosa wrote:
> On 03/21/2015 02:05 PM, Pedro Alves wrote:
>> I went ahead and did that, along with a few more changes.  Let me
>> know what you think.
>
> Pedro,
>
> This is so much better than my (knowingly limited) improvements! 
> Please go ahead with your version, and I'll happily drop that patch 
> from my series.
>
> Thanks!
> Cleber Rosa.

Hi Pedro,

Just as a reminder: I believe this one (your version) can be pushed 
without any side effects.

Thanks,
CR.
  

On 03/24/2015 02:15 PM, Cleber Rosa wrote:
> On 03/21/2015 02:05 PM, Pedro Alves wrote:
>> I went ahead and did that, along with a few more changes.  Let me
>> know what you think.
> 
> Pedro,
> 
> This is so much better than my (knowingly limited) improvements! Please 
> go ahead with your version, and I'll happily drop that patch from my series.

Now pushed.

Thanks,
Pedro Alves