Re: [PATCH 40/40] Document breakpoints / linespec & co improvements (manual + NEWS)

Pedro Alves
2017-06-21T19:01:39Z

On 06/21/2017 07:26 PM, Eli Zaretskii wrote:
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <palves@redhat.com>
>> Date: Wed, 21 Jun 2017 14:32:54 +0100
>>
>>> Also, I think @kbd is more appropriate here than @code, since you mean
>>> commands the user will type, not just command names.
>>
>> I was addressing this comment, and found myself a bit confused
>> on the distinction between kbd vs code, and what you mean by
>> "commands the user will type, not just command names". Here I'm
>> referring to how the commands with those names behave, not explicitly
>> discussing typing. E.g., the commands behave the same way
>> when found in a script too. Doesn't that suggest @code instead?
>
> Not IMO.
>
> We use @code for names of individual commands, like @code{help} or
> @code{run}. When we need to show a full command line, it is better to
> use @kbd because it is the markup suitable for commands that users
> type. I don't think it matters much whether they type it at GDB's
> prompt or into a script.
>
> In a nutshell, when I see a string with embedded whitespace marked up
> in @code, I raise a brow ;-)
>
> (And yes, I know that we use @code{set FOO} a lot. That is IMO an
> exception, since the "set" command alone makes very little sense in
> GDB.)

OK, I think I get it. In this case, I'm saying
"break B::func", which is an example of an invocation of the
command (I'm passing in a specific function name). Maybe
that's another way to put it -- when talking about invocations
of commands, use @kbd. A bit like "type" vs "value".

>> What specifically confused me was this example
>> in that page that uses @code for a command name not unlike one of GDB's:
>>
>> ~~~
>> To give the @code{logout} command,
>> type the characters @kbd{l o g o u t @key{RET}}.
>> ~~~
>
> Why is that confusing? This text specifically makes a point of
> differentiating between a command's name and the way it is typed at
> the keyboard. It's a rare case, but it does happen.

The confusion was that I was seeing the cases in my patch
like the @code{logout} case here. I looked for @kbd instances
in gdb.texinfo, and saw many preceded by type/typing, etc.,
that's why I thought that we'd only use kbd in those cases.
I see now that there are more cases that don't
say "type" explicitly.

>> We seemingly use @code throughout in GDB's manual to refer to
>> command names, which adds to my confusion. They may all be
>> incorrect, and I'm not trying to justify adding more wrong usages
>> at all. I'd just like to understand better the distinction you have
>> in mind, so I can follow it consistently too.
>
> I hope I explained at least some of that.

Thanks, that was sufficient, I think.

I'm merging this on top of the patch that I sent. The last
hunk fixes a pre-existing case around the text that I'm fixing.

From ff6dfe14de6f207dfe6d227749b7145ad7e95d6f Mon Sep 17 00:00:00 2001
From: Pedro Alves <palves@redhat.com>
Date: Wed, 21 Jun 2017 19:41:43 +0100
Subject: [PATCH] kbd

---
gdb/doc/gdb.texinfo | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index eff1f55..1db8690 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -7867,8 +7867,8 @@ named @var{function} ignoring missing leading specifiers (namespaces
and classes).

For example, assuming a program with symbols named @code{A::B::func}
-and @code{B::func}, both commands @w{@code{break func}} and
-@w{@code{break B::func}} set a breakpoint on both symbols. To
+and @code{B::func}, both commands @w{@kbd{break func}} and
+@w{@kbd{break B::func}} set a breakpoint on both symbols. To
override this, you can use the explicit location option
@code{-qualified}. @xref{Explicit Locations}.

@@ -7941,16 +7941,16 @@ named @var{function} ignoring missing leading specifiers (namespaces
and classes).

For example, assuming a program with symbols named @code{A::B::func}
-and @code{B::func}, both commands @code{break -function func} and
-@code{break -function B::func} set a breakpoint on both symbols.
+and @code{B::func}, both commands @w{@kbd{break -function func}} and
+@w{@kdb{break -function B::func}} set a breakpoint on both symbols.

@item -qualified @var{function}
Like @code{-function}, but the value specifies a fully qualified name
of a function.

For example, assuming a C@t{++} program with symbols named
-@code{A::B::func} and @code{B::func}, the @code{break -qualified
-B::func} command sets a breakpoint on @code{B::func}, only.
+@code{A::B::func} and @code{B::func}, the @w{@kbd{break -qualified
+B::func}} command sets a breakpoint on @code{B::func}, only.

@item -label @var{label}
The value specifies the name of a label. When the function
@@ -7965,7 +7965,7 @@ relative to the current line.
@end table

Explicit location options may be abbreviated by omitting any non-unique
-trailing characters from the option name, e.g., @code{break -s main.c -li 3}.
+trailing characters from the option name, e.g., @w{@kdb{break -s main.c -li 3}}.

@node Address Locations
@subsection Address Locations
--
2.5.5