Re: RFA: gdb/783 doc change

[Elena Zannoni <ezannoni@redhat.com>]

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


 > -- 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"@},