This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH 3/3] Target remote mode fork and exec docs
- From: Eli Zaretskii <eliz at gnu dot org>
- To: Don Breazeal <donb at codesourcery dot com>
- Cc: gdb-patches at sourceware dot org
- Date: Thu, 12 Nov 2015 18:48:18 +0200
- Subject: Re: [PATCH 3/3] Target remote mode fork and exec docs
- Authentication-results: sourceware.org; auth=none
- References: <1447290000-31393-1-git-send-email-donb at codesourcery dot com> <1447290000-31393-2-git-send-email-donb at codesourcery dot com>
- Reply-to: Eli Zaretskii <eliz at gnu dot org>
> From: Don Breazeal <donb@codesourcery.com>
> Date: Wed, 11 Nov 2015 17:00:00 -0800
>
> >> +@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".
Yes, that's it.
> +@table @asis
> +
> +@cindex remote debugging, detach and program exit
> +@item Result of detach or program exit
> +
> +@strong{target remote mode:} When the debugged program exits or you
> +detach from it, @value{GDBN} disconnects from the target. When using
> +@code{gdbserver}, @code{gdbserver} will exit.
> +
> +@strong{target extended-remote mode:} When the debugged program exits or
This is OK, but the fact that "target extended-remote mode:" part that
begins a sentence doesn't start with a capital letter looks wrong.
How about starting with @strong{With target extended-remote mode:}
instead?
> +@item The @code{run} command
> +@strong{target remote mode:} The @code{run} command is not supported.
Please be consistent regarding whether or not you leave an empty line
after the @item line. (My suggestion is not to leave such a line in a
@table.)
> If you're using a serial line, you may want to give @value{GDBN} the
> @samp{--baud} option, or use the @code{set serial baud} command
> (@pxref{Remote Configuration, set serial baud}) before the
> -@code{target} command.
> +@kbd{target} command.
Here you show 2 commands in the same sentence, one with @code, the
other with @kbd. I think both should use @code.
> +In @code{target extended-remote} mode, you can also attach using the
> +@value{GDBN} attach command
> +(@pxref{Types of Remote Connections: Attaching}).
I don't understand this @pxref -- there's no such node or anchor in
the text. Does this work for you? (Also, using a colon in
cross-reference or node names is a bad idea, as that confuses Info
readers.)
The patch is approved, assuming the above minor issues are fixed.
Thanks.