[PATCH:doc] GDB/MI attribute names

[PATCH:doc] GDB/MI attribute names

[Nick Roberts]

This patch, slightly paranoid, document the current practice for attribute
names.  I don't want future names to break exiting parsers.

-- 
Nick                                           http://users.snap.net.nz/~nickrob

2009-09-24  Nick Roberts  <nickrob@snap.net.nz>

	* gdb.texinfo (GDB/MI Output Syntax): Document current practice
	for attribute names.


*** gdb.texinfo.~1.628.~	2009-09-22 10:40:52.000000000 +1200
--- gdb.texinfo	2009-09-24 21:58:16.000000000 +1200
*************** the log output is prefixed by @samp{&}.
*** 21260,21265 ****
--- 21260,21268 ----
  New @sc{gdb/mi} commands should only output @var{lists} containing
  @var{values}.
  
+ @item
+ @var{variable} expressions should be alphabetic words or comprise of
+ alphabetic words separated by underscores.
  
  @end itemize
  

Re: [PATCH:doc] GDB/MI attribute names

[Eli Zaretskii]

> Date: Thu, 24 Sep 2009 22:04:04 +1200
> From: nickrob@snap.net.nz (Nick Roberts)
> 
> This patch, slightly paranoid, document the current practice for attribute
> names.  I don't want future names to break exiting parsers.

I agree, assuming that what you wrote is factually correct at this
point, and that we have no good reasons to modify it VSN.  Is that
indeed so?

> + @var{variable} expressions should be alphabetic words or comprise of
> + alphabetic words separated by underscores.               ^^^^^^^^^^^

Don't you meant "comprised of"?

