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

[Eli Zaretskii <eliz at gnu dot org>]

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

> >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{....}".

My rule is "when talking about something that users might/will type,
explicitly or implicitly".  It's admittedly a fine line sometimes,
which is why I use the "whitespace" heuristics (which is also
imperfect).

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

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