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

Message ID 20210611192642.19463-1-philippe.waroquiers@skynet.be
State Superseded
Headers show
Series
  • [RFA] Fix/complete option list/description in manual and in gdb --help.
Related show

Commit Message

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

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, for backward
  compatibility reasons, -w starts the TK 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
  Note that --annotate is deprecated (front ends should use GDB/MI)
  but --help is not modified to indicate this deprecation.

* 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).
  Note that --enable-external-editor is a noop kept for backward compatibility,
  but I have not modified the --help to indicate that.

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

* 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.

  The user manual was using a mixture of notations, sometimes -XXXXXX,
  sometimes --XXXXXX, sometimes both.
  Manual changed to systematically use the same notation as the --help
  output.
  The manual now only describes that options can be quite freely accepted
  with all the above different formats, but now uses in examples and index
  the classical --XXXXXXX or -Y formats.

gdb/ChangeLog
2021-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* main.c (captured_main_1): Have -w starting TUI to TK,
	use consistently -o or --option convention.
	(print_gdb_help): fix/complete help.

gdb/doc/ChangeLog
2021-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* gdb.texinfo (Invoking GDB): Complete help.  Use -- systematically
        for all long options.
---
 gdb/doc/gdb.texinfo | 149 ++++++++++++++++++++++++++------------------
 gdb/main.c          | 109 +++++++++++++++++++-------------
 2 files changed, 152 insertions(+), 106 deletions(-)

-- 
2.20.1

Comments

> Date: Fri, 11 Jun 2021 21:26:42 +0200

> From: Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org>

> 

> gdb/ChangeLog

> 2021-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

> 

> 	* main.c (captured_main_1): Have -w starting TUI to TK,

> 	use consistently -o or --option convention.

> 	(print_gdb_help): fix/complete help.

> 

> gdb/doc/ChangeLog

> 2021-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

> 

> 	* gdb.texinfo (Invoking GDB): Complete help.  Use -- systematically

>         for all long options.


Thank you for doing this.

> +Many options have both long and short forms.  Short options start with

> +@samp{-}, and long options start with @samp{--}.  @value{GDBN} also

> +recognizes the long forms if you truncate them, so long as enough of

> +the option is present to be unambiguous.  If an option requires a

> +value, the convention for long options is @samp{--option=value} and

> +@samp{-o value} for short options.

> +

> +Note however that @value{GDBN} accepts all of the following conventions

> +for most options:

> +

> +@table @code

> +@item --option=value

> +@item --option value

> +@item -option=value

> +@item -option value

> +@item -o value

> +@item -o=value

> +@item --o value

> +@item --o=value

> +@end table


The "value" parts above should have the @var markup.

> +@c NOTE: the @cindex entries here use double dashes ON PURPOSE.  This

> +@c way, both those who look for -foo and --foo in the index, will find

> +@c it.


Should this comment be before the text above, as it is relevant for it
as well?

The documentation part is OK with those nits taken care of.
Pedro Alves June 17, 2021, 10:23 a.m. | #2
On 2021-06-11 8:26 p.m., Philippe Waroquiers via Gdb-patches wrote:
> The GDB option list given in gdb --help was incomplete.

> This fixes it.  Some fixes are also done in the user manual.

> 

> 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, for backward

>   compatibility reasons, -w starts the TK interface.

>   So, now, -w is actually useful :).


Not sure I agree we should do this.  Shouldn't we instead error out if
Insight (the TK GUI) is not compiled in?  Like we do with --tui:

	  case OPT_TUI:
	    /* --tui is equivalent to -i tui.  */
#ifdef TUI
	    xfree (interpreter_p);
	    interpreter_p = xstrdup (INTERP_TUI);
#else
	    error (_("%s: TUI mode is not supported"), gdb_program_name);
#endif

> 

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

>   Note that --annotate is deprecated (front ends should use GDB/MI)

>   but --help is not modified to indicate this deprecation.

> 

> * Slightly reworded to --tui text to use the terminology GUI also used