In any case, the text you suggests sounds a bit inaccurate to me.
(Maybe I just don't know enough about MI, so please bear with me.)
You say "variable expressions", but an expression can use operators,
can't it?  If it can, then the operators are not generally alphabetic
characters.

Based on my understanding of what you meant, I suggest to rephrase as
follows:

  Every @var{variable} should be specified as a sequence of alphabetic
  characters and underscores.

Does that reflect correctly what you wanted to say?

Btw, are digit really "verboten"?  If not, replace "alphabetic" with
"alphanumeric" above.

Thanks.

Re: [PATCH:doc] GDB/MI attribute names

[Nick Roberts]

 > > This patch, slightly paranoid, document the current practice for attribute
 > > names.  I don't want future names to break exiting parsers.
 > 
 > I agree, assuming that what you wrote is factually correct at this
 > point, and that we have no good reasons to modify it VSN.  Is that
 > indeed so?

I can't find any that don't fit the rule that I want to document.  It occurred
to me that the regexp that I was using to parse MI output for Emacs wouldn't
work if certain characters, e.g "$", were used.  I just want to discourage
their use in future attribute names.  Parsers will have to handle existing
anomalies, if any.

 > > + @var{variable} expressions should be alphabetic words or comprise of
 > > + alphabetic words separated by underscores.               ^^^^^^^^^^^
 > 
 > Don't you meant "comprised of"?

Either sounds OK to me.

 > In any case, the text you suggests sounds a bit inaccurate to me.
 > (Maybe I just don't know enough about MI, so please bear with me.)
 > You say "variable expressions", but an expression can use operators,
 > can't it?  If it can, then the operators are not generally alphabetic
 > characters.

No I don't really mean expression.

 @var{variable} names...

would probably work.

 > Based on my understanding of what you meant, I suggest to rephrase as
 > follows:
 > 
 >   Every @var{variable} should be specified as a sequence of alphabetic
 >   characters and underscores.
 > 
 > Does that reflect correctly what you wanted to say?

I'm not sure.  To me, thay're not really variables but a field names (or
attribute names in HTML/XML parlance).  It might mean the value rather than
the name.

How about:

   @var{variable} names should be specified as a sequence of alphabetic
   characters and underscores.

Or say what you would like to see.  I'm not too worried about the exact
wording.  I just want to formalise the output syntax a bit more.


 > Btw, are digit really "verboten"?  If not, replace "alphabetic" with
 > "alphanumeric" above.

I've actually used the [:alnum:] character class in my parser but there are so
few names that I felt that requiring alphabetic wouldn't be restrictive.


-- 
Nick                                           http://users.snap.net.nz/~nickrob

Re: [PATCH:doc] GDB/MI attribute names

[Vladimir Prus]

Nick Roberts wrote:

>  > Does that reflect correctly what you wanted to say?
> 
> I'm not sure.  To me, thay're not really variables but a field names (or
> attribute names in HTML/XML parlance).  It might mean the value rather than
> the name.
> 
> How about:
> 
>    @var{variable} names should be specified as a sequence of alphabetic
>    characters and underscores.

It seem to me to introduce too many indirection levels. We don't have something
called 'variable' that also has name, that is also 'specified' by something
separate. Why not:

     The @var{variable} nonterminal in the above grammar may contain only
     alphanumeric characters or the underscore character.

? This is probably not 100% accurate either, since nonterminals do not contain
characters but have terminal strings derived from them, which strings consist of 
characters, but I presume we're not writing a PhD here ;-)      

- Volodya

Re: [PATCH:doc] GDB/MI attribute names

[Nick Roberts]

 > > How about:
 > > 
 > >    @var{variable} names should be specified as a sequence of alphabetic
 > >    characters and underscores.
 > 
 > It seem to me to introduce too many indirection levels. We don't have something
 > called 'variable' that also has name, that is also 'specified' by something
 > separate. Why not:
 > 
 >      The @var{variable} nonterminal in the above grammar may contain only
 >      alphanumeric characters or the underscore character.
 > 
 > ? This is probably not 100% accurate either, since nonterminals do not
 > contain characters but have terminal strings derived from them, which
 > strings consist of characters, but I presume we're not writing a PhD here
 > ;-)

I had to look up `nonterminal' in Wikipedia where it talks about
Backus?Naur Form.  Having read that,

  <VARIABLE> should be specified as a sequence of alphabetic
  characters and underscores.

seems good to me.  Apparently it's a widely used syntax and it looks familiar
to me, e.g., the git manpages and we could use it for existing documentation,
e.g.,

<RESULT-RECORD> ::=  [ <TOKEN> ] "^" <RESULT-CLASS> ( "," <RESULT> )* <NL>

rather than the currently ad-hoc(?) metasyntax.


-- 
Nick                                           http://users.snap.net.nz/~nickrob

Re: [PATCH:doc] GDB/MI attribute names

[Vladimir Prus]

Nick Roberts wrote:

>  > > How about:
>  > > 
>  > >    @var{variable} names should be specified as a sequence of alphabetic
>  > >    characters and underscores.
>  > 
>  > It seem to me to introduce too many indirection levels. We don't have something
>  > called 'variable' that also has name, that is also 'specified' by something
>  > separate. Why not:
>  > 
>  >      The @var{variable} nonterminal in the above grammar may contain only
>  >      alphanumeric characters or the underscore character.
>  > 
>  > ? This is probably not 100% accurate either, since nonterminals do not
>  > contain characters but have terminal strings derived from them, which
>  > strings consist of characters, but I presume we're not writing a PhD here
>  > ;-)
> 
> I had to look up `nonterminal' in Wikipedia where it talks about
> Backus?Naur Form.  Having read that,
> 
>   <VARIABLE> should be specified as a sequence of alphabetic
>   characters and underscores.

That's again using the word 'specified', as if VARIABLE is something you write
specification for, and you are restricted in how you can write such specification.
Rather, VARIABLE *is* a sequence of alphabetic characters and underscores.

Anyway, this is probably too minor for me to further complain about.

> seems good to me.  Apparently it's a widely used syntax and it looks familiar
> to me, e.g., the git manpages and we could use it for existing documentation,
> e.g.,
> 
> <RESULT-RECORD> ::=  [ <TOKEN> ] "^" <RESULT-CLASS> ( "," <RESULT> )* <NL>
> 
> rather than the currently ad-hoc(?) metasyntax.

In fact, the current convention is just as good as putting nonterminal names in
angle brackets. BTW, probably the best way to fix documentation is actually
define 'string'. We have definition for c-string:

        c-string ==> 
        """ seven-bit-iso-c-string-content """

and can add this:

        string ==> 
        """ ( letter | digit | "_" ) * """

This is much more formal than anything else we can say.

- Volodya

Re: [PATCH:doc] GDB/MI attribute names

[Eli Zaretskii]

> Date: Fri, 25 Sep 2009 22:55:19 +1200
> Cc: gdb-patches@sources.redhat.com
> From: nickrob@snap.net.nz (Nick Roberts)
> 
> How about:
> 
>    @var{variable} names should be specified as a sequence of alphabetic
>    characters and underscores.

Fine with me.  Thanks.

Re: [PATCH:doc] GDB/MI attribute names

[Eli Zaretskii]

> From:  Vladimir Prus <vladimir@codesourcery.com>
> Date:  Fri, 25 Sep 2009 15:09:12 +0400
> 
> >    @var{variable} names should be specified as a sequence of alphabetic
> >    characters and underscores.
> 
> It seem to me to introduce too many indirection levels. We don't have something
> called 'variable' that also has name, that is also 'specified' by something
> separate.

What do you think about my suggestion?

> Why not:
> 
>      The @var{variable} nonterminal in the above grammar may contain only
>      alphanumeric characters or the underscore character.

I'd prefer not to use ``nonterminal'', as it might not be known to a
reader who didn't study formal grammars and parsers.  We don't use
this terminology anywhere else in the manual.

Re: [PATCH:doc] GDB/MI attribute names

[Eli Zaretskii]

> From:  Vladimir Prus <vladimir@codesourcery.com>
> Date:  Fri, 25 Sep 2009 16:50:53 +0400
> 
> >   <VARIABLE> should be specified as a sequence of alphabetic
> >   characters and underscores.
> 
> That's again using the word 'specified', as if VARIABLE is something you write
> specification for

No, you are interpreting the word ``specified'' to narrowly.  It also
means ``given'', please see how we use it elsewhere in the manual.

Re: [PATCH:doc] GDB/MI attribute names

[Vladimir Prus]

Eli Zaretskii wrote:

>> From:  Vladimir Prus <vladimir@codesourcery.com>
>> Date:  Fri, 25 Sep 2009 16:50:53 +0400
>> 
>> >   <VARIABLE> should be specified as a sequence of alphabetic
>> >   characters and underscores.
>> 
>> That's again using the word 'specified', as if VARIABLE is something you write
>> specification for
> 
> No, you are interpreting the word ``specified'' to narrowly.  It also
> means ``given'', please see how we use it elsewhere in the manual.

The 'given' is not right here either I'm afraid. 'variable' *is* a sequence. The
wording above suggest that there are alternative ways to describe a variable,
and somebody should use the way that uses alphanumerical characters.

- Volodya

Re: [PATCH:doc] GDB/MI attribute names

[Vladimir Prus]

Eli Zaretskii wrote:

>> From:  Vladimir Prus <vladimir@codesourcery.com>
>> Date:  Fri, 25 Sep 2009 15:09:12 +0400
>> 
>> >    @var{variable} names should be specified as a sequence of alphabetic
>> >    characters and underscores.
>> 
>> It seem to me to introduce too many indirection levels. We don't have something
>> called 'variable' that also has name, that is also 'specified' by something
>> separate.
> 
> What do you think about my suggestion?

It still has the same problem -- it separates 'variable'  and 'specification' thereof, 
while those are one and the same thing. I think that my last suggestion of modifying the grammar is
the best
approach.

- Volodya

Re: [PATCH:doc] GDB/MI attribute names

[Eli Zaretskii]

> From:  Vladimir Prus <vladimir@codesourcery.com>
> Date:  Fri, 25 Sep 2009 17:34:28 +0400
> 
> 'variable' *is* a sequence.

Let's not start an argument about the differences between a thing, its
name, and a specification of the name ;-)

