From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id Iw39Lbn+3mJFehoAWB0awg (envelope-from ) for ; Mon, 25 Jul 2022 16:36:09 -0400 Received: by simark.ca (Postfix, from userid 112) id A77CD1E9EB; Mon, 25 Jul 2022 16:36:09 -0400 (EDT) Authentication-Results: simark.ca; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.a=rsa-sha256 header.s=default header.b=yEGZdltG; dkim-atps=neutral X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-2.0 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RDNS_DYNAMIC,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from sourceware.org (ip-8-43-85-97.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 9DD0B1E87E for ; Mon, 25 Jul 2022 16:36:08 -0400 (EDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id C75EC3839C6C for ; Mon, 25 Jul 2022 20:36:07 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org C75EC3839C6C DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1658781367; bh=y+b8rU74m+3xGR8aWLerc36nMRV/818+8ERLaqkwms4=; h=Subject:To:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=yEGZdltGAHEmaue4HClzLl85efO9rXm3helrtH9LYCnxv0gGoI4yd7wtaseaaGf31 wJKbgYt7/EPhK7tvr8iGH8fs0VaEGvM+nvJ6SrbolMsdf10L45zYdiIDaVQMfszI61 cOi1C3sEmOhgP/aKvDDe4rZa77fttxzEKz+ZQ+gI= Received: from mailsec113.isp.belgacom.be (mailsec113.isp.belgacom.be [195.238.20.109]) by sourceware.org (Postfix) with ESMTPS id 7C35E3858CDA for ; Mon, 25 Jul 2022 20:35:47 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 7C35E3858CDA X-ExtLoop: 1 X-IPAS-Result: =?us-ascii?q?A2C3AQCZ/d5i/1uGgG0NTYEJCYZEhE6RCwORNI1BCwEBA?= =?us-ascii?q?QEBAQEBAQlCBAEBhQEDAgKEbSY4EwECBAEBAQEDAgMBAQEBAQEDAQEGAQEBA?= =?us-ascii?q?QEBBgQBgRuFLwwIgmcpAYNjAQEBAQIBIw8BRhAJAg0HAQMCAiYCAlcGE4Vzj?= =?us-ascii?q?jubGnqBMRpnhHCDLIFlgREsgWaFdoc4N4FVRIEVgyo+iBqCQyIEnDkcOAMaL?= =?us-ascii?q?S8SgR9sAQgEBgcKBS4GAgwYFAQCExJTFgISBQ8ZDhQbIhcMDwMSAw8BBwIJE?= =?us-ascii?q?AgRJQgCAwgDAgMbCwIDFgYOAx0IChgSEBICBBEaCwYDFj8JAgQOA0AIDgMRB?= =?us-ascii?q?AMPGAkSCBAEBgMyDCULAxQMAQYDBgUDAQMbAxQDBSQHAx8PIw0NBBgHHQMDB?= =?us-ascii?q?SUDAgIbBwICAwIGFQYCAk45CAQIBCsjDwUCBy8FBC8CHgQFBhEIAhYCBgQEB?= =?us-ascii?q?AQWAhAIAggnFwcTGBsZAQVZEAkhHA4aCgYFBhMDIG8FCjsPKDM1PCsfGwqBE?= =?us-ascii?q?iorFgMEBAMCBhoDAyICEC4xAxUGKRMSLQkqdwkCAyJwAwMEKi4DCSEfBxkBH?= =?us-ascii?q?Z1tEVoGPiYBEDaBCx0tRgg1L79sfTQHg1SBPgYMnkgxlwIDkWKWfKI4hRyBe?= =?us-ascii?q?IF+bVOCaFGMEpEIczsCBgEKAQEDCYw+LIE/XQEB?= IronPort-PHdr: A9a23:qEF/Dx8/S2KtXv9uWbe8ngc9DxPPW53KNwIYoqAql6hJOvz6uci4Z wqFvaUm1QOWFazgqNt8w9LMtK7hXWFSqb2gi1slNKJ2ahkelM8NlBYhCsPWQWfyLfrtcjBoV J8aDAwt8H60K1VaF9jjbFPOvHKy8SQSGhLiPgZpO+j5AIHfg9q52uyo5ZHffwZFiDWgbb59L hi9sBncuNQRjYZ+MKg61wHHomFPe+RYxGNoIUyckhPh7cqu/5Bt7jpdtes5+8FPTav1caI4T adFDDs9KGA6+NfrtRjYQgSR4HYXT3gbnQBJAwjB6xH6Q4vxvy7nvedzxCWWIcv7Rq0vVD+88 6lkVgPniCYfNz447m7XjNBwjLlGqx6lvhBz3pLYbJ2QOPd4Y6jTf84VRXBZU8hSSiJPAp2yY pUBAeUDM+ZXs4fyqFQBoxalGQmhB/nixiNUinLs36A31fkqHwHc3AwnGtIDqG7arNX0NKcWU OC11LHIwiveZPxWwzj98o/Icgk8ofGNQ71wa9HRwlQoGgPdjlWQqIjlPzKN1uQVrWeX9eRhW vi1i24gsgFxvzmvydk2ionSnY8V0VPE9CV/wIkrOd20UlV0bsC9HZZWqiqVOJd4TNk4TGF0p CY11KcGuZijcSUO1JgpxwLSZv2GfoaH/B7uW+afLDN3iX9ner+yhBa8/VW8x+HhV8S5zlZHo y5Zn9XRq30D2BLd5tWJR/dj+kqs3yuE2QPL6uxcPEw4ia7WJ4Q8zrIulZcfq1nPEyH5lUnsi KKaa0Mp8fWy5ev9eLXpvJqcOpdxigH5L6shhNSyAf89MggSR2ib/vm81KH78U35XrpKivo2n 7Hdv5zHIckXuLS1DxJU34sg8RqzEi2q3MkckHYBNF5FeRSHgJb1O1zWPfz0EfOyj06xnDt1x P3KJKDtD5vCI3TZlLrtYK5x60tGxwoyydBf6YhUCrYEIP/rQk/xtN3YDhs4Mwys2+boFs9x1 40EVmKVBa+ZKb7SsV6W6eI1OOmBf5QVuDX9Kvgj+fHukWU1lkQDcqWx25sYc2i3Hu56LEWBf XrsntABHH8UsgYmVuzllEWCUSJPZ3a1R68z+DU7CIOnDIrYSYCthqGB0D28Hp1MaWBKEkqMH mvwd4WYR/cMbzqfIsB8nTMfTLShU5Uu1Q2yuw/61bVnNfHZ+jYftZL+zth6+/PclB8o+jxuE cuRyWaNT3t7njBAezhj8aR+6X500Fqfyqt5grQMGNhS9dtGVBp8MoTTmb9UEdf3DzrBf9OIU E6rCuqvGzYoU9M82cRGN159GtGjlgjOmTWjGbgMir2GHocc6aHN2XXtYcxwnSWVnJI9hkUrF 5McfVatgbRyok2KX9ahrg== IronPort-Data: A9a23:lYXq2K0XHtz3HVwtufbD5XVzkn2cJEfYwER7XKvMYLTBsI5bpzAAx mQdDziBbv2NZ2amctonPdjnoRsGupLRydc2GgRl3Hw8FHgiRegppTi6wuYcGwvIc6UvmWo+t 512huHodZxyFjmFzvuUGuCJQUNUjMlkfZKhTr+fUsxNbVU8En151kg+w7RRbrNA2LBVPSvc4 bsenOWCYDdJ6xYsWo7Dw/vewP/HlK2aVAIw5jTSV9gS1LPtvyV94KYkGE2EByCQrr+4sQKNb 72rILmRpgs19vq2Yz+vuu6TnkYiGtY+MeUS45Zbc/DKv/RMmsA9+psZFPtERABPsDOyk/BR0 4tcnr7tYhh8a8UgmMxFO/VZOxInbPcAoeGXZyH56J2mp6HEWyK0krM3VhFwZNZEvLcuaY1N3 aVwxDQldhCCg+Ou2L/9VeB2gd0+LcTxJ6sEuWBmwC2fB/tOrZXrGvyXvoMHgmZr7ixINa3cP skENzw2VRLFOzFyBW0QEpgusej90xETdBUd8jp5v5Ef7mzS3iR+1qWrN8DaEvSFSc8Qhk+Er WLL5EziBQwAP9GAwCCItHW2iYfycTjTAdpDUuTiprgz2wHVlzV75AAqaGZXaMKR0iaWM++z4 WRNksbyhcDeP3BHgjUws9NUbZJEUtMhtwJsLtAH IronPort-HdrOrdr: A9a23:pdSYnq4FxSee8wKrogPXwMPXdLJyesId70hD6qm+c3Nom6uj5q STdZUgpHzJYVkqNk3I9ersBEDEexLhHP1OkOws1NWZNzUO0VHARL2Kr7GD/9SKIUfDH4BmuZ uIP5IOauHNMQ== X-IronPort-Anti-Spam-Filtered: true X-ProximusIPWarmup: true Received: from unknown (HELO [192.168.1.19]) ([109.128.134.91]) by relay.proximus.be with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 25 Jul 2022 22:35:46 +0200 Message-ID: <459ea883bef4b9af65194bd3e5ed4de78b600c62.camel@skynet.be> Subject: Re: [RFA] Allow to document user-defined aliases. To: Eli Zaretskii Date: Mon, 25 Jul 2022 22:35:45 +0200 In-Reply-To: <831qu9fna0.fsf@gnu.org> References: <20220725041113.185127-1-philippe.waroquiers@skynet.be> <831qu9fna0.fsf@gnu.org> Content-Type: text/plain; charset="UTF-8" User-Agent: Evolution 3.38.3-1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , From: Philippe Waroquiers via Gdb-patches Reply-To: Philippe Waroquiers Cc: gdb-patches@sourceware.org Errors-To: gdb-patches-bounces+public-inbox=simark.ca@sourceware.org Sender: "Gdb-patches" On Mon, 2022-07-25 at 14:24 +0300, Eli Zaretskii wrote: > > Date: Mon, 25 Jul 2022 06:11:13 +0200 > > From: Philippe Waroquiers via Gdb-patches > > > > When using 'help ALIASNAME', GDB shows the help of the aliased command. > > This is a good default behaviour. > > > > However, GDB alias command allows to define aliases with arguments > > possibly changing or tuning significantly the behaviour of > > the aliased command. In such a case, showing the help of the aliased > > command might not be ideal. > > But it doesn't do much harm, either. Moreover, it is useful to tell > the user that some handy aliases exist related to the command. The idea/reasoning is that if the user documents specifically the alias, it means that the alias is not properly documented by the doc of the aliased command. It is for sure trivial to still show the alias definition in the list of aliases of the aliased command, but at work, this currently results already in quite a long list of aliases for the with command, with little value: (gdb) help btf with, Wmay-call-function, Wunlimited, Wada, Wc, scan-every-of-type, scan-args-of-type, scan-locals-of-type, btf, bts, btS, w alias Wmay-call-function = with may-call-functions -- alias Wunlimited = with max-value-size unlimited -- with annotate 0 -- with print elements unlimited -- alias Wada = with language ada -- with annotate 0 -- alias Wc = with language c -- with annotate 0 -- alias scan-every-of-type = with annotate 0 -- with print frame-info short-location -- with print frame-arguments presence -- with print address off -- frame apply all -s info-args-and-locals-matching-type alias scan-args-of-type = with annotate 0 -- with print frame-info short-location - - with print frame-arguments presence -- with print address off -- frame apply all - s info args -q -t alias scan-locals-of-type = with annotate 0 -- with print frame-info short-location -- with print frame-arguments presence -- with print address off -- frame apply all -s info local -q -t alias btf = with print address off -- with filename-display basename -- backtrace - full alias bts = with print address off -- with filename-display basename -- backtrace - entry-values no -frame-arguments presence -frame-info location alias btS = with print address off -- backtrace -entry-values no -frame-arguments presence -frame-info short-location Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING. Usage: with SETTING [VALUE] [-- COMMAND] Usage: w SETTING [VALUE] [-- COMMAND] With no COMMAND, repeats the last executed command. SETTING is any setting you can change with the "set" subcommands. E.g.: with language pascal -- print obj with print elements unlimited -- print obj You can change multiple settings using nested with, and use abbreviations for commands and/or values. E.g.: w la p -- w p el u -- p obj (gdb) The long list of long aliases clutters the help of 'with' and confuses the reader. E.g. btf is really doing a backtrace, but looks like it is a 'with command'. The idea is that all these aliases will be documented, and then should not clutter anymore the 'with' help. Note that currently, when showing the help for a documented alias, the alias definition is not shown. It would be easy to show the alias documentation and its definition. > > > This is particularly true when defining an alias as a set of > > nested 'with' followed by a last command to launch, such as: > >   (gdb) alias pp10 = with print pretty -- with print elements 10 -- print > > Asking 'help pp10' shows the help of the 'with' command, which is > > not particularly useful: > >   (gdb) help pp10 > >   with, pp10, w > >     alias pp10 = with print pretty -- with print elements 10 -- print > >   Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING. > >   Usage: with SETTING [VALUE] [-- COMMAND] > >   .... > > Maybe help for an alias shouldn't show the original commands, but help > for "with" could usefully mention pp10. That is in fact the current behaviour, which I find confusing (see above the help for 'btf' at work, showing in fact the help of 'with' with a bunch of aliases that in reality are very different of a 'with' command. > > Or maybe we should be smarter and show only the help for pp10 when > help for "print" was requested. Sadly, this seems not easy to do/not really doable. The problem is that GDB cli is not cleanly implemented in a parsing phase followed by an execution phase. Parsing a command is mixed with executing the command. Also, more sadly, it is possible to define an alias that is using some other not yet defined commands, for example: (gdb) alias thread-apply-all-foo = thread apply all foo (gdb) define foo Type commands for definition of "foo". End with a line saying just "end". >next >end So, discovering the real command that an alias launches/will launch is IMO not doable without significant/major rework of all the command parsing. > > > Such an alias can now be documented by the user: > >   (gdb) document pp10 > >   >Pretty printing an expressiong, printing 10 elements. > >   >Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP > >   >See 'help print' for more information. > >   >end > >   (gdb) help pp10 > >   Pretty printing an expressiong, printing 10 elements. > >   Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP > >   See 'help print' for more information. > >   (gdb) > > > > When a user-defined alias is documented specifically, help and apropos > > use the provided alias documentation instead of the documentation of > > the aliased command. > > > > Such a documented alias is also not shown anymore in the help of the > > aliased command, and the alias is not listed anymore in the help > > of the aliased command. > > When you say "such a documented alias", do you mean that by just > documenting the alias has this effect? IMO, this could be too > far-fetched. How about adding some specific attribute of the command > to that effect, instead of re-purposing the documentation attribute? Effectively, the idea is that giving a specific documentation to an alias makes it a "first class/independent" command. IIUC, what you suggest is to add e.g. an option -s (for standalone) to the alias command. When -s is given, then the alias would not be shown in the list of aliases of the aliased command. That is another way to ensure e.g. that the 'help with' is not cluttered with plenty of not relevant aliases. But I found the indication given by the specific alias doc reasonable/simple enough and intuitive. I can for sure implement the alias -s option if there is an agreement that this is better. Thanks Philippe > > > +(@pxref{Command aliases default args,}). >                                        ^ > That comma should be deleted. Will fix in the next patch version. > > The documentation parts are OK, assuming that the implementation is > accepted. > > Thanks. Thanks for the (as usual) quick and good review. Philippe