[RFC] Fix/complete option list/description in manual and in gdb --help.

[RFC] Fix/complete option list/description in manual and in gdb --help.

[Philippe Waroquiers]

The GDB option list given in gdb --help was incomplete.
This fixes it.  A few fixes are also done in the user manual.

Open questions:
* is it worth describing in gdb --help that --enable-external-editor
  is a 'noop' kept for backward compatibility ?
  Or should that just not mentionned in --help ?
* should --annotate gdb --help output indicate its deprecation and that
  new front ends should use GDB/MI (--interpret=mi) ?
* For an option such as "--eval-command=COMMAND, -ex", GDB accepts all of:
      --eval-command=quit
      -eval-command=quit
      --eval-command quit
      -eval-command quit
      --ex=quit
      -ex=quit
      --ex quit
      -ex quit
  The gdb --help output uses quite systematically --XXXXX
  for the "long option" XXXXX and -Y for the "short option" -y.
  But the user manual has a mix of notations.  For many options,
  it uses -XXXXX.  For some options, it uses --XXXXX.  For some, it uses
  both.  For some, it uses -XXXXX in the text but --XXXXX for the index.

  The manual indicates that many options have a long and short option,
  and that options can be flagged with -- but that the manual illustrates
  the 'more usual convention using a single -'.
  (this is strangely documented in the 'Choosing Files' subsection,
  while it should better be in the level above in 'Invoking GDB').

  However, the --help assumes that the usual convention is -- for long options.
  I am more used to the --long-option convention.
  => should the user manual be changed to consistently document and use
  --long-option ? (and just mention the alternative accepted conventions?)

Changes in main.c are:
* the -w option was since 2003 commented as 'not sure actually useful'.
  As -nw is disabling tui, and -w was activating an optional TK based
  GUI, I changed the behaviour of -w to activate the TUI interface if
  configured.  In case both TK and TUI are configured, -w starts
  the TUI interface.
  So, now, -w is actually useful :).

* For some options, the addition of the short option letter needs more room.
  So, the option description indentation is increased by 3 spaces,
  still keeping the help output <= 80 characters.

* addition of short options for various long options
  (--core, --exec, --pid; --symbols, --readnow, --fullname,
   --interpreter, --cd)

* Addition of the long option for -w, --nw, -b.

* addition of the short and long options
   --early--init-command=FILE, -eix
   --early-init-eval-command=COMMAND, -eiex
   --annotate=LEVEL

* Slightly reworded to --tui text to use the terminology GUI also used
  by -w and --nw.

* addition of GDBTK options (--tclcommand, --enable-external-editor,
  --editor-command).

Changes in the user manual are:
* Remove the -t TTY description.  This short letter option is not defined
  (and is already currently ambiguous between -tty and -tui).
* Added various synonyms
  --cd=DIRECTORY = -cd DIRECTORY
  --ui=INTERPRET and -i INTERPRET = --interpreter=INTERPRET
* Added description of --dbx
---
 gdb/doc/gdb.texinfo |  13 +++++-
 gdb/main.c          | 102 ++++++++++++++++++++++++++------------------
 2 files changed, 72 insertions(+), 43 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d09b86cda95..dd6b2e811c3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1193,6 +1193,7 @@ If @value{GDBN} includes a GUI, then this option requires it to be
 used if possible.
 
 @item -cd @var{directory}
+@itemx --cd=@var{directory}
 @cindex @code{--cd}
 Run @value{GDBN} using @var{directory} as its working directory,
 instead of the current directory.
@@ -1252,9 +1253,7 @@ Set the timeout (in seconds) of any communication used by @value{GDBN}
 for remote debugging.
 
 @item -tty @var{device}
-@itemx -t @var{device}
 @cindex @code{--tty}
-@cindex @code{-t}
 Run using @var{device} for your program's standard input and output.
 @c FIXME: kingdon thinks there is more to -tty.  Investigate.
 
@@ -1269,7 +1268,11 @@ option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
 Using @value{GDBN} under @sc{gnu} Emacs}).
 
 @item -interpreter @var{interp}
+@itemx --ui=@var{interp}
+@itemx -i @var{interp}
 @cindex @code{--interpreter}
+@cindex @code{--ui}
+@cindex @code{-i}
 Use the interpreter @var{interp} for interface with the controlling
 program or device.  This option is meant to be set by programs which
 communicate with @value{GDBN} using it as a back end.
@@ -1282,6 +1285,12 @@ version 2 (@code{mi2}), included in @value{GDBN} 6.0 and version 1 (@code{mi1}),
 included in @value{GDBN} 5.3, are also available.  Earlier @sc{gdb/mi}
 interfaces are no longer supported.
 
+@item --dbx
+@cindex @code{--dbx}
+@samp{--dbx} causes @value{GDBN} to define various additional commands
+(such as @samp{assign}, @samp{use}, ...) providing some compatibility
+with the @var{dbx} debugger.
+
 @item -write
 @cindex @code{--write}
 Open the executable and core files for both reading and writing.  This
diff --git a/gdb/main.c b/gdb/main.c
index 5761ce2bdbe..c7325ce1077 100644
--- a/gdb/main.c
+++ b/gdb/main.c
@@ -887,12 +887,15 @@ captured_main_1 (struct captured_main_args *context)
 #endif
 	    break;
 	  case OPT_WINDOWS:
-	    /* FIXME: cagney/2003-03-01: Not sure if this option is
-	       actually useful, and if it is, what it should do.  */
 #ifdef GDBTK
 	    /* --windows is equivalent to -i=insight.  */
 	    xfree (interpreter_p);
 	    interpreter_p = xstrdup (INTERP_INSIGHT);