Can you suggest an alternative that doesn't use terminology which
could be unknown to the reader?

Re: [PATCH:doc] GDB/MI attribute names

[Vladimir Prus]

Eli Zaretskii wrote:

>> From:  Vladimir Prus <vladimir@codesourcery.com>
>> Date:  Fri, 25 Sep 2009 17:34:28 +0400
>> 
>> 'variable' *is* a sequence.
> 
> Let's not start an argument about the differences between a thing, its
> name, and a specification of the name ;-)
> 
> Can you suggest an alternative that doesn't use terminology which
> could be unknown to the reader?

I have already suggested:

        string ==> 
        """ ( letter | digit | "_" ) * """

This at least uses a terminology that is already used in the 
manual.

- Volodya

Re: [PATCH:doc] GDB/MI attribute names

[Eli Zaretskii]

> From:  Vladimir Prus <vladimir@codesourcery.com>
> Date:  Fri, 25 Sep 2009 18:14:55 +0400
> 
> > Can you suggest an alternative that doesn't use terminology which
> > could be unknown to the reader?
> 
> I have already suggested:
> 
>         string ==> 
>         """ ( letter | digit | "_" ) * """

Fine with me.  Thanks.

Re: [PATCH:doc] GDB/MI attribute names

[Nick Roberts]

 > I have already suggested:
 > 
 >         string ==> 
 >         """ ( letter | digit | "_" ) * """
 > 
 > This at least uses a terminology that is already used in the 
 > manual.

