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

[Vladimir Prus <vladimir@codesourcery.com>]

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