[RFA] [doc] thread-created/thread-exited

[RFA] [doc] thread-created/thread-exited

[Vladimir Prus]

This patch documents the thread-create and thread-exited MI notification.
It also fixes the terminology as bit -- the grammar say that out-of-band
record is either async record or stream record, whereas the following docs
first describe stream records and then talk about async records, but call
them out-of-band.

OK?

- Volodya

---
 gdb/doc/gdb.texinfo |   23 ++++++++++++++---------
 1 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 294276c..988eceb 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18113,24 +18113,29 @@ The log stream contains debugging messages being produced by @value{GDBN}'s
 internals.
 @end table
 
-@node GDB/MI Out-of-band Records
-@subsection @sc{gdb/mi} Out-of-band Records
+@node GDB/MI Async Records
+@subsection @sc{gdb/mi} Async Records
 
-@cindex out-of-band records in @sc{gdb/mi}
-@cindex @sc{gdb/mi}, out-of-band records
-@dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
+@cindex async records in @sc{gdb/mi}
+@cindex @sc{gdb/mi}, async records
+@dfn{Async} records are used to notify the @sc{gdb/mi} client of
 additional changes that have occurred.  Those changes can either be a
-consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
+consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of
 target activity (e.g., target stopped).
 
-The following is a preliminary list of possible out-of-band records.
-In particular, the @var{exec-async-output} records.
+The following is the list of possible async records
 
 @table @code
 @item *stopped,reason="@var{reason}"
+The target has stopped.
+@item =thread-created,id="@var{id}"
+@item =thread-exited,id="@var{id}"
+A thread either was created, or has exited. The @var{id} field
+contains the @var{GDBN} identifier of the thread.
 @end table
 
-@var{reason} can be one of the following:
+For the @samp{*stopped} async record, the @var{reason} field can have
+one of the following values:
 
 @table @code
 @item breakpoint-hit
-- 
1.5.3.5

Re: [RFA] [doc] thread-created/thread-exited

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Sat, 26 Apr 2008 21:44:03 +0400
> 
> This patch documents the thread-create and thread-exited MI notification.
> It also fixes the terminology as bit -- the grammar say that out-of-band
> record is either async record or stream record, whereas the following docs
> first describe stream records and then talk about async records, but call
> them out-of-band.
> 
> OK?

Did you actually try to say "make info" after applying these patches?
Because I don't see how it could fly: you've modified the name of a
node, but did not change the corresponding item in the @menu of the
section of which "GDB/MI Out-of-band Records" was a subsection.  That
ought to trigger error messages from makeinfo.

> +The following is the list of possible async records

A colon at the end of this line, please.

>  @table @code
>  @item *stopped,reason="@var{reason}"
> +The target has stopped.
> +@item =thread-created,id="@var{id}"
> +@item =thread-exited,id="@var{id}"
> +A thread either was created, or has exited. The @var{id} field
> +contains the @var{GDBN} identifier of the thread.
>  @end table

Please leave an empty line before an @item line, otherwise it will
look ugly in print.  Also, you cannot have 2 @item lines in a row; all
but the first one must be @itemx, or else the formatting of the table
will come out wrong.  Finally, 2 spaces after a period that ends a
sentence, please.

> +For the @samp{*stopped} async record, the @var{reason} field can have
> +one of the following values:
>  
>  @table @code
>  @item breakpoint-hit