>   by -w and --nw.


That looks odd to me, to call it a GUI.  TUI stands for "Text User Interface".

I'd say it's a TUI, not a GUI:

 https://en.wikipedia.org/wiki/Text-based_user_interface

> 

> * addition of GDBTK options (--tclcommand, --enable-external-editor,

>   --editor-command).

>   Note that --enable-external-editor is a noop kept for backward compatibility,

>   but I have not modified the --help to indicate that.

> 

> 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

> 

> * 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.

> 

>   The user manual was using a mixture of notations, sometimes -XXXXXX,

>   sometimes --XXXXXX, sometimes both.

>   Manual changed to systematically use the same notation as the --help

>   output.

>   The manual now only describes that options can be quite freely accepted

>   with all the above different formats, but now uses in examples and index

>   the classical --XXXXXXX or -Y formats.

> 

> gdb/ChangeLog

> 2021-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

> 

> 	* main.c (captured_main_1): Have -w starting TUI to TK,

> 	use consistently -o or --option convention.

> 	(print_gdb_help): fix/complete help.

> 

> gdb/doc/ChangeLog

> 2021-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

> 

> 	* gdb.texinfo (Invoking GDB): Complete help.  Use -- systematically

>         for all long options.

> ---

>  gdb/doc/gdb.texinfo | 149 ++++++++++++++++++++++++++------------------

>  gdb/main.c          | 109 +++++++++++++++++++-------------

>  2 files changed, 152 insertions(+), 106 deletions(-)

> 

> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo

> index d09b86cda95..0f5a4d0eca4 100644

> --- a/gdb/doc/gdb.texinfo

> +++ b/gdb/doc/gdb.texinfo

> @@ -921,7 +921,7 @@ options.  @value{GDBN} itself can remind you of the options available.

>  Type

>  

>  @smallexample

> -@value{GDBP} -help

> +@value{GDBP} --help

>  @end smallexample

>  

>  @noindent

> @@ -932,6 +932,31 @@ All options and command line arguments you give are processed

>  in sequential order.  The order makes a difference when the

>  @samp{-x} option is used.

>  

> +Many options have both long and short forms.  Short options start with

> +@samp{-}, and long options start with @samp{--}.  @value{GDBN} also

> +recognizes the long forms if you truncate them, so long as enough of

> +the option is present to be unambiguous. > If an option requires a



Should we actually describe this long vs short option distinction?  It isn't
actually correct.

Short options in getopt programs are one letter options that you can combine
in a single '-'.   For example "ls -als" vs "ls -a -l -s".  

In GDB, you can't do that with the "short" options.  GDB uses getopt_long_only.

"gdb -qf" is not the same as "gdb -q -f"

In GDB, the supposedly short options can also be specified with --, we install
long options for all them as well.  Well, again, we use getopt_long_only.

These are the same:

 gdb -q
 gdb --q

Or these two:

 gdb -f
 gdb --f

etc.

Also, some options listed with single dash, supposedly indicating "short" option, like -ex here:

  --eval-command=COMMAND, -ex

aren't really short options.  They are more than one character long, and they work
with both "-" and "--":

  gdb -ex CMD
  gdb --ex CMD


Instead what we have, is I think:

All options can be specified with - or --.  GDB recognizes (all, short and long if you must) options if
you truncate them, so long as enough of the option is present to be unambiguous.  For some options,
GDB recognizes a shorter form even if it would be ambiguous with some other options.

So I wonder whether the direction should be the opposite, document all options with single '-'
consistently throughout?

I have to say that I never use = with "long" options, do you?  I found it a bit weird to document
that as the canonical form, but maybe that's just me.

> -@item -init-command @var{file}

> +@item -init-command=@var{file}


This one missed the '-' -> '--'.

>  @itemx -ix @var{file}

>  @cindex @code{--init-command}

>  @cindex @code{-ix}

> @@ -1032,7 +1048,7 @@ Execute commands from file @var{file} before loading the inferior (but

>  after loading gdbinit files).

