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

Eli Zaretskii
2017-06-21T18:26:54Z

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