[RFC, doc] fix document error on the grammar of GDB/MI output format syntax

[RFC, doc] fix document error on the grammar of GDB/MI output format syntax

[asmwarrior]

Hi, I noticed that GDB has a "new line" in the end of "out-of-band-record".
But the document does not correctly describe this. See here:
https://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI-Output-Syntax.html#GDB_002fMI-Output-Syntax
Some discussion has already in GDB maillist, see: https://sourceware.org/ml/gdb/2013-12/msg00058.html

As Joel suggested there that the change should be both reviewed by Eli and some GDB maintainer.

The change log could be: Fix syntax description error about GDB/MI "out-of-band-record", there should be a "new line" in end.

Thanks.

Yuanhui Zhang


 gdb/doc/gdb.texinfo | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b7551c2..a8b888c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -29160,7 +29160,7 @@ corresponding output for that command will also be prefixed by that same
 @code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
 
 @item @var{out-of-band-record} @expansion{}
-@code{@var{async-record} | @var{stream-record}}
+@code{@var{async-record} @var{nl} | @var{stream-record} @var{nl}}
 
 @item @var{async-record} @expansion{}
 @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}

Re: [RFC, doc] fix document error on the grammar of GDB/MI output format syntax

[Joel Brobecker]

> The change log could be: Fix syntax description error about GDB/MI "out-of-band-record", there should be a "new line" in end.
> 
> Thanks.
> 
> Yuanhui Zhang

I may have given you bad advice when we discussed this on gdb@.
Looking at the patch, I see you're repeating the "nl", which
was what I thought we could avoid. But now that we're trying to
implement the suggestion, and re-reading the grammar, it might
make better logical sense to group the marker used for a given
output report (Eg: "*" or "=") and the associated nl in the same
rule.

Concretely, this is the patch I would suggest instead (you'll notice
that I removed one such "nl") to move it elsewhere.  I think it's an
extension of what you originally suggested?

Sorry about flip-flopping on you like that...

-- 
Joel

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b7551c2..f392733 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -29166,16 +29166,16 @@ corresponding output for that command will also be prefixed by that same
 @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
 
 @item @var{exec-async-output} @expansion{}
-@code{[ @var{token} ] "*" @var{async-output}}
+@code{[ @var{token} ] "*" @var{async-output}} @var{nl}
 
 @item @var{status-async-output} @expansion{}
-@code{[ @var{token} ] "+" @var{async-output}}
+@code{[ @var{token} ] "+" @var{async-output}} @var{nl}
 
 @item @var{notify-async-output} @expansion{}
-@code{[ @var{token} ] "=" @var{async-output}}
+@code{[ @var{token} ] "=" @var{async-output}} @var{nl}
 
 @item @var{async-output} @expansion{}
-@code{@var{async-class} ( "," @var{result} )* @var{nl}}
+@code{@var{async-class} ( "," @var{result} )*
 
 @item @var{result-class} @expansion{}
 @code{"done" | "running" | "connected" | "error" | "exit"}
@@ -29207,13 +29207,13 @@ depending on the needs---this is still in development).
 @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
 
 @item @var{console-stream-output} @expansion{}
-@code{"~" @var{c-string}}
+@code{"~" @var{c-string}} @var{nl}
 
 @item @var{target-stream-output} @expansion{}
-@code{"@@" @var{c-string}}
+@code{"@@" @var{c-string}} @var{nl}
 
 @item @var{log-stream-output} @expansion{}
-@code{"&" @var{c-string}}
+@code{"&" @var{c-string}} @var{nl}
 
 @item @var{nl} @expansion{}
 @code{CR | CR-LF}

Re: [RFC, doc] fix document error on the grammar of GDB/MI output format syntax

[asmwarrior]

On 2013-12-22 16:09, Joel Brobecker wrote:
>> The change log could be: Fix syntax description error about GDB/MI "out-of-band-record", there should be a "new line" in end.
>>
>> Thanks.
>>
>> Yuanhui Zhang
> I may have given you bad advice when we discussed this on gdb@.
> Looking at the patch, I see you're repeating the "nl", which
> was what I thought we could avoid. But now that we're trying to
> implement the suggestion, and re-reading the grammar, it might
> make better logical sense to group the marker used for a given
> output report (Eg: "*" or "=") and the associated nl in the same
> rule.
>
> Concretely, this is the patch I would suggest instead (you'll notice
> that I removed one such "nl") to move it elsewhere.  I think it's an
> extension of what you originally suggested?
Yes.
> Sorry about flip-flopping on you like that...
Never mind, thanks for your help.

