Re: RFA: gdb/783 doc change

["J. Johnston" <jjohnstn at redhat dot com>]

Elena Zannoni wrote:
> 
> J. Johnston writes:
>  > The following changes the mi documentation to clarify the usage of the
>  > "--" delimeter.  This delimeter is meant to provide a way to separate
>  > options from parameters so as to handle cases whereby the parameters may
>  > start with "-" and be mistaken for options.
>  >
>  > The problem reported tries to use it generally before any parameter list.
>  > This doesn't work because only the mi_getopt option processor knows to ignore it and
>  > commands that don't have options (preceded by dash) don't call mi_getopt.
>  > It is then treated as a parameter which is incorrect.
>  >
>  > I have removed the delimeter from the description of the -data-disassemble
>  > command as it is not manditory and the delimeter should be treated as optional to all
>  > applicable commands that support both options and parameters.  I have removed
>  > it from one of the -data-disassemble examples to clarify that it may or may not
>  > be specified.
>  >
>  > Ok to commit?
>  >
> 
> Hmmm, the current documentation specifies that a command is:
> 
> mi-command ==>
>        [ token ] "-" operation ( " " option )* [ " --" ] ( " " parameter )* nl
> 
> I.e. the -- bit is optional. Doesn't this take already care of the PR?
> The PR was filed againt 5.2.1. So the doco was updated in between then
> and now.
> 
> Maybe I am misreading the PR, though.  You cannot remove '--' from
> the data-disasssemble doco because the command really uses it.
> The generic doco change seems ok.
> 
> I'll let Eli comment.
> 
> Elena
> 

It actually doesn't look at "--".  The command processes options until mi_getopt
returns -1.  This happens if "--" is specified or if a parameter is found (no
dash preceding).  

I tried it on my local build and it properly recognizes the last argument with
or without the double-dash.  Since the delimeter is only meant to provide
the ability to specify arguments that may have dashes in front, I feel that
it is confusing to specify it needed for the command considering that the
next argument must be a format specifier that cannot start with dash.

-- Jeff J.

>  > -- Jeff J.
>  >
>  > gdb/mi/ChangeLog:
>  >
>  > 2002-11-11  Jeff Johnston  <jjohnstn@redhat.com>
>  >
>  >      * gdbmi.texinfo (GDB/MI Output Syntax): Clarify the usage of the
>  >      optional "--" delimeter.
>  >      (-data-disassemble): Remove "--" from command synopsis.  Also
>  >      change one example to not use "--".  This is a fix for PR gdb/783.Index: gdbmi.texinfo
>  > ===================================================================
>  > RCS file: /cvs/src/src/gdb/mi/gdbmi.texinfo,v
>  > retrieving revision 1.30
>  > diff -u -r1.30 gdbmi.texinfo
>  > --- gdbmi.texinfo    11 Nov 2002 17:09:50 -0000      1.30
>  > +++ gdbmi.texinfo    11 Nov 2002 23:19:50 -0000
>  > @@ -185,11 +185,15 @@
>  >  finishes.
>  >
>  >  @item
>  > -Some @sc{mi} commands accept optional arguments as part of the parameter
>  > -list.  Each option is identified by a leading @samp{-} (dash) and may be
>  > -followed by an optional argument parameter.  Options occur first in the
>  > -parameter list and can be delimited from normal parameters using
>  > -@samp{--} (this is useful when some parameters begin with a dash).
>  > +Some @sc{mi} commands accept both options and parameters;
>  > +options occur first, followed by parameters.  Since options
>  > +always start with a @samp{-} (dash),
>  > +the special @samp{--} delimeter is provided to optionally
>  > +signal the end of the option list.  This would be used in the case
>  > +where a parameter needed to start with @samp{-}.
>  > +For @sc{mi} commands that accept no arguments or that
>  > +require parameters but not options, the @samp{--} sequence should
>  > +not be used.
>  >  @end itemize
>  >
>  >  Pragmatics:
>  > @@ -1093,7 +1097,7 @@
>  >   -data-disassemble
>  >      [ -s @var{start-addr} -e @var{end-addr} ]
>  >    | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
>  > -  -- @var{mode}
>  > +  @var{mode}
>  >  @end example
>  >
>  >  @noindent
>  > @@ -1166,7 +1170,7 @@
>  >  @code{main}.
>  >
>  >  @smallexample
>  > --data-disassemble -f basics.c -l 32 -- 0
>  > +-data-disassemble -f basics.c -l 32 0
>  >  ^done,asm_insns=[
>  >  @{address="0x000107bc",func-name="main",offset="0",
>  >  inst="save  %sp, -112, %sp"@},