This could drag on and I guess the above is adequate for the case under
discussion but I don't understand the existing syntax.  I can guess what it
means but why are there three pairs of double quotes?  When inserted into info
it all gets enclosed in further single quotes.  The usual meaning of `string'
gets re-defined and * means 0 or more, so the empty string would be valid.
Also we probably don't want a field name to start with a digit.  Current names
don't use digits at all and my initial proposal was not to include them in the
specification.

I don't see this combination of grouping and alternatives elsewhere
and in BNF maybe it should look something like:

<fieldchar> ::== <letter> | <digit> | "_"
<variable> ::==  <letter> <fieldchar> +



-- 
Nick                                           http://users.snap.net.nz/~nickrob

Re: [PATCH:doc] GDB/MI attribute names

[Nick Roberts]

 >                                                  ...I can guess what it
 > means but why are there three pairs of double quotes?

I see why now. Perhaps something like:

   <fieldchar> ::== <letter> | <digit> | "_"
   <variable>  ::==  """ <letter> ( <fieldchar> )+ """

I would prefer to use BNF as it seems quite widespread and I've not seen

`COMMAND ==>'
     `CLI-COMMAND | MI-COMMAND'

as a syntax anywhere else.

-- 
Nick                                           http://users.snap.net.nz/~nickrob

Re: [PATCH:doc] GDB/MI attribute names

[Eli Zaretskii]

> Date: Sat, 26 Sep 2009 10:31:41 +1200
> Cc: gdb-patches@sources.redhat.com
> From: nickrob@snap.net.nz (Nick Roberts)
> 
> I can guess what it means but why are there three pairs of double
> quotes?  When inserted into info it all gets enclosed in further
> single quotes.  The usual meaning of `string' gets re-defined and *
> means 0 or more, so the empty string would be valid.  Also we
> probably don't want a field name to start with a digit.  Current
> names don't use digits at all and my initial proposal was not to
> include them in the specification.

If Texinfo markup and the way the result looks in Info are the
problem, then tell me how would you like it to look in Info, and I
will suggest the markup.

Wrt rest, I will go with anything you two agree upon.  I only tried to
suggest alternatives from the documentation readability POV, not
because I know more about the subject matter than you do.  IOW, my
comments were stylistic, not about the essence.

Re: [PATCH:doc] GDB/MI attribute names

[Vladimir Prus]

On Saturday 26 September 2009 Nick Roberts wrote:

>  >                                                  ...I can guess what it
>  > means but why are there three pairs of double quotes?
> 
> I see why now. Perhaps something like:
> 
>    <fieldchar> ::== <letter> | <digit> | "_"
>    <variable>  ::==  """ <letter> ( <fieldchar> )+ """

I would say it's better to inline 'fieldchar' inside 'variable' here, since
we're not using it elsewhere. E.g.:

    variable ==> """ letter ( letter | digit | "_" ) * """

> I would prefer to use BNF as it seems quite widespread and I've not seen
> 
> `COMMAND ==>'
>      `CLI-COMMAND | MI-COMMAND'
> 
> as a syntax anywhere else.

I'd suggest we first fix the direct problem that hand -- which is documenting 
that field names may not use random characters. And for that, can we use the
syntax that is already used?

We can discuss global change of grammar notation. I don't have a well-formed
opinion about the specific characters used to express the grammar -- I 
found the current one fairly clear, and the difference between :== and 
==> seems insignificant.

- Volodya