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

[Pedro Alves <palves@redhat.com>]

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