>  @xref{Startup}.

>
Thanks for the comments, I will send soon a patch RFA V2.
Some feedback about specific points below.

Philippe

On Thu, 2021-06-17 at 11:23 +0100, Pedro Alves wrote:
> On 2021-06-11 8:26 p.m., Philippe Waroquiers via Gdb-patches wrote:

> > The GDB option list given in gdb --help was incomplete.

> > This fixes it.  Some fixes are also done in the user manual.

> > 

> > 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, for backward

> >   compatibility reasons, -w starts the TK interface.

> >   So, now, -w is actually useful :).

> 

> Not sure I agree we should do this.  Shouldn't we instead error out if

> Insight (the TK GUI) is not compiled in?  Like we do with --tui:

> 

> 	  case OPT_TUI:

> 	    /* --tui is equivalent to -i tui.  */

> #ifdef TUI

> 	    xfree (interpreter_p);

> 	    interpreter_p = xstrdup (INTERP_TUI);

> #else

> 	    error (_("%s: TUI mode is not supported"), gdb_program_name);

> #endif

Currently, the code ignores -w --window if GDBTK is not configured,
and the user manual explicitly indicates this option is ignored in this case.
So, the idea of the change is:
   * do not change the behaviour that -w --window is ignored.
   * but starts the TUI if configured. It seems inconsistent to
     have -nw --nowindows disabling the TUI but -w --window not enabling it.
I have changed the --help and user manual to indicate that these options are
enabling/disable 'GUI or TUI'.


> That looks odd to me, to call it a GUI.  TUI stands for "Text User Interface".

Changed to use TUI or 'GUI or TUI' when relevant.

> ---

> >  gdb/doc/gdb.texinfo | 149 ++++++++++++++++++++++++++------------------

> >  gdb/main.c          | 109 +++++++++++++++++++-------------

> >  2 files changed, 152 insertions(+), 106 deletions(-)

> > 

> > diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo

> > index d09b86cda95..0f5a4d0eca4 100644

> > --- a/gdb/doc/gdb.texinfo

> > +++ b/gdb/doc/gdb.texinfo

> > @@ -921,7 +921,7 @@ options.  @value{GDBN} itself can remind you of the options available.

> >  Type

> >  

> >  @smallexample

> > -@value{GDBP} -help

> > +@value{GDBP} --help

> >  @end smallexample

> >  

> >  @noindent

> > @@ -932,6 +932,31 @@ All options and command line arguments you give are processed

> >  in sequential order.  The order makes a difference when the

> >  @samp{-x} option is used.

> >  

> > +Many options have both long and short forms.  Short options start with

> > +@samp{-}, and long options start with @samp{--}.  @value{GDBN} also

> > +recognizes the long forms if you truncate them, so long as enough of

> > +the option is present to be unambiguous. > If an option requires a

> 

> Should we actually describe this long vs short option distinction?  It isn't

> actually correct.

> 

> Short options in getopt programs are one letter options that you can combine

> in a single '-'.   For example "ls -als" vs "ls -a -l -s".  

> 

> In GDB, you can't do that with the "short" options.  GDB uses getopt_long_only.

> 

> "gdb -qf" is not the same as "gdb -q -f"

> 

> In GDB, the supposedly short options can also be specified with --, we install

> long options for all them as well.  Well, again, we use getopt_long_only.

> 

> These are the same:

> 

>  gdb -q

>  gdb --q

> 

> Or these two:

> 

>  gdb -f

>  gdb --f

> 

> etc.

> 

> Also, some options listed with single dash, supposedly indicating "short" option, like -ex here:

> 

>   --eval-command=COMMAND, -ex

> 

> aren't really short options.  They are more than one character long, and they work

> with both "-" and "--":

> 

>   gdb -ex CMD

>   gdb --ex CMD

> 

> 

> Instead what we have, is I think:

> 

> All options can be specified with - or --.  GDB recognizes (all, short and long if you must) options if

> you truncate them, so long as enough of the option is present to be unambiguous.  For some options,