+#endif
+#ifdef TUI
+	    /* Or -i=tui, with a priority to tui if both are defined.  */
+	    xfree (interpreter_p);
+	    interpreter_p = xstrdup (INTERP_TUI);
 #endif
 	    break;
 	  case OPT_NOWINDOWS:
@@ -1403,66 +1406,83 @@ This is the GNU debugger.  Usage:\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\
-  --readnever        Do not read symbol files.\n\
-  --write            Set writing into executable and core files.\n\n\
+  --args                Arguments after executable-file are passed to inferior.\n\
+  --core=COREFILE, -c   Analyze the core dump COREFILE.\n\
+  --exec=EXECFILE, -e   Use EXECFILE as the executable.\n\
+  --pid=PID, -p         Attach to running process PID.\n\
+  --directory=DIR, -d   Search for source files in DIR.\n\
+  --se=FILE             Use FILE as symbol file and executable file.\n\
+  --symbols=SYMFILE, -s Read symbols from SYMFILE.\n\
+  --readnow, -r         Fully read symbol files on first access.\n\
+  --readnever           Do not read symbol files.\n\
+  --write               Set writing into executable and core files.\n\n\
 "), stream);
   fputs_unfiltered (_("\
 Initial commands and command files:\n\n\
-  --command=FILE, -x Execute GDB commands from FILE.\n\
+  --command=FILE, -x    Execute GDB commands from FILE.\n\
   --init-command=FILE, -ix\n\
-		     Like -x but execute commands before loading inferior.\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\
+		        Execute a single GDB command.\n\
+		        May be used multiple times and in conjunction\n\
+		        with --command.\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\
+		        Like -ex but before loading inferior.\n\
+  --early-init-command=FILE, -eix\n\
+                        Like -x but FILE can only contain 'set' and 'source'\n\
+                        commands to run before GDB initialization.\n\
+  --early-init-eval-command=COMMAND, -eiex\n\
+                        Like -ex but only for 'set' and 'source' commands\n\
+                        to run before GDB initialization.\n\
+  --nh                  Do not read ~/.gdbinit.\n\
+  --nx, -n              Do not read any .gdbinit files in any directory.\n\n\
 "), stream);
   fputs_unfiltered (_("\
 Output and user interface control:\n\n\
-  --fullname         Output information used by emacs-GDB interface.\n\
-  --interpreter=INTERP\n\
-		     Select a specific interpreter / user interface.\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\
+  --annotate=LEVEL      Output information used by graphical user interfaces.\n\
+  --fullname, -f        Output information used by emacs-GDB interface.\n\
+                        Like --annotate=1\n\
+  --interpreter=INTERP, --ui=INTERP, -i \n\
+		        Select a specific interpreter / user interface.\n\
+  --tty=TTY             Use TTY for input/output by the program being debugged.\n\
+  --windows, -w         Use the GUI interface.\n\
+  --nowindows, --nw     Do not use the GUI interface.\n\
 "), stream);
 #if defined(TUI)
   fputs_unfiltered (_("\
-  --tui              Use a terminal user interface.\n\
+  --tui                 Use the terminal user interface GUI.\n\
+"), stream);
+#endif
+#if defined(GDBTK)
+  fputs_unfiltered (_("\
+  --tclcommand=FILE     Load tclcommand FILE.\n\
+  --enable-external-editor\n\
+                        Ignored for backward compatibility.\n\
+  --editor-command=COMMAND\n\
+                        Set the external editor command when GDB\n\
+                        is farming out files to be edited by another program.\n\
 "), stream);
 #endif
   fputs_unfiltered (_("\
-  --dbx              DBX compatibility mode.\n\
-  -q, --quiet, --silent\n\
-		     Do not print version number on startup.\n\n\
+  --dbx                 DBX compatibility mode.\n\
+  -q, --quiet, --silent 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\
+  --batch               Exit after processing options.\n\
+  --batch-silent        Like --batch, but suppress all gdb stdout output.\n\
+  --return-child-result GDB exit code will be the child's exit code.\n\
+  --statistics          Print time and memory usage after each command.\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\
+  --baud=BAUDRATE, -b   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\
+  --cd=DIR, -cd         Change current directory to DIR.\n\
   --data-directory=DIR, -D\n\
-		     Set GDB's data-directory to DIR.\n\
+		        Set GDB's data-directory to DIR.\n\
 "), stream);
   fputs_unfiltered (_("\n\
 At startup, GDB reads the following early init files and executes their\n\
-- 
2.20.1

Re: [RFC] Fix/complete option list/description in manual and in gdb --help.

[Philippe Waroquiers]

On Sun, 2021-06-06 at 16:39 +0200, Philippe Waroquiers wrote:
> 
> Changes in main.c are:
> * the -w option was since 2003 commented as 'not sure actually useful'.
>   As -nw is disabling tui, and -w was activating an optional TK based
>   GUI, I changed the behaviour of -w to activate the TUI interface if
>   configured.  In case both TK and TUI are configured, -w starts
>   the TUI interface.
Correction: for backward compatibility reasons, in case both TK and TUI
GUIs are configured, TK based one is started (by adding its interpreter
last).

Philippe

Re: [RFC] Fix/complete option list/description in manual and in gdb --help.

[Eli Zaretskii]

> Date: Sun,  6 Jun 2021 16:39:27 +0200
> From: Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org>
> 
>   I am more used to the --long-option convention.
>   => should the user manual be changed to consistently document and use
>   --long-option ?

Yes, IMO.  And in any case, we shouldn't use both -foo and --foo for
the same option, that is just counter-productive.

> (and just mention the alternative accepted conventions?)

I wouldn't, FWIW.