Re: [RFA] Allow to document user-defined aliases.

[Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org>]

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 <gdb-patches@sourceware.org>
> > 
> > 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