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

[Pedro Alves <palves at redhat dot com>]

Hi Eli,

On 06/02/2017 02:01 PM, Eli Zaretskii wrote:
>> From: Pedro Alves <palves@redhat.com>
>> > Date: Fri,  2 Jun 2017 13:22:38 +0100
>> > 
>> > +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.
> The 2 commands are long and include whitespace, so I'd suggest
> enclosing each one in @w{..}, to avoid a line break in the middle of a
> command.
> 
> 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?
If not, what would be an example of "just command names", ones that
the user will NOT type?  I.e., when should we use @code instead?

>From here: 
 https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040kbd.html
I got the impression that a use of @kbd would be when describing
the completion machinery.  Or then the text clearly says something around
"type @kbd{....}".  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}}.
~~~

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.

Thanks,
Pedro Alves