Looking at your patch.
> -@code{[ @var{token} ] "+" @var{async-output}}
> +@code{[ @var{token} ] "+" @var{async-output}} @var{nl}
Is it OK to put the @var{nl} inside the @code{}?

Because I see some (removed) code in your patch:
> -@code{@var{async-class} ( "," @var{result} )* @var{nl}}
I'm not familiar with the Texinfo grammar.

Thanks.

Yuanhui Zhang

Re: [RFC, doc] fix document error on the grammar of GDB/MI output format syntax

[Eli Zaretskii]

> Date: Sun, 22 Dec 2013 19:31:55 +0800
> From: asmwarrior <asmwarrior@gmail.com>
> CC: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> 
> Looking at your patch.
> > -@code{[ @var{token} ] "+" @var{async-output}}
> > +@code{[ @var{token} ] "+" @var{async-output}} @var{nl}
> Is it OK to put the @var{nl} inside the @code{}?

Yes, definitely.

Re: [RFC, doc] fix document error on the grammar of GDB/MI output format syntax

[Joel Brobecker]

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

> Looking at your patch.
> > -@code{[ @var{token} ] "+" @var{async-output}}
> > +@code{[ @var{token} ] "+" @var{async-output}} @var{nl}
> Is it OK to put the @var{nl} inside the @code{}?

OK, thank you and Eli for pointing this out and confirming it.
Attached is the updated patch.

> Because I see some (removed) code in your patch:
> > -@code{@var{async-class} ( "," @var{result} )* @var{nl}}
> I'm not familiar with the Texinfo grammar.

I won't say that I am extremely comfortable with it, yet,
but I'm slowly getting there...

Basically, the "nl" has been moved to the varous rules that
use this rule (exec-async-output, status-async-output and
notify-async-output). The idea is, as hinted in the patch's
rev log, to keep the special symbol indicating the type of
output, and the nl, within the same rule.

gdb/doc/ChangeLog:

        (from Yao Qi  <yao@codesourcery.com>)
        (from Joel Brobecker  <brobecker@adacore.com>)
        * gdb.texinfo (GDB/MI Output Syntax): Add some missing "nl"
        markers.  Remove one that was misplaced.

OK to apply?

-- 
Joel

[-- Attachment #2: 0001-Small-fixes-to-the-GDB-MI-Output-Syntax-grammar.patch --]
[-- Type: text/x-diff, Size: 2244 bytes --]

From a838547bbecd611cedd059911d95c6790871d63e Mon Sep 17 00:00:00 2001
From: Joel Brobecker <brobecker@adacore.com>
Date: Mon, 23 Dec 2013 04:25:14 +0400
Subject: [PATCH] Small fixes to the GDB/MI Output Syntax grammar.

This patch fixes the grammar, and tries to do it in a way that makes
the logic behind the current implementation a little clearer.

gdb/doc/ChangeLog:

        (from Yao Qi  <yao@codesourcery.com>)
        (from Joel Brobecker  <brobecker@adacore.com>)
        * gdb.texinfo (GDB/MI Output Syntax): Add some missing "nl"
        markers.  Remove one that was misplaced.
---
 gdb/doc/gdb.texinfo | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b7551c2..f852c53 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -29166,16 +29166,16 @@ corresponding output for that command will also be prefixed by that same
 @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
 
 @item @var{exec-async-output} @expansion{}
-@code{[ @var{token} ] "*" @var{async-output}}
+@code{[ @var{token} ] "*" @var{async-output nl}}
 
 @item @var{status-async-output} @expansion{}
-@code{[ @var{token} ] "+" @var{async-output}}
+@code{[ @var{token} ] "+" @var{async-output nl}}
 
 @item @var{notify-async-output} @expansion{}
-@code{[ @var{token} ] "=" @var{async-output}}
+@code{[ @var{token} ] "=" @var{async-output nl}}
 
 @item @var{async-output} @expansion{}
-@code{@var{async-class} ( "," @var{result} )* @var{nl}}
+@code{@var{async-class} ( "," @var{result} )*}
 
 @item @var{result-class} @expansion{}
 @code{"done" | "running" | "connected" | "error" | "exit"}
@@ -29207,13 +29207,13 @@ depending on the needs---this is still in development).
 @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
 
 @item @var{console-stream-output} @expansion{}
