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

[Philippe Waroquiers]

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.