Re: [PATCH 3/3] Target remote mode fork and exec docs

[Eli Zaretskii <eliz at gnu dot org>]

> 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.

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.

> +@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.

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

>  @item target remote @code{udp:@var{host}:@var{port}}
> -@cindex @acronym{UDP} port, @code{target remote}
> +@item target extended-remote @code{udp:@var{host}:@var{port}}

Likewise.

>  @item target remote | @var{command}
> -@cindex pipe, @code{target remote} to
> +@item target extended-remote | @var{command}

Likewise.

> -@subsection Running @code{gdbserver}
> +@subsection Running gdbserver

Not sure why you removed the markup from "gdbserver" here.

Thanks.