RFA: update 'target remote' description

RFA: update 'target remote' description

[Jim Blandy]

src/gdb/doc/ChangeLog:
2006-03-07  Jim Blandy  <jimb@red-bean.com>

	* gdb.texinfo (Target Commands): Update text describing how to
	specify a target.  Refer to the detailed section on remote
	debugging, not the brief mention.

Index: src/gdb/doc/gdb.texinfo
===================================================================
--- src.orig/gdb/doc/gdb.texinfo
+++ src/gdb/doc/gdb.texinfo
@@ -11906,14 +11906,24 @@ An executable file.  @samp{target exec @
 A core dump file.  @samp{target core @var{filename}} is the same as
 @samp{core-file @var{filename}}.
 
-@item target remote @var{dev}
+@item target remote @var{medium}
+@cindex @code{target remote}
 @cindex remote target
-Remote serial target in GDB-specific protocol.  The argument @var{dev}
-specifies what serial device to use for the connection (e.g.@:
-@file{/dev/ttya}). @xref{Remote, ,Remote debugging}.  @code{target remote}
-supports the @code{load} command.  This is only useful if you have
-some other way of getting the stub to the target system, and you can put
-it somewhere in memory where it won't get clobbered by the download.
+A remote system connected to @value{GDBN} via a serial line or network
+connection.  This command tells @value{GDBN} to use its own remote
+protocol over @var{medium} for debugging.  @xref{Remote Debugging}.
+
+For example, if you have a board connected to @file{/dev/ttya} on the
+machine running @value{GDBN}, you could say:
+
+@smallexample
+target remote /dev/ttya
+@end smallexample
+
+@code{target remote} supports the @code{load} command.  This is only
+useful if you have some other way of getting the stub to the target
+system, and you can put it somewhere in memory where it won't get
+clobbered by the download.
 
 @item target sim
 @cindex built-in simulator target

Re: RFA: update 'target remote' description

[Eli Zaretskii]

> From: Jim Blandy <jimb@codesourcery.com>
> Date: Tue, 07 Mar 2006 14:27:45 -0800
> 
> 
> src/gdb/doc/ChangeLog:
> 2006-03-07  Jim Blandy  <jimb@red-bean.com>
> 
> 	* gdb.texinfo (Target Commands): Update text describing how to
> 	specify a target.  Refer to the detailed section on remote
> 	debugging, not the brief mention.

This is approved, but:

> +@item target remote @var{medium}
> +@cindex @code{target remote}
>  @cindex remote target

Please remove this cindex entry.  You already added such an entry
where the detailed description of this command is given; having
another one here is redundant, and even harmful, since this section
doesn't really explain about the command.

> +@code{target remote} supports the @code{load} command.  This is only
> +useful if you have some other way of getting the stub to the target
> +system, and you can put it somewhere in memory where it won't get
> +clobbered by the download.

I'm guessing that this paragraph might be important in some situation
(which one, btw?), otherwise you wouldn't be adding it.  So perhaps an
index entry related to that situation would in order here.  What
phrases would a person who looks for this information have in mind?

Thanks.

Re: RFA: update 'target remote' description

[Jim Blandy]

On 3/8/06, Eli Zaretskii <eliz@gnu.org> wrote:
> > From: Jim Blandy <jimb@codesourcery.com>
> > Date: Tue, 07 Mar 2006 14:27:45 -0800
> >
> >
> > src/gdb/doc/ChangeLog:
> > 2006-03-07  Jim Blandy  <jimb@red-bean.com>
> >
> >       * gdb.texinfo (Target Commands): Update text describing how to
> >       specify a target.  Refer to the detailed section on remote
> >       debugging, not the brief mention.
>
> This is approved, but:
>
> > +@item target remote @var{medium}
> > +@cindex @code{target remote}
> >  @cindex remote target
>
> Please remove this cindex entry.  You already added such an entry
> where the detailed description of this command is given; having
> another one here is redundant, and even harmful, since this section
> doesn't really explain about the command.

Okay.

> > +@code{target remote} supports the @code{load} command.  This is only
> > +useful if you have some other way of getting the stub to the target
> > +system, and you can put it somewhere in memory where it won't get
> > +clobbered by the download.
>
> I'm guessing that this paragraph might be important in some situation
> (which one, btw?), otherwise you wouldn't be adding it.  So perhaps an
> index entry related to that situation would in order here.  What
> phrases would a person who looks for this information have in mind?

Actually, I didn't add that: it's present in the current text.  I
don't think it belongs there; I was simply avoiding moving it.

Ideally, I think the entry for 'target remote' in @section Commands
for managing targets should just be a brief reference to @chapter
Debugging remote programs, and @section Remote Debugging should be
removed, with all its content moved to @chapter Debugging remote
programs.

But I'd like to keep problems separate here.  May I commit this
change, with the @cindex @code{target remote} omitted?

Re: RFA: update 'target remote' description

[Eli Zaretskii]

> Date: Thu, 9 Mar 2006 10:05:31 -0800
> From: "Jim Blandy" <jimb@red-bean.com>
> Cc: "Jim Blandy" <jimb@codesourcery.com>, gdb-patches@sourceware.org
> 
> May I commit this change, with the @cindex @code{target remote}
> omitted?

Yes.

Re: RFA: update 'target remote' description

[Jim Blandy]

On 3/9/06, Eli Zaretskii <eliz@gnu.org> wrote:
> > Date: Thu, 9 Mar 2006 10:05:31 -0800
> > From: "Jim Blandy" <jimb@red-bean.com>
> > Cc: "Jim Blandy" <jimb@codesourcery.com>, gdb-patches@sourceware.org
> >
> > May I commit this change, with the @cindex @code{target remote}
> > omitted?
>
> Yes.

Committed, thanks.