Re: [rfc] Remote file transfer support

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Mon, 29 Oct 2007 16:30:42 -0400
> From: Daniel Jacobowitz <drow@false.org>
> 
> 2007-10-29  Daniel Jacobowitz  <dan@codesourcery.com>
> 
> 	* gdb.texinfo (Remote Debugging): Add File Transfer section.
> 	(Remote Configuration): Document Host I/O packets.
> 	(GDB/MI): Add GDB/MI File Transfer Commands section.
> 	(Remote Protocol): Add Host I/O Packets section.
> 	(Packets): Add vFile.

I have a few comments for this part.

> +@node File Transfer
> +@section Sending files to a remote system
> +@cindex remote target, file transfer
> +@cindex file transfer

Please add a @cindex entry as follows:

  @cindex sending files to remote systems

> +for targets accessible through other means, e.g.@: GNU/Linux systems
                                                      ^^^^^^^^^
I believe we want to use @sc{gnu}/Linux.

> +@item remote put @var{hostfile} @var{targetfile}
> +Copy @var{hostfile} from the host system (the machine running
> +@value{GDBN}) to the path @var{targetfile} on the target system.

GNU coding conventions frown on using "path" in the sense of a file
name or a fully qualified directory name.  "Path" is reserved for
$PATH and other lists of directories, like the value of $MANPATH etc.

Also, I think it would help to say "file" at least once, to make sure
the reader understands that @var{hostfile} and other similar
parameters are file names:

  Copy file @var{hostfile} from the host system ...

> +Perform a file operation on the target system.  For details,
> +@xref{Host I/O Packets}.

@xref produces "See", with a capital `S', which looks as a typo in the
middle of a sentence.  To avoid this, use @ref as follows:

  For details, see @ref{Host I/O Packets}.

or reverse the order:

  @xref{Host I/O Packets}, for details.

>               The protocol has some common features with the File-I/O
> +protocol, e.g.@: all constants and data structures are encoded in the
> +same way.

I didn't understand this sentence.  Can you explain what does it mean
to say?

>               However, the packets are structured differently, because
> +requests are initiated by @value{GDBN}, and the target's memory is not
> +involved.

This is also unclear.

>                                                                  For
> +operations which return data, @var{attachment} will be provided a
> +binary buffer.

Did you mean "as a binary buffer", perhaps?

> +The data read should be returned as a binary attachment on success,
> +even if zero bytes were read.

Ehm... how do you express a buffer of zero bytes?

> --- gdb/NEWS.orig	2007-10-29 15:20:55.000000000 -0400
> +++ gdb/NEWS	2007-10-29 16:11:11.000000000 -0400

This part is fine with me.

Thanks.