> GDB recognizes a shorter form even if it would be ambiguous with some other options.

I have reworked the user manual based on the above.

> 

> So I wonder whether the direction should be the opposite, document all options with single '-'

> consistently throughout?

I am more used to the --option=value notation for long options.  Eli also replied that
we should use/document the --option form.

> 

> I have to say that I never use = with "long" options, do you?  I found it a bit weird to document

> that as the canonical form, but maybe that's just me.

Probably I am influenced a lot by many commands (e.g. ls) that accept and document
--option=value even if they also accept --option value.
I am likely also influenced by valgrind that only accepts --option=value form.

Note that gdb --help documents options with -- since quite a long time (1999 or before).

So, it looks to me that the user manual should better be consistent with --help.
Joel Brobecker Aug. 1, 2021, 11:19 p.m. | #4
> > +Many options have both long and short forms.  Short options start with

> > +@samp{-}, and long options start with @samp{--}.  @value{GDBN} also

> > +recognizes the long forms if you truncate them, so long as enough of

> > +the option is present to be unambiguous. > If an option requires a

> 

> 

> Should we actually describe this long vs short option distinction?  It isn't

> actually correct.

> 

> Short options in getopt programs are one letter options that you can combine

> in a single '-'.   For example "ls -als" vs "ls -a -l -s".  

> 

> In GDB, you can't do that with the "short" options.  GDB uses getopt_long_only.

> 

> "gdb -qf" is not the same as "gdb -q -f"

> 

> In GDB, the supposedly short options can also be specified with --, we install

> long options for all them as well.  Well, again, we use getopt_long_only.

> 

> These are the same:

> 

>  gdb -q

>  gdb --q

> 

> Or these two:

> 

>  gdb -f

>  gdb --f

> 

> etc.

> 

> Also, some options listed with single dash, supposedly indicating "short" option, like -ex here:

> 

>   --eval-command=COMMAND, -ex

> 

> aren't really short options.  They are more than one character long, and they work

> with both "-" and "--":

> 

>   gdb -ex CMD

>   gdb --ex CMD

> 

> 

> Instead what we have, is I think:

> 

> All options can be specified with - or --.  GDB recognizes (all, short and long if you must) options if

> you truncate them, so long as enough of the option is present to be unambiguous.  For some options,

> GDB recognizes a shorter form even if it would be ambiguous with some other options.

> 

> So I wonder whether the direction should be the opposite, document all options with single '-'

> consistently throughout?

> 

> I have to say that I never use = with "long" options, do you?  I found it a bit weird to document

> that as the canonical form, but maybe that's just me.

> 

> > -@item -init-command @var{file}

> > +@item -init-command=@var{file}

> 

> This one missed the '-' -> '--'.

> 

> >  @itemx -ix @var{file}

> >  @cindex @code{--init-command}

> >  @cindex @code{-ix}

> > @@ -1032,7 +1048,7 @@ Execute commands from file @var{file} before loading the inferior (but

> >  after loading gdbinit files).

> >  @xref{Startup}.


Fascinating... I had never realized that this.

I really don't have a real preference about what the cannonical form
should be. My initial reaction was that the typical format for long
options is with '--'. But then I thought of the single-letter "long"
options like "q"; do we really want to promote "--q"? It does make it
clear that this is indeed a single-letter option name, and that it's
not to be combined with other such single-letter options. But I do
not think this is sufficient to justify emphasizing "--q" over "-q",
knowing that this will steer people towards the longer option. I know
we're talking nano-gains in terms of efficiency, but for me, -q is
cleaner and more efficient.

If we think as long-time GDB users, I think the simplest is to
start the help and documentation by explaining that, for all
options, we treat -OPTION and --OPTION exactly the same. And then
document the -OPTION version.

But, if people think we should make an effort to conform better
to more traditional argument handling, we could, in addition to
the doc about -OPTION and --OPTIONS, chose the following approach:

  - For all options that are single-letter, use the single-dash form.
  - For all multi-letter options, use the double-dashes form.

