RFA: gdb/783 doc change

RFA: gdb/783 doc change

[J. Johnston]

[-- Attachment #1: Type: text/plain, Size: 1202 bytes --]

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?

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

[-- Attachment #2: 783.doc.patch --]
[-- Type: text/plain, Size: 1629 bytes --]

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

Re: RFA: gdb/783 doc change

[Elena Zannoni]

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

Re: RFA: gdb/783 doc change

[Andrew Cagney]

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

The documentation is correct, there is no reason for changing it.

All MI commands should use mi_getopt() as by doing this the MI can 
present a very consistent command line interface to its users.  Contrast 
this to the UNIX and GDB CLI interfaces, each individual command has its 
own eseoteric edge conditions (and the user needs to work around each 
individually).  The ``--'' problem is just one of the cases that 
mi_getopt() handles, another is c-strings (see below).

In case you're wondering, the commands that don't use mi_getopt() 
pre-date that function's implementation (and one has gone back and 
updated them).

For the most part converting commands to use mi_getopt() should be 
straight forward.  There are exceptions though, some of the older 
commands pulled a very GDB CLI like hack by accepting:
	-command -opt x this is the "final" parameter
when they should have accepted:
	-command -opt x -- "this is the \"final\" parameter"
such a change will get messy and might mean replacing the command.

>  > Ok to commit?

No.

Andrew

Re: RFA: gdb/783 doc change

[J. Johnston]

Andrew Cagney 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.
> 
> The documentation is correct, there is no reason for changing it.
> 
> All MI commands should use mi_getopt() as by doing this the MI can
> present a very consistent command line interface to its users.  Contrast
> this to the UNIX and GDB CLI interfaces, each individual command has its
> own eseoteric edge conditions (and the user needs to work around each
> individually).  The ``--'' problem is just one of the cases that
> mi_getopt() handles, another is c-strings (see below).
> 
> In case you're wondering, the commands that don't use mi_getopt()
> pre-date that function's implementation (and one has gone back and
> updated them).
> 
> For the most part converting commands to use mi_getopt() should be
> straight forward.  There are exceptions though, some of the older
> commands pulled a very GDB CLI like hack by accepting:
>         -command -opt x this is the "final" parameter
> when they should have accepted:
>         -command -opt x -- "this is the \"final\" parameter"
> such a change will get messy and might mean replacing the command.
> 
> >  > Ok to commit?
> 
> No.
> 

Ignore my previous post then.

-- Jeff J.

Re: RFA: gdb/783 doc change

[J. Johnston]

Andrew Cagney 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.
> 
> The documentation is correct, there is no reason for changing it.
> 
> All MI commands should use mi_getopt() as by doing this the MI can
> present a very consistent command line interface to its users.  Contrast
> this to the UNIX and GDB CLI interfaces, each individual command has its
> own eseoteric edge conditions (and the user needs to work around each
> individually).  The ``--'' problem is just one of the cases that
> mi_getopt() handles, another is c-strings (see below).
> 
> In case you're wondering, the commands that don't use mi_getopt()
> pre-date that function's implementation (and one has gone back and
> updated them).
> 
> For the most part converting commands to use mi_getopt() should be
> straight forward.  There are exceptions though, some of the older
> commands pulled a very GDB CLI like hack by accepting:
>         -command -opt x this is the "final" parameter
> when they should have accepted:
>         -command -opt x -- "this is the \"final\" parameter"
> such a change will get messy and might mean replacing the command.
> 

Could you please clarify this?  The mi_getopt code currently returns -1
when it sees a "--" or an argument that does not start with a "-".  It
sets optind to 1 so you can skip over the "--", but it is not
used to do any parsing of regular parameters beyond the option list.

Could you also clarify what you want to do with commands that currently
do not accept options.  For example, -data-disassemble only accepts parameters.
If the command is not changed to accept options, then you just want the
mi_getopt for the sake of skipping the "--".  If correct, this seems wasteful.
I can't imagine why an application would want or need to call a command this way.

-- Jeff J.

Re: RFA: gdb/783 doc change

[J. Johnston]

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

Re: RFA: gdb/783 doc change

[Eli Zaretskii]

> From: Elena Zannoni <ezannoni@redhat.com>
> Date: Mon, 11 Nov 2002 19:40:00 -0500
> 
> 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.

Andrew already responded to this (and I agree with what he said).