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

Eli Zaretskii
2013-06-22T11:23:28Z

> 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\