-@code{"~" @var{c-string}}
+@code{"~" @var{c-string nl}}
 
 @item @var{target-stream-output} @expansion{}
-@code{"@@" @var{c-string}}
+@code{"@@" @var{c-string nl}}
 
 @item @var{log-stream-output} @expansion{}
-@code{"&" @var{c-string}}
+@code{"&" @var{c-string nl}}
 
 @item @var{nl} @expansion{}
 @code{CR | CR-LF}
-- 
1.8.3.2

Re: [RFC, doc] fix document error on the grammar of GDB/MI output format syntax

[asmwarrior]

On 2013-12-23 8:41, Joel Brobecker wrote:
>> Looking at your patch.
>>> -@code{[ @var{token} ] "+" @var{async-output}}
>>> +@code{[ @var{token} ] "+" @var{async-output}} @var{nl}
>> Is it OK to put the @var{nl} inside the @code{}?
> 
> OK, thank you and Eli for pointing this out and confirming it.
> Attached is the updated patch.
> 
>> Because I see some (removed) code in your patch:
>>> -@code{@var{async-class} ( "," @var{result} )* @var{nl}}
>> I'm not familiar with the Texinfo grammar.
> 
> I won't say that I am extremely comfortable with it, yet,
> but I'm slowly getting there...
> 
> Basically, the "nl" has been moved to the varous rules that
> use this rule (exec-async-output, status-async-output and
> notify-async-output). The idea is, as hinted in the patch's
> rev log, to keep the special symbol indicating the type of
> output, and the nl, within the same rule.
> 
> gdb/doc/ChangeLog:
> 
>         (from Yao Qi  <yao@codesourcery.com>)

Mistake here? Wrong person?

>         (from Joel Brobecker  <brobecker@adacore.com>)
>         * gdb.texinfo (GDB/MI Output Syntax): Add some missing "nl"
>         markers.  Remove one that was misplaced.
> 
> OK to apply?
> 
I'm OK.

Yuanhui Zhang

Re: [RFC, doc] fix document error on the grammar of GDB/MI output format syntax

[Joel Brobecker]

> > gdb/doc/ChangeLog:
> > 
> >         (from Yao Qi  <yao@codesourcery.com>)
> 
> Mistake here? Wrong person?

This is very embarrassing, I'm sorry. It's a copy/paste error, and
my only excuse is that it is only 5:30am where I am, and I have
already been up for a couple of hours. Sorry!

Fixed in my commit thusly:

gdb/doc/ChangeLog:

        (from Yuanhui Zhang  <asmwarrior@gmail.com>)
        (from Joel Brobecker  <brobecker@adacore.com>)
        * gdb.texinfo (GDB/MI Output Syntax): Add some missing "nl"
        markers.  Remove one that was misplaced.

-- 
Joel

Re: [RFC, doc] fix document error on the grammar of GDB/MI output format syntax

[asmwarrior]

On 2013-12-23 9:29, Joel Brobecker wrote:
>>> gdb/doc/ChangeLog:
>>>
>>>         (from Yao Qi  <yao@codesourcery.com>)
>> Mistake here? Wrong person?
> This is very embarrassing, I'm sorry. It's a copy/paste error, and
> my only excuse is that it is only 5:30am where I am, and I have
> already been up for a couple of hours. Sorry!
>
> Fixed in my commit thusly:
>
> gdb/doc/ChangeLog:
>
>         (from Yuanhui Zhang  <asmwarrior@gmail.com>)
>         (from Joel Brobecker  <brobecker@adacore.com>)
>         * gdb.texinfo (GDB/MI Output Syntax): Add some missing "nl"
>         markers.  Remove one that was misplaced.
>
Hi, Joel, never mind, thanks. You are hardworking.

Yuanhui Zhang

[pushed] Re: [RFC, doc] fix document error on the grammar of GDB/MI output format syntax

[Joel Brobecker]

Hello,

> gdb/doc/ChangeLog:
> 
>         (from Yao Qi  <yao@codesourcery.com>)
>         (from Joel Brobecker  <brobecker@adacore.com>)
>         * gdb.texinfo (GDB/MI Output Syntax): Add some missing "nl"
>         markers.  Remove one that was misplaced.

Just to confirm that this patch is now in...

-- 
Joel