-- 
Joel

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d09b86cda95..0f5a4d0eca4 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -921,7 +921,7 @@  options.  @value{GDBN} itself can remind you of the options available.
 Type
 
 @smallexample
-@value{GDBP} -help
+@value{GDBP} --help
 @end smallexample
 
 @noindent
@@ -932,6 +932,31 @@  All options and command line arguments you give are processed
 in sequential order.  The order makes a difference when the
 @samp{-x} option is used.
 
+Many options have both long and short forms.  Short options start with
+@samp{-}, and long options start with @samp{--}.  @value{GDBN} also
+recognizes the long forms if you truncate them, so long as enough of
+the option is present to be unambiguous.  If an option requires a
+value, the convention for long options is @samp{--option=value} and
+@samp{-o value} for short options.
+
+Note however that @value{GDBN} accepts all of the following conventions
+for most options:
+
+@table @code
+@item --option=value
+@item --option value
+@item -option=value
+@item -option value
+@item -o value
+@item -o=value
+@item --o value
+@item --o=value
+@end table
+
+@c NOTE: the @cindex entries here use double dashes ON PURPOSE.  This
+@c way, both those who look for -foo and --foo in the index, will find
+@c it.
+
 
 @menu
 * File Options::                Choosing files
@@ -945,10 +970,10 @@  in sequential order.  The order makes a difference when the
 
 When @value{GDBN} starts, it reads any arguments other than options as
 specifying an executable file and core file (or process ID).  This is
