RFA: gdb/783 doc change

["J. Johnston" <jjohnstn@redhat.com>]

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