Re: regroup --help text in --help)

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 12 Apr 2013 15:39:14 +0100
> From: Pedro Alves <palves@redhat.com>
> CC: tromey@redhat.com, dje@google.com, brobecker@adacore.com,
>         gdb-patches@sourceware.org
> 
> On 04/12/2013 11:01 AM, Eli Zaretskii wrote:
> >> Date: Fri, 12 Apr 2013 11:58:48 +0300
> >> From: Eli Zaretskii <eliz@gnu.org>
> >> Cc: palves@redhat.com, dje@google.com, brobecker@adacore.com, gdb-patches@sourceware.org
> >>
> >> I will take a shot on regrouping the --help text later.
> > 
> > Howe about the following (if accepted, I will write a patch to
> > implement this):
> 
> This is great.  Many thanks.
> 
> > 
> >   This is the GNU debugger.  Usage:
> > 
> >       gdb [options] [executable-file [core-file or process-id]]
> >       gdb [options] --args executable-file [inferior-arguments ...]
> > 
> >   Selection of debuggee and its files:
> > 
> >     --args             Arguments after executable-file are passed to inferior.
> >     --core=COREFILE    Analyze the core dump COREFILE.
> >     --exec=EXECFILE    Use EXECFILE as the executable.
> >     --pid=PID          Attach to running process PID.
> >     --directory=DIR    Search for source files in DIR.
> >     --se=FILE          Use FILE as symbol file and executable file.
> >     --symbols=SYMFILE  Read symbols from SYMFILE.
> >     --readnow          Fully read symbol files on first access.
> >     --write            Set writing into executable and core files.
> > 
> >   Initial commands and command files:
> > 
> >     --command=FILE, -x Execute GDB commands from FILE.
> >     --init-command=FILE, -ix 
> >                        Like -x but execute commands before loading inferior.
> >     --eval-command=COMMAND, -ex
> > 		       Execute a single GDB command.
> > 		       May be used multiple times and in conjunction
> > 		       with --command.
> >     --init-eval-command=COMMAND, -iex 
> >                        Like -ex but before loading inferior.
> >     --nh               Do not read ~/.gdbinit.
> >     --nx               Do not read any .gdbinit files in any directory.
> > 
> >   Output and user interface control:
> > 
> >     --epoch            Output information used by epoch emacs-GDB interface.
> >     --fullname         Output information used by emacs-GDB interface.
> >     --interpreter=INTERP
> > 		       Select a specific interpreter / user interface
> >     --tty=TTY          Use TTY for input/output by the program being debugged.
> >     -w                 Use the GUI interface.
> >     --nw               Do not use the GUI interface.
> >     --tui              Use the text-mode user interface
> >     --dbx              DBX compatibility mode.
> >     --xdb              XDB compatibility mode.
> >     --quiet            Do not print version number on startup.
> > 
> >   Miscellaneous options:
> > 
> >     -b BAUDRATE        Set serial port baud rate used for remote debugging.
> >     --batch            Exit after processing options.
> >     --batch-silent     Like --batch, but suppress all gdb stdout output.
> >     --return-child-result
> > 		       GDB exit code will be the child's exit code.
> >     --cd=DIR           Change current directory to DIR.
> >     -l TIMEOUT         Set timeout in seconds for remote debugging.
> > 
> >     --configuration    Print details about GDB configuration and then exit.
> >     --help             Print this message and then exit.
> >     --version          Print version information and then exit.
> > 
> 
> I'd suggest splitting the miscellaneous section as:
> 
>    Operating modes:
> 
>      --batch            Exit after processing options.
>      --batch-silent     Like --batch, but suppress all gdb stdout output.
>      --return-child-result
>  		       GDB exit code will be the child's exit code.
> 
>      --configuration    Print details about GDB configuration and then exit.
>      --help             Print this message and then exit.
>      --version          Print version information and then exit.
> 
>    Remote debugging options:
> 
>      -b BAUDRATE        Set serial port baud rate used for remote debugging.
>      -l TIMEOUT         Set timeout in seconds for remote debugging.
> 
>    Other options:
> 
>      --cd=DIR           Change current directory to DIR.

Long time ago, but not forgotten.  The final patch appears below.  I
will commit it in a few days, if no one objects.

2013-06-22  Eli Zaretskii  <eliz@gnu.org>

	* main.c (print_gdb_help): Regroup options in the --help text.
	See http://sourceware.org/ml/gdb-patches/2013-04/msg00362.html for
	the relevant discussions.

Index: gdb/main.c
===================================================================
RCS file: /cvs/src/src/gdb/main.c,v
retrieving revision 1.125
diff -u -p -r1.125 main.c
--- gdb/main.c	22 Apr 2013 16:46:15 -0000	1.125
+++ gdb/main.c	22 Jun 2013 11:22:40 -0000
@@ -1081,59 +1081,48 @@ print_gdb_help (struct ui_file *stream)
 
   get_init_files (&system_gdbinit, &home_gdbinit, &local_gdbinit);
 
