Re: [rfc/rfa] [3/4] SPU enhancements: gdbserver support

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Sat, 2 Jun 2007 21:33:29 +0200 (CEST)
> From: "Ulrich Weigand" <uweigand@de.ibm.com>
> Cc: eliz@gnu.org, drow@false.org
> 
> Eli, are the doc changes OK?

Yes, but see some comments below.

> +@item qXfer:spu:read:@var{annex}:@var{offset},@var{length}
> +@anchor{qXfer spu read}
> +@cindex spufs
> +@cindex SPU 

You already added a "@cindex SPU" entry in your previous patch.  This
is the second index entry with exactly the same name, which is not a
very good idea: a reader looking at the index will not know which one
to choose.  It is better to use an entry qualified by its context, for
example:

  @cindex SPU, read @code{spufs} files

> +Read contents of an @code{spufs} file on the target system.  The
> +annex specifies which file to read; it must be of the form 
> +@var{id}/@var{name}, where @var{id} specifies an SPU context ID

Since you are talking about a file, you should use the @file markup:

  +@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID

> -@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
> +@item qXfer:@var{object}:write:@var{annex}:@var{offset},@var{length}:@var{data}@dots{}

Won't this change break backward compatibility?

> +Write @var{length} bytes of uninterpreted data into the target's
> +special data area identified by the keyword @var{object}, starting

What do you mean by ``keyword''?  Isn't @var{object} a _name_ of an
object or its symbol?

> +at @var{offset} bytes into the data.  @samp{@var{data}@dots{}} is
                                         ^^^^^^^^^^^^^^^^^^^^^^
Why use @samp here?  Does it do anything useful?

> +the binary-encoded data (@pxref{Binary Data}) to be written.  The
> +content and encoding of @var{annex} is specific to the object; it can
                                       ^^^^^^^^^^^^^^^^^^^^^^^^^
Better say "... is specific to @var{object}".

> +@table @samp
> +@item qXfer:@var{spu}:write:@var{annex}:@var{offset},@var{length}:@var{data}@dots{}
> +@anchor{qXfer spu write}
> +@cindex spufs
> +@cindex SPU

See above about "@cindex SPU".

> +be of the form @var{id}/@var{name}, where @var{id} specifies an SPU context ID
                  ^^^^^^^^^^^^^^^^^^^
Likewise, please use @file.