[3/3] Target remote mode fork and exec docs

  Hi Eli,
Thanks for the review.

On 11/7/2015 12:18 AM, Eli Zaretskii wrote:
>> From: Don Breazeal <donb@codesourcery.com>
>> Date: Fri, 6 Nov 2015 15:56:28 -0800
>>
>> diff --git a/gdb/NEWS b/gdb/NEWS
>> index b2b1e99..166a6ca 100644
>> --- a/gdb/NEWS
>> +++ b/gdb/NEWS
>> @@ -87,6 +87,14 @@ set remote exec-event-feature-packet
>>  show remote exec-event-feature-packet
>>    Set/show the use of the remote exec event feature.
>>  
>> +* Target remote mode fork and exec events
>> +
>> +  ** GDB now has support for fork and exec events on target remote mode
>> +     Linux targets.  For such targets with Linux kernels 2.5.46 and later,
>> +     this enables follow-fork-mode, detach-on-fork and fork and exec
>> +     catchpoints.  Note that follow-exec-mode is not supported, because
>> +     target remote mode does not support the 'run' command.
>> +
>>  *** Changes in GDB 7.10
> 
> This part is OK.
> 
>> -@value{GDBN} needs an unstripped copy of your program to access symbol
>> -and debugging information.  Some remote targets (@pxref{qXfer
>> -executable filename read}, and @pxref{Host I/O Packets}) allow
>> -@value{GDBN} to access program files over the same connection used to
>> -communicate with @value{GDBN}.  With such a target, if the remote
>> -program is unstripped, the only command you need is @code{target
>> -remote}.  Otherwise, start up @value{GDBN} using the name of the local
>> +@value{GDBN} supports two types of remote connections, @kbd{target remote}
>> +mode and @kbd{target extended-remote} mode.  There are several major
>> +differences between the two.  In @kbd{target extended-remote} mode, GDB
>                                                                        ^^^
> @value{GDBN}
> 
>> +stays connected to @code{gdbserver} after the debugged program exits or you
>> +detach from it, and @code{gdbserver} provides support for the @code{run}
>> +and @code{attach} commands.
> 
> Saying "several major differences" and then neither describing them
> nor providing a reference (not even just "described below") will leave
> the reader confused, I think.  How about a short summary of the
> differences, e.g. as an itemized list, here?
> 
> Also, does the sentence that follow (the last one in the above
> excerpt) need to be here?  It reads strange, especially since it
> doesn't seem like it belongs to the aforementioned differences.  Maybe
> you could reword it so it did contrast the two modes.
> 
> Alternatively, perhaps the following subsections are better rearranged
> as extended descriptions of each of the differences, e.g. using @table.
> Right now, they read somewhat confusingly, because the description
> jumps between the two modes without providing any intermediate summary
> for the reader, and thus it is easy to become confused as to what mode
> and what difference you are describing.  Some better organization of
> the same material could help the reader organize their thoughts and
> come out with a better understanding of the differences.

I went with the latter suggestion.  I hope my interpretation of this
doesn't violate any doc conventions.  In the previous version I had
tried to leave some paragraphs unmodified, just reorganizing where
they were.  I've been more liberal in my changes in this version.

> 
> Last, but not least: please consider adding @cindex entries to each of
> the subsections, with text that describes the main subject of each
> subsection.  In many cases, just the down-cased name of the section is
> a good starting point.  This will help the readers find the subsection
> quickly using the Info index-searching commands, which is important
> for using the manual as a reference.

I added a number of these.

> 
>> +@item
>> +Finally, connect to your target.  For TCP connections, you must start up
>> +@code{gdbserver} prior to using the @kbd{target remote} or
>> +@kbd{target extended-remote} command.  Otherwise you may get an error
>> +whose text depends on the host system, but which usually looks something
>> +like @samp{Connection refused}.  Don't use the @code{load} command in
>> +@value{GDBN} when using @code{gdbserver}, since the program is already on
>> +the target.
> 
> There's some inconsistency in your usage of @code and @kbd markup for
> commands.  In general, the correct markup is @kbd when the context is
> about commands typed by the user, and @code otherwise.  (The GDB
> manual almost never uses @kbd, for historical reasons, btw.)  You have
> changed some of the @code to @kbd regardless of context, or so it
> seems.  But in the above passage, you use @code as well, so I'm unsure
> what is your rule for selecting one or the other.

I misunderstood the convention here.  Thanks for clarifying.  I think I
have more-or-less restored things.  Basically, as I understand it, the rule
is: use @kbd where the sentence is saying "type @kbd{foo}" or "use
@kbd{foo}", but use @code if it is just referring to it, like "in the
case of the @code{foo} command".

> 
>>  @item target remote @var{serial-device}
>> -@cindex serial line, @code{target remote}
>> +@item target extended-remote @var{serial-device}
>    ^^^^^
> Should be @itemx.

I fixed all of these.

>> -@subsection Running @code{gdbserver}
>> +@subsection Running gdbserver
> 
> Not sure why you removed the markup from "gdbserver" here.

My ignorance about how to implement cross-references.  I've figured out
the right thing to do, and restored the markup.

Let me know what you think about this version.
thanks
--Don
-----------------------
This patch implements documentation updates for target remote mode
fork and exec events.  A summary of the rationale for the changes
made here:

* Types of Remote Connections -- explain that the two protocols exist,
and describe the differences between the two.

* Host and Target Files -- collect paragraphs dealing with how to locate
symbol files from original sections "Connecting to a remote target" and
"Using the gdbserver program | Connecting to gdbserver".

* Remote connection commands -- used to be the bulk of "Connecting to a
remote target".  Added "target extended-remote" commands and information.

Thanks,
--Don

gdb/
2015-11-11  Don Breazeal  <donb@sourceware.org>

	* NEWS: Announce fork and exec event support for target remote.

gdb/doc/
2015-11-11  Don Breazeal  <donb@sourceware.org>

	* gdb.texinfo (Forks): Correct Linux kernel version where
	fork and exec events are supported, add notes about support
	of these events in target remote mode.
	(Connecting): Reorganize and clarify distinctions between
	target remote, extended-remote, and multiprocess.
	Reorganize related text from separate sections into new
	sections.
	(Server): Note effects of target extended-remote mode.
	Delete section on Multi-Process Mode for gdbserver.
	Move some text to "Connecting" node.

---
 gdb/NEWS            |   8 ++
 gdb/doc/gdb.texinfo | 272 +++++++++++++++++++++++++++++++++++++---------------
 2 files changed, 202 insertions(+), 78 deletions(-)

[3/3] Target remote mode fork and exec docs

Commit Message

Comments

Patch