+  /* Note: The options in the list below are only approximately sorted
+     in the alphabetical order, so as to group closely related options
+     together.  */
   fputs_unfiltered (_("\
 This is the GNU debugger.  Usage:\n\n\
     gdb [options] [executable-file [core-file or process-id]]\n\
     gdb [options] --args executable-file [inferior-arguments ...]\n\n\
-Options:\n\n\
 "), stream);
   fputs_unfiltered (_("\
+Selection of debuggee and its files:\n\n\
   --args             Arguments after executable-file are passed to inferior\n\
+  --core=COREFILE    Analyze the core dump COREFILE.\n\
+  --exec=EXECFILE    Use EXECFILE as the executable.\n\
+  --pid=PID          Attach to running process PID.\n\
+  --directory=DIR    Search for source files in DIR.\n\
+  --se=FILE          Use FILE as symbol file and executable file.\n\
+  --symbols=SYMFILE  Read symbols from SYMFILE.\n\
+  --readnow          Fully read symbol files on first access.\n\
+  --write            Set writing into executable and core files.\n\n\
 "), stream);
   fputs_unfiltered (_("\
-  -b BAUDRATE        Set serial port baud rate used for remote debugging.\n\
-  --batch            Exit after processing options.\n\
-  --batch-silent     As for --batch, but suppress all gdb stdout output.\n\
-  --return-child-result\n\
-                     GDB exit code will be the child's exit code.\n\
-  --cd=DIR           Change current directory to DIR.\n\
+Initial commands and command files:\n\n\
   --command=FILE, -x Execute GDB commands from FILE.\n\
+  --init-command=FILE, -ix\n\
+                     Like -x but execute commands before loading inferior.\n\
   --eval-command=COMMAND, -ex\n\
                      Execute a single GDB command.\n\
                      May be used multiple times and in conjunction\n\
                      with --command.\n\
-  --init-command=FILE, -ix Like -x but execute it before loading inferior.\n\
-  --init-eval-command=COMMAND, -iex Like -ex but before loading inferior.\n\
-  --core=COREFILE    Analyze the core dump COREFILE.\n\
-  --pid=PID          Attach to running process PID.\n\
+  --init-eval-command=COMMAND, -iex\n\
+                     Like -ex but before loading inferior.\n\
+  --nh               Do not read ~/.gdbinit.\n\
+  --nx               Do not read any .gdbinit files in any directory.\n\n\
 "), stream);
   fputs_unfiltered (_("\
-  --dbx              DBX compatibility mode.\n\
-  --directory=DIR    Search for source files in DIR.\n\
-  --exec=EXECFILE    Use EXECFILE as the executable.\n\
+Output and user interface control:\n\n\
   --fullname         Output information used by emacs-GDB interface.\n\
-  --help             Print this message.\n\
-"), stream);
-  fputs_unfiltered (_("\
   --interpreter=INTERP\n\
                      Select a specific interpreter / user interface\n\
-"), stream);
-  fputs_unfiltered (_("\
-  -l TIMEOUT         Set timeout in seconds for remote debugging.\n\
-  --nw		     Do not use a window interface.\n\
-  --nx               Do not read any "), stream);
-  fputs_unfiltered (gdbinit, stream);
-  fputs_unfiltered (_(" files.\n\
-  --nh               Do not read "), stream);
-  fputs_unfiltered (gdbinit, stream);
-  fputs_unfiltered (_(" file from home directory.\n\
-  --quiet            Do not print version number on startup.\n\
-  --readnow          Fully read symbol files on first access.\n\
-"), stream);
-  fputs_unfiltered (_("\
-  --se=FILE          Use FILE as symbol file and executable file.\n\
-  --symbols=SYMFILE  Read symbols from SYMFILE.\n\
   --tty=TTY          Use TTY for input/output by the program being debugged.\n\
+  -w                 Use the GUI interface.\n\
+  --nw               Do not use the GUI interface.\n\
 "), stream);
 #if defined(TUI)
   fputs_unfiltered (_("\
@@ -1141,11 +1130,24 @@ Options:\n\n\
 "), stream);
 #endif
   fputs_unfiltered (_("\
-  --version          Print version information and then exit.\n\
-  --configuration    Print details about GDB configuration and then exit.\n\
-  -w                 Use a window interface.\n\
-  --write            Set writing into executable and core files.\n\
+  --dbx              DBX compatibility mode.\n\
   --xdb              XDB compatibility mode.\n\
+  --quiet            Do not print version number on startup.\n\n\
+"), stream);
+  fputs_unfiltered (_("\
+Operating modes:\n\n\
+  --batch            Exit after processing options.\n\
+  --batch-silent     Like --batch, but suppress all gdb stdout output.\n\
+  --return-child-result\n\
+                     GDB exit code will be the child's exit code.\n\
+  --configuration    Print details about GDB configuration and then exit.\n\
+  --help             Print this message and then exit.\n\
+  --version          Print version information and then exit.\n\n\
+Remote debugging options:\n\n\
+  -b BAUDRATE        Set serial port baud rate used for remote debugging.\n\
+  -l TIMEOUT         Set timeout in seconds for remote debugging.\n\n\
+Other options:\n\n\
+  --cd=DIR           Change current directory to DIR.\n\
 "), stream);
   fputs_unfiltered (_("\n\
 At startup, GDB reads the following init files and executes their commands:\n\