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

  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(-)
  

> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <palves@redhat.com>
> Date: Wed, 21 Jun 2017 20:01:34 +0100
> 
> 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".

Right.

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

This is OK, thanks.