Re: [PATCH 1/1] Integrate GNU poke in GDB

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 10 May 2021 17:10:44 +0200
> From: "Jose E. Marchesi via Gdb-patches" <gdb-patches@sourceware.org>
> 
> This patch integrates GNU poke (http://jemarch.net/poke) in GDB by
> mean of libpoke.  It allows the GDB user to execute Poke code from
> within the debugger with access to the target memory, types and
> values.

Thanks.

> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -10245,6 +10245,7 @@ being passed the type of @var{arg} as the argument.
>  * Caching Target Data::         Data caching for targets
>  * Searching Memory::            Searching memory for a sequence of bytes
>  * Value Sizes::                 Managing memory allocated for values
> +* Poke::                        Poking at data using GNU poke.
                                                            ^^^^
@samp{poke}, please.

> +@c XXX example: saving some memory in a file (opening other IO spaces)

What's this comment about?

> +@node Poke
> +@section Poking at data using GNU poke

Likewise, please use @samp for "poke" in the section name and in the
text (but not the node name).

> +(with big P) that is specifically designed in order to describe the
         ^^^^^
"capital P"

> +certain GDB abstractions (such as symbols and types) visible from the
           ^^^
@value{GDBN}

> +the Poke language in detail. @xref{Top,,, poke, The GNU poke Manual}
> +for more information.                                               ^

Please add a comma there.

> +* The @command{poke} Command::  Executing Poke from @value{GDBN}.
> +* Poking the Target Memory::    Accessing the target's memory from Poke.
> +* @value{GDBN} Types and Poke::         Accessing @value{GDBN} types from Poke.
> +* @value{GDBN} Values and Poke::        Accessing @value{GDBN} values from Poke.
> +@end menu
> +
> +@node The @command{poke} Command
> +@subsection The @command{poke} Command
> +
> +The @command{poke} command allows to execute arbitrary Poke code from
> +the @value{GDBN} prompt.

@command is wrong for GDB commands.  Our convention is to use @code.

> +(@value{GDBP}) type Packet = struct @{ byte magic == 0x4a; byte sz; byte[sz] payload; @}

This line is too long, it will typeset badly in the printed version.
Please break it into two or more lines.

> +This loads a file @dfn{foo.pk} if it is found in the load path:
                     ^^^^
@file, not @dfn (here and elsewhere).

> +To Poke source files containing definitions that conceptually apply to
> +some definite domain, we call them @dfn{pickles}.  For example,

"To Poke ..., we call them "pickles""?  That sounds incorrect English
to me, do you want to rephrase?

> +(@value{GDBP}) spoke string[3] @@ 0x5ff0#B
                  ^^^^^
"spoke"?

> +Note that the fact the current IO space is the GDB target memory
                                                  ^^^
@value{GDBN}

> +If you close the default IO space you can re-open the GDB target space
                                                         ^^^
Likewise.

> +Note how two types are added: the requested @code{struct person} and
> +also @code{int}, since the struct contains a field of that basic C
> +type. Let's take a look to the type definitions:
       ^^
Two spaces between sentences.

> +type struct_person = struct @{int age; offset<uint<64>,B> name @@ 8#B; offset<uint<64>,B> postal_address;@};

This line is too long.

> +If we wanted to add all the types known to GDB to poke, we could so do
                                              ^^^
@value{GDBN}

> +Poke variables are not the same than GDB symbols, and live in a
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"not the same as @value{GDBN} symbols"

> +separated world of their own. However, it is possible to refer to GDB
                               ^^                                    ^^^
Two spaces, and @value{GDBN} again.

> +Since many @value{GDBN} values are pointers, it is possible to access
> +to the address of a value by using the @code{$addr::IDENTIFIER} ^^^^^
   ^^^^^^^^^^^^^^
"access the address", without the "to".