I'd put this right after the @item above that introduced the
`*stopped' record (yes, a table inside a table).  Didactically, it is
better to have related information close together, rather than apart.

Re: [RFA] [doc] thread-created/thread-exited

[Vladimir Prus]

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

Eli Zaretskii wrote:

>> From: Vladimir Prus <vladimir@codesourcery.com>
>> Date: Sat, 26 Apr 2008 21:44:03 +0400
>> 
>> This patch documents the thread-create and thread-exited MI notification.
>> It also fixes the terminology as bit -- the grammar say that out-of-band
>> record is either async record or stream record, whereas the following docs
>> first describe stream records and then talk about async records, but call
>> them out-of-band.
>> 
>> OK?
> 
> Did you actually try to say "make info" after applying these patches?
> Because I don't see how it could fly: you've modified the name of a
> node, but did not change the corresponding item in the @menu of the
> section of which "GDB/MI Out-of-band Records" was a subsection.  That
> ought to trigger error messages from makeinfo.

I did 'make pdf' and it worked. 

>> +The following is the list of possible async records
> 
> A colon at the end of this line, please.
> 
>>  @table @code
>>  @item *stopped,reason="@var{reason}"
>> +The target has stopped.
>> +@item =thread-created,id="@var{id}"
>> +@item =thread-exited,id="@var{id}"
>> +A thread either was created, or has exited. The @var{id} field
>> +contains the @var{GDBN} identifier of the thread.
>>  @end table
> 
> Please leave an empty line before an @item line, otherwise it will
> look ugly in print.  

Hmm, it looks just fine for me. I've added blank lines though.

> Also, you cannot have 2 @item lines in a row; all 
> but the first one must be @itemx, or else the formatting of the table
> will come out wrong.  Finally, 2 spaces after a period that ends a
> sentence, please.
> 
>> +For the @samp{*stopped} async record, the @var{reason} field can have
>> +one of the following values:
>>  
>>  @table @code
>>  @item breakpoint-hit
> 
> I'd put this right after the @item above that introduced the
> `*stopped' record (yes, a table inside a table).  Didactically, it is
> better to have related information close together, rather than apart.

How about this revision?

- Volodya


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: a.diff --]
[-- Type: text/x-diff; name="a.diff", Size: 2096 bytes --]

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 294276c..2ffdc53 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18045,7 +18045,7 @@ follow development on @email{gdb@@sourceware.org} and
 @menu
 * GDB/MI Result Records::
 * GDB/MI Stream Records::
-* GDB/MI Out-of-band Records::
+* GDB/MI Async Records::
 @end menu
 
 @node GDB/MI Result Records
@@ -18113,24 +18113,23 @@ The log stream contains debugging messages being produced by @value{GDBN}'s
 internals.
 @end table
 
-@node GDB/MI Out-of-band Records
-@subsection @sc{gdb/mi} Out-of-band Records
+@node GDB/MI Async Records
+@subsection @sc{gdb/mi} Async Records
 
-@cindex out-of-band records in @sc{gdb/mi}
-@cindex @sc{gdb/mi}, out-of-band records
-@dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
+@cindex async records in @sc{gdb/mi}
+@cindex @sc{gdb/mi}, async records
+@dfn{Async} records are used to notify the @sc{gdb/mi} client of
 additional changes that have occurred.  Those changes can either be a
-consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
+consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of
 target activity (e.g., target stopped).
 
-The following is a preliminary list of possible out-of-band records.
-In particular, the @var{exec-async-output} records.
+The following is the list of possible async records
 
 @table @code
-@item *stopped,reason="@var{reason}"
-@end table
 
-@var{reason} can be one of the following:
+@item *stopped,reason="@var{reason}"
+The target has stopped.  The @var{reason} field can have one of the
+following values:
 
 @table @code
 @item breakpoint-hit
@@ -18160,6 +18159,13 @@ The inferior exited normally.
 A signal was received by the inferior.
 @end table
 
+@item =thread-created,id="@var{id}"
+@itemx =thread-exited,id="@var{id}"
+A thread either was created, or has exited.  The @var{id} field
+contains the @value{GDBN} identifier of the thread.
+@end table
+
+
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Simple Examples

Re: [RFA] [doc] thread-created/thread-exited

[Eli Zaretskii]

> From:  Vladimir Prus <vladimir@codesourcery.com>
> Date:  Sat, 26 Apr 2008 22:56:37 +0400
> 
> > Did you actually try to say "make info" after applying these patches?
> > Because I don't see how it could fly: you've modified the name of a
> > node, but did not change the corresponding item in the @menu of the
> > section of which "GDB/MI Out-of-band Records" was a subsection.  That
> > ought to trigger error messages from makeinfo.
> 
> I did 'make pdf' and it worked. 

Evidently, that's not enough; please always do a "make info" as well.

> +The following is the list of possible async records

Still no colon at the end.

Otherwise, this is fine; thanks.