From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 96552 invoked by alias); 21 Jun 2017 18:26:54 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 96436 invoked by uid 89); 21 Jun 2017 18:26:53 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.1 required=5.0 tests=AWL,BAYES_00,SPF_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy=brow, Hx-languages-length:2514, rare X-HELO: eggs.gnu.org Received: from eggs.gnu.org (HELO eggs.gnu.org) (208.118.235.92) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 21 Jun 2017 18:26:51 +0000 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dNkKy-00085b-A7 for gdb-patches@sourceware.org; Wed, 21 Jun 2017 14:26:48 -0400 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:60716) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dNkKy-00085T-6q; Wed, 21 Jun 2017 14:26:44 -0400 Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:3172 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dNkKw-0008NE-7u; Wed, 21 Jun 2017 14:26:43 -0400 Date: Wed, 21 Jun 2017 18:26:00 -0000 Message-Id: <83shiturhr.fsf@gnu.org> From: Eli Zaretskii To: Pedro Alves CC: gdb-patches@sourceware.org In-reply-to: (message from Pedro Alves on Wed, 21 Jun 2017 14:32:54 +0100) Subject: Re: [PATCH 40/40] Document breakpoints / linespec & co improvements (manual + NEWS) Reply-to: Eli Zaretskii References: <1496406158-12663-1-git-send-email-palves@redhat.com> <1496406158-12663-41-git-send-email-palves@redhat.com> <83a85qczmo.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-IsSubscribed: yes X-SW-Source: 2017-06/txt/msg00599.txt.bz2 > Cc: gdb-patches@sourceware.org > From: Pedro Alves > 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.