Re: help text of aliased commands using "with"

[Simon Sobisch <simonsobisch@gnu.org>]

Thanks Philippe for taking the time to answer ins such a detail.
I now see that it is not really possible to document the "with" parts.

Dropping the aliases using "with" from "help with" seems to be very 
useful, similar showing the help of the aliased COMMAND when using with 
and default args as a reasonable default.

The addition of allowing aliases to get their own help (currently 
raising an error 'Command "with" is built-in.') would allow the user to 
handle this as deemed useful.
It would be nice to see those additions in GDB 13 :-)

Simon


Am 10.06.2022 um 07:36 schrieb Philippe Waroquiers:
> On Thu, 2022-06-09 at 11:27 +0200, Simon Sobisch via Gdb wrote:
>> Questions:
>>
>> 1 Can the alias always be printed? scenario 1 misses the line
>>     alias asdf = print"
>>     I guess that's possibly a small bug fix.
> Before aliases could have default args, the help of a command was
> not showing its aliases.
> 
> When aliases could have default args, help was changed to show
> also the aliases, but only the aliases that have default args.
> This behavior is an explicit choice: the help first shows the
> complete list of aliases (with or without default args).
> It then shows the full alias definition only for aliases that have default args,
> as for "simple" aliases, this line does not bring additional information.
> Here is the code that implements the logic "show only aliases having default args":
>        /* Print the definition of the aliases of CMD that have default args.  */
>        
>        static void
>        fput_aliases_definition_styled (const cmd_list_element &cmd,
>        				struct ui_file *stream)
>        {
>          for (const cmd_list_element &alias : cmd.aliases)
>            if (!alias.cmd_deprecated && !alias.default_args.empty ())
>              fput_alias_definition_styled (alias, stream);
>        }
>        
> It would of course be trivial to remove the condition "&& !alias.default_args.empty ()".
> Question is if this longer help output is really worth. At the time it was developed,
> it was deemed better to not output such "simple" aliases twice.
> 
> 
>>
>> 2 Is it possible to adjust "alias --" to let its help point to the
>>     actual COMMAND?
>>     Preferably with the help for the parameters requested?
>From memory, I contemplated doing this when default args was added, but this was
> not easy: one reason is because the alias is associated to "its parent
> command" (the command to be executed when alias is used).
> Also, default args are not typically not validated/parsed. So, the final command of
> a chain of "with" is only discovered "at runtime", i.e. when alias is used.
>        (gdb) alias groinch-boing-boum = with groinch on -- with boing on -- boum
>        (gdb) groinch-boing-boum
>        Undefined set command: "groinch".  Try "help set".
>        (gdb)
> The problem is that gdb does not really have a 'command definition language/syntax':
> GDB does (mostly) not separate the parsing of a command and the execution of a command.
> Parsing and execution are typically mixed. This is e.g. also visible when using
> the "define" command:
>        (gdb) define boum
>        Type commands for definition of "boum".
>        End with a line saying just "end".
>        >bang
>        >bing
>        >bong
>        >end
>        (gdb)
>        
> Nothing in the above was parsed or validated.
> And we can define boum (including its help) after boum has been used
> in a chain of "with".
> 
>>
>> Draft output (as in scenario 2 + output of the "with" entries as shown
>> with "help set print elements unlimited"):
>>
>> (gdb) help asdfw
>> print, asdfa, asdfw, asdf, inspect, p
>>    alias -- asdfw = with print elements unlimited
>>                  -- with print repeats unlimited
>>                  print
>>
>> Print value of expression EXP.
>> Usage: print [[OPTION]... --] [/FMT] [EXP]
>> [... rest of print help]
>>
>>    print repeats unlimited
>> Set threshold for repeated print elements.
>> "unlimited" causes all elements to be individually printed.
>>
>>    print elements unlimited
>> Set limit on string chars or array elements to print.
>> "unlimited" causes there to be no limit.
>>
>>
>> 3 If this isn't possible then could the help of "alias --" entries be
>> adjusted to "just show the alias? Draft output for that:
>>
>> (gdb) help asdfw
>>    alias -- asdfw = with print elements unlimited
>>                  -- with print repeats unlimited
>>                  print
>> Do "help with", "help print" for info on commands executed.
>>
> As explained above, an alias of a chain of "with" does not know that at
> the end the "print" command will be executed.
> 
> I have in a corner a patch that allows to document explicitly an alias.
> With this patch, you can do:
>        (gdb) alias pretty-boum = with print pretty on -- boum
>        (gdb) document pretty-boum
>        Type documentation for "pretty-boum".
>        End with a line saying just "end".
>        >Doc of the alias launching the command boum with pretty on.
>        >Use pretty-boum at your own risk !
>        >end
>        (gdb) help pretty-boum
>        Doc of the alias launching the command boum with pretty on.
>        Use pretty-boum at your own risk !
>        (gdb)
>        
> The patch is still missing gdb manual update and tests.
> Also, I am thinking that maybe an explicitly documented alias
> should not be put in the help output of its "parent" command
> based on the assumption that an explicit doc for an alias
> is an indication that it should be considered as a "quite different"
> command than its parent command.
> 
> We might as well contemplate to not output the aliases that are aliasing
> the "with" command.
> 
> 
> Philippe