-the same as if the arguments were specified by the @samp{-se} and
+the same as if the arguments were specified by the @samp{--se} and
 @samp{-c} (or @samp{-p}) options respectively.  (@value{GDBN} reads the
 first argument that does not have an associated option flag as
-equivalent to the @samp{-se} option followed by that argument; and the
+equivalent to the @samp{--se} option followed by that argument; and the
 second argument that does not have an associated option flag, if any, as
 equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
 If the second argument begins with a decimal digit, @value{GDBN} will
@@ -961,48 +986,39 @@  If @value{GDBN} has not been configured to included core file support,
 such as for most embedded targets, then it will complain about a second
 argument and ignore it.
 
-Many options have both long and short forms; both are shown in the
-following list.  @value{GDBN} also recognizes the long forms if you truncate
-them, so long as enough of the option is present to be unambiguous.
-(If you prefer, you can flag option arguments with @samp{--} rather
-than @samp{-}, though we illustrate the more usual convention.)
-
-@c NOTE: the @cindex entries here use double dashes ON PURPOSE.  This
-@c way, both those who look for -foo and --foo in the index, will find
-@c it.
 
 @table @code
-@item -symbols @var{file}
+@item --symbols=@var{file}
 @itemx -s @var{file}
 @cindex @code{--symbols}
 @cindex @code{-s}
 Read symbol table from file @var{file}.
 
-@item -exec @var{file}
+@item --exec=@var{file}
 @itemx -e @var{file}
 @cindex @code{--exec}
 @cindex @code{-e}
 Use file @var{file} as the executable file to execute when appropriate,
 and for examining pure data in conjunction with a core dump.
 
-@item -se @var{file}
+@item --se=@var{file}
 @cindex @code{--se}
 Read symbol table from file @var{file} and use it as the executable
 file.
 
-@item -core @var{file}
+@item --core=@var{file}
 @itemx -c @var{file}
 @cindex @code{--core}
 @cindex @code{-c}
 Use file @var{file} as a core dump to examine.
 
-@item -pid @var{number}
+@item --pid=@var{number}
 @itemx -p @var{number}
 @cindex @code{--pid}
 @cindex @code{-p}
 Connect to process ID @var{number}, as with the @code{attach} command.
 
-@item -command @var{file}
+@item --command=@var{file}
 @itemx -x @var{file}
 @cindex @code{--command}
 @cindex @code{-x}
@@ -1010,21 +1026,21 @@  Execute commands from file @var{file}.  The contents of this file is
 evaluated exactly as the @code{source} command would.
 @xref{Command Files,, Command files}.
 
-@item -eval-command @var{command}
+@item --eval-command=@var{command}
 @itemx -ex @var{command}
 @cindex @code{--eval-command}
 @cindex @code{-ex}
 Execute a single @value{GDBN} command.
 
 This option may be used multiple times to call multiple commands.  It may
-also be interleaved with @samp{-command} as required.
+also be interleaved with @samp{--command} as required.
 
 @smallexample
 @value{GDBP} -ex 'target sim' -ex 'load' \
    -x setbreakpoints -ex 'run' a.out
 @end smallexample
 
-@item -init-command @var{file}
+@item -init-command=@var{file}
 @itemx -ix @var{file}
 @cindex @code{--init-command}
 @cindex @code{-ix}
@@ -1032,7 +1048,7 @@  Execute commands from file @var{file} before loading the inferior (but
 after loading gdbinit files).
 @xref{Startup}.
 
-@item -init-eval-command @var{command}
+@item --init-eval-command=@var{command}
 @itemx -iex @var{command}
 @cindex @code{--init-eval-command}
 @cindex @code{-iex}
@@ -1040,28 +1056,28 @@  Execute a single @value{GDBN} command before loading the inferior (but
 after loading gdbinit files).
 @xref{Startup}.
 
-@item -early-init-command @var{file}
+@item --early-init-command=@var{file}
 @itemx -eix @var{file}
 @cindex @code{--early-init-command}
 @cindex @code{-eix}
 Execute commands from @var{file} very early in the initialization
 process, before any output is produced.  @xref{Startup}.
 
-@item -early-init-eval-command @var{command}
+@item --early-init-eval-command=@var{command}
 @itemx -eiex @var{command}
 @cindex @code{--early-init-eval-command}
 @cindex @code{-eiex}
 Execute a single @value{GDBN} command very early in the initialization
 process, before any output is produced.
 
-@item -directory @var{directory}
+@item --directory=@var{directory}
 @itemx -d @var{directory}
 @cindex @code{--directory}
 @cindex @code{-d}
 Add @var{directory} to the path to search for source and script files.
 
 @item -r
-@itemx -readnow
+@itemx --readnow
 @cindex @code{--readnow}
 @cindex @code{-r}
 Read each symbol file's entire symbol table immediately, rather than
@@ -1087,24 +1103,24 @@  You can run @value{GDBN} in various alternative modes---for example, in
 batch mode or quiet mode.
 
 @table @code
-@anchor{-nx}
-@item -nx
+@anchor{--nx}
+@item --nx
 @itemx -n
 @cindex @code{--nx}
 @cindex @code{-n}
 Do not execute commands found in any initialization files
 (@pxref{Initialization Files}).
 
-@anchor{-nh}
-@item -nh
+@anchor{--nh}
+@item --nh
 @cindex @code{--nh}
 Do not execute commands found in any home directory initialization
 file (@pxref{Initialization Files,,Home directory initialization
 file}).  The system wide and current directory initialization files
 are still loaded.
 
-@item -quiet
-@itemx -silent
+@item --quiet
+@itemx --silent
 @itemx -q
 @cindex @code{--quiet}
 @cindex @code{--silent}
@@ -1120,7 +1136,7 @@  current setting.  Place @code{set startup-quietly on} into your early
 initialization file (@pxref{Initialization Files,,Initialization
 Files}) to have future @value{GDBN} sessions startup quietly.
 
-@item -batch
+@item --batch
 @cindex @code{--batch}
 Run in batch mode.  Exit with status @code{0} after processing all the
 command files specified with @samp{-x} (and all commands from
@@ -1143,11 +1159,11 @@  Program exited normally.
 @value{GDBN} control terminates) is not issued when running in batch
 mode.
 
-@item -batch-silent
+@item --batch-silent
 @cindex @code{--batch-silent}
-Run in batch mode exactly like @samp{-batch}, but totally silently.  All
+Run in batch mode exactly like @samp{--batch}, but totally silently.  All
 @value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
-unaffected).  This is much quieter than @samp{-silent} and would be useless
+unaffected).  This is much quieter than @samp{--silent} and would be useless
 for an interactive session.
 
 This is particularly useful when using targets that give @samp{Loading section}
