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

[Joel Brobecker <brobecker@adacore.com>]

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