From patchwork Wed Jun 21 19:01:34 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pedro Alves X-Patchwork-Id: 21181 Received: (qmail 12683 invoked by alias); 21 Jun 2017 19:01:39 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 12626 invoked by uid 89); 21 Jun 2017 19:01:39 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-26.9 required=5.0 tests=BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, SPF_HELO_PASS, T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy=Hx-languages-length:5160 X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 21 Jun 2017 19:01:37 +0000 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 0C0FC61B91; Wed, 21 Jun 2017 19:01:36 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 0C0FC61B91 Authentication-Results: ext-mx10.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx10.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=palves@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com 0C0FC61B91 Received: from [127.0.0.1] (ovpn04.gateway.prod.ext.ams2.redhat.com [10.39.146.4]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3D4B4171A1; Wed, 21 Jun 2017 19:01:35 +0000 (UTC) Subject: Re: [PATCH 40/40] Document breakpoints / linespec & co improvements (manual + NEWS) 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> <83shiturhr.fsf@gnu.org> Cc: gdb-patches@sourceware.org From: Pedro Alves Message-ID: <68def636-5333-0718-dedd-dad3ef7b2d35@redhat.com> Date: Wed, 21 Jun 2017 20:01:34 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.4.0 MIME-Version: 1.0 In-Reply-To: <83shiturhr.fsf@gnu.org> On 06/21/2017 07:26 PM, Eli Zaretskii wrote: >> 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.) 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 Date: Wed, 21 Jun 2017 19:41:43 +0100 Subject: [PATCH] kbd --- gdb/doc/gdb.texinfo | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index eff1f55..1db8690 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -7867,8 +7867,8 @@ named @var{function} ignoring missing leading specifiers (namespaces and classes). For example, assuming a program with symbols named @code{A::B::func} -and @code{B::func}, both commands @w{@code{break func}} and -@w{@code{break B::func}} set a breakpoint on both symbols. To +and @code{B::func}, both commands @w{@kbd{break func}} and +@w{@kbd{break B::func}} set a breakpoint on both symbols. To override this, you can use the explicit location option @code{-qualified}. @xref{Explicit Locations}. @@ -7941,16 +7941,16 @@ named @var{function} ignoring missing leading specifiers (namespaces and classes). 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. +and @code{B::func}, both commands @w{@kbd{break -function func}} and +@w{@kdb{break -function B::func}} set a breakpoint on both symbols. @item -qualified @var{function} Like @code{-function}, but the value specifies a fully qualified name of a function. For example, assuming a C@t{++} program with symbols named -@code{A::B::func} and @code{B::func}, the @code{break -qualified -B::func} command sets a breakpoint on @code{B::func}, only. +@code{A::B::func} and @code{B::func}, the @w{@kbd{break -qualified +B::func}} command sets a breakpoint on @code{B::func}, only. @item -label @var{label} The value specifies the name of a label. When the function @@ -7965,7 +7965,7 @@ relative to the current line. @end table Explicit location options may be abbreviated by omitting any non-unique -trailing characters from the option name, e.g., @code{break -s main.c -li 3}. +trailing characters from the option name, e.g., @w{@kdb{break -s main.c -li 3}}. @node Address Locations @subsection Address Locations