Re: [rfc] Let the remote protocol report the target's arch

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 4 Jan 2007 17:16:22 -0500
> From: Daniel Jacobowitz <drow@false.org>
> 
> When you get a chance, could you look at this?  It's not too urgent; I
> need to work on the next patch in this series, since I've forgotten
> where I was over the last month.
> 
> Original patch is here:
> http://sourceware.org/ml/gdb-patches/2006-12/msg00100.html

Sorry, I've managed to miss the fact that portions of this patch await
my review.  On to it now.

> +Access the target's @dfn{target description}.  @xref{Target Descriptions}.  The

``target's target description''?  Wouldn't this be better:

  Access the @dfn{target description}.

> +annex specifies which XML document to access.  The main description is
> +always loaded from @samp{target.xml}.

Is `target.xml' a literal file name, or is the `target' part something
that will be replaced with a specific target name?  If the former,
please use @file{target.xml}, if the latter, @file{@var{target}.xml}.
If it's not a file at all, I think this text needs to explain what it
is.

Similar problems with the markup of target.xml are elsewhere in the
patch.

> +@node Target Descriptions
> +@appendix Target Descriptions

Please add a suitable @cindex entry here, for those who will look for
this stuff because they remember it's described somewhere in the
manual.

> +Alternatively, you can specify a file to read for the target description.
> +If a file is set, the target will not be queried.
> +
> +@table @code
> +@cindex set tdesc filename
> +@item set tdesc filename @var{path}

I suggest a sentence before @table to explain what is described in
this table.

>                                           If @var{path} is empty,
> +use the target-supplied description.

This sentence is unclear, at least to me: what is this target-supplied
description, and where does one find it?  If it's target.xml, then how
about mentioning it here explicitly?

> +@node Target Description Format
> +@section Target Description Format

Suggest an @cindex entry here as well: someone could be looking for
this format description.

> +@example
> +<target>
> +  <architecture>i386:x86-64</architecture>
> +</target>
> +@end example
> +
> +@noindent
> +This description only says that the target uses the x86-64 architecture.
> +describes a simple target feature set which only contains two
> +registers, named @code{s0} (a 32-bit integer register) and @code{s1}
> +(a 32-bit floating point register).

Something's missing here, before the "describes a simple target" part.

> +The content of the @samp{<architecture>} element is an architecture
> +name, from the same selection accepted by @code{set architecture}

There's no `<architecture>' element in the example that precedes this
text, which is confusing.  You should probably rewrite the example.

> +set tdesc filename
> +show tdesc filename
> +  Read an XML target description from the specified local file instead
> +  of querying the target for its description.

Actually, "set tdesc filename" command doesn't read anything, it just
sets the name of the file from which to read the description.

Anyway, I think NEWS should say explicitly that GDB can now read a
description of remote target's features from an XML file.  Then these
two new commands will make sense to the reader.