@@ -1156,7 +1172,7 @@  messages, for example.
 Note that targets that give their output via @value{GDBN}, as opposed to
 writing directly to @code{stdout}, will also be made silent.
 
-@item -return-child-result
+@item --return-child-result
 @cindex @code{--return-child-result}
 The return code from @value{GDBN} will be the return code from the child
 process (the process being debugged), with the following exceptions:
@@ -1165,7 +1181,7 @@  process (the process being debugged), with the following exceptions:
 @item
 @value{GDBN} exits abnormally.  E.g., due to an incorrect argument or an
 internal error.  In this case the exit code is the same as it would have been
-without @samp{-return-child-result}.
+without @samp{--return-child-result}.
 @item
 The user quits with an explicit value.  E.g., @samp{quit 1}.
 @item
@@ -1173,19 +1189,19 @@  The child process never runs, or is not allowed to terminate, in which case
 the exit code will be -1.
 @end itemize
 
-This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
-when @value{GDBN} is being used as a remote program loader or simulator
-interface.
+This option is useful in conjunction with @samp{--batch} or
+@samp{--batch-silent}, when @value{GDBN} is being used as a remote
+program loader or simulator interface.
 
-@item -nowindows
-@itemx -nw
+@item --nowindows
+@itemx --nw
 @cindex @code{--nowindows}
-@cindex @code{-nw}
+@cindex @code{--nw}
 ``No windows''.  If @value{GDBN} comes with a graphical user interface
 (GUI) built in, then this option tells @value{GDBN} to only use the command-line
 interface.  If no GUI is available, this option has no effect.
 
-@item -windows
+@item --windows
 @itemx -w
 @cindex @code{--windows}
 @cindex @code{-w}
@@ -1193,11 +1209,12 @@  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.
 
-@item -data-directory @var{directory}
+@item --data-directory=@var{directory}
 @itemx -D @var{directory}
 @cindex @code{--data-directory}
 @cindex @code{-D}
@@ -1205,7 +1222,7 @@  Run @value{GDBN} using @var{directory} as its data directory.
 The data directory is where @value{GDBN} searches for its
 auxiliary files.  @xref{Data Files}.
 
-@item -fullname
+@item --fullname
 @itemx -f
 @cindex @code{--fullname}
 @cindex @code{-f}
@@ -1219,7 +1236,7 @@  and a newline.  The Emacs-to-@value{GDBN} interface program uses the two
 @samp{\032} characters as a signal to display the source code for the
 frame.
 
-@item -annotate @var{level}
+@item --annotate=@var{level}
 @cindex @code{--annotate}
 This option sets the @dfn{annotation level} inside @value{GDBN}.  Its
 effect is identical to using @samp{set annotate @var{level}}
@@ -1239,7 +1256,7 @@  Change interpretation of command line so that arguments following the
 executable file are passed as command line arguments to the inferior.
 This option stops option processing.
 
-@item -baud @var{bps}
+@item --baud=@var{bps}
 @itemx -b @var{bps}
 @cindex @code{--baud}
 @cindex @code{-b}
@@ -1251,15 +1268,13 @@  interface used by @value{GDBN} for remote debugging.
 Set the timeout (in seconds) of any communication used by @value{GDBN}
 for remote debugging.
 
-@item -tty @var{device}
-@itemx -t @var{device}
+@item --tty=@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.
 
 @c resolve the situation of these eventually
-@item -tui
+@item --tui
 @cindex @code{--tui}
 Activate the @dfn{Text User Interface} when starting.  The Text User
 Interface manages several text windows on the terminal, showing
@@ -1268,8 +1283,12 @@  source, assembly, registers and @value{GDBN} command outputs
 option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
 Using @value{GDBN} under @sc{gnu} Emacs}).
 
-@item -interpreter @var{interp}
+@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,23 +1301,29 @@  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 -write
+@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
 is equivalent to the @samp{set write on} command inside @value{GDBN}
 (@pxref{Patching}).
 
-@item -statistics
+@item --statistics
 @cindex @code{--statistics}
 This option causes @value{GDBN} to print statistics about time and
 memory usage after it completes each command and returns to the prompt.
 
-@item -version
+@item --version
 @cindex @code{--version}
 This option causes @value{GDBN} to print its version number and
 no-warranty blurb, and exit.
 
-@item -configuration
+@item --configuration
 @cindex @code{--configuration}
 This option causes @value{GDBN} to print details about its build-time
 configuration parameters, and then exit.  These details can be
@@ -1344,7 +1369,7 @@  Reads the initialization file (if any) in your home directory and
 executes all the commands in that file, @pxref{Home Directory Init
 File}.
 
-@anchor{Option -init-eval-command}
+@anchor{Option --init-eval-command}
 @item
 Executes commands and command files specified by the @samp{-iex} and
 @samp{-ix} options in their specified order.  Usually you should use the
@@ -1544,7 +1569,7 @@  While on Apple hosts the locations searched are:
 @end table
 
 It is possible to prevent the home directory initialization file from
-being loaded using the @samp{-nx} or @samp{-nh} command line options,
+being loaded using the @samp{--nx} or @samp{--nh} command line options,
 @pxref{Mode Options,,Choosing Modes}.
 
 The DJGPP port of @value{GDBN} uses the name @file{gdb.ini} instead of
@@ -1569,7 +1594,7 @@  directory initialization file then it will not be loaded a second
 time.
 
 It is possible to prevent the local directory initialization file from
-being loaded using the @samp{-nx} command line option, @pxref{Mode
+being loaded using the @samp{--nx} command line option, @pxref{Mode
 Options,,Choosing Modes}.
 
 @node Quitting GDB
@@ -26301,7 +26326,7 @@  control when to auto-load files and which files should be auto-loaded.
 @item set auto-load off
 Globally disable loading of all auto-loaded files.
 You may want to use this command with the @samp{-iex} option
-(@pxref{Option -init-eval-command}) such as:
+(@pxref{Option --init-eval-command}) such as:
 @smallexample
 $ @kbd{gdb -iex "set auto-load off" untrusted-executable corefile}
 @end smallexample
diff --git a/gdb/main.c b/gdb/main.c
index 5761ce2bdbe..3ea01f9f056 100644
--- a/gdb/main.c
+++ b/gdb/main.c
@@ -878,7 +878,7 @@  captured_main_1 (struct captured_main_args *context)
 	    set_per_command_space (1);
 	    break;
 	  case OPT_TUI:
-	    /* --tui is equivalent to -i=tui.  */
+	    /* --tui is equivalent to -i tui.  */
 #ifdef TUI
 	    xfree (interpreter_p);
 	    interpreter_p = xstrdup (INTERP_TUI);
@@ -887,16 +887,20 @@  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.  */
+	    /* --windows is equivalent to -i insight or -i tui.
+               If both are defined, for backward compatibility reasons,
+	       priority is given to -i insight.  */
+#ifdef TUI
+	    xfree (interpreter_p);
+	    interpreter_p = xstrdup (INTERP_TUI);
+#endif
 #ifdef GDBTK
-	    /* --windows is equivalent to -i=insight.  */
 	    xfree (interpreter_p);
 	    interpreter_p = xstrdup (INTERP_INSIGHT);
 #endif
 	    break;
 	  case OPT_NOWINDOWS:
-	    /* -nw is equivalent to -i=console.  */
+	    /* -nw is equivalent to --interpreter=console.  */
 	    xfree (interpreter_p);
 	    interpreter_p = xstrdup (INTERP_CONSOLE);
 	    break;
@@ -1403,66 +1407,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\