Better looking visible aliases for subcommands

[sondr3]

Right now when you create a visible alias for a subcommand it appears in brackets after the help message, so when I first added some visible aliases I thought it didn't work. I like how Jekyll for example does it:

❯ jekyll --help
jekyll 3.8.4 -- Jekyll is a blog-aware, static site generator in Ruby

[snip]

Subcommands:
  build, b              Build your site
  serve, server, s      Serve your site locally

as opposed to Clap:

❯ ./target/debug/blug --help

[snip]

SUBCOMMANDS:
    build     Build your blug without serving it. [aliases: b]
    create    Create a post, page, draft etc [aliases: c]
    init      Initialize a new blug [aliases: i]

[sondr3]

After having used Rust for a while now I think this is something I might be able to implement myself, are there any thoughts on how this should work? Should I create a AppSetting::MergedAliases for example or just outright change how aliases are displayed? @pksunkara @CreepySkeleton

[pksunkara]

Outright change is probably not a good idea. A setting sounds good but I am wondering if we are taking this too far. What if people want it in a different kind of way?

[sondr3]

Any suggestions for how you'd approach this in that case?

[pksunkara]

I am honestly stumped regarding the design here. @kbknapp What do you think?

[CreepySkeleton]

I personally like this one more

  build, b              Build your site
  serve, server, s      Serve your site locally

[pksunkara]

I don't think we should be defaulting to that. But I too like it, which is why I am saying that we should come up with a way to allow users to format the help messages.

[kbknapp]

The difference between the two versions is aesthetic only and not structural, so I'd prefer to have one way to display it and stick to that. I don't think it's worth the overhead to provide an option to switch between whichever way is the default and the other way.

The same could be argued for options/flags, however the average long flag (and especially options) take up far more room than subcommand names, hence placing them at the back of the help message where they can easily be wrapped if required without throwing off the aligned of all other options/flags. Of course this doesn't apply as much to multi-line help messages (long_help), but those aren't the default.

The only aesthetic AppSetting we have is similar to this proposal is UnifiedHelpMessage, but I'd argue that's a whole different category and provides a common format used by a lot of CLIs.

As for which version I prefer? I don't have super strong feelings about either. I could be convinced that the new way looks a little better. But it also suffers from the alignment issue described above. Since this change only affects subcommands, I'd be fine accepting it. My only other concern is then the request to do the same for flags/options would become a request which I would be more against for the alignment issues.

Maybe it'd be worth a look through github and grep.app to see average length of subcommands/aliases because when combined with #1891 if we lowered the default term width to 100, I'd want to make sure we didn't end up with help messages like this (exaggerated just for example):

    build, b            build your
                        site
    serve, server, s    serve your
                        site
                        locally

[pksunkara]

But it also suffers from the alignment issue described above.

It is the main reason I prefer not to change the current way of showing aliases.

But, we can allow a help_generate hook which could be filled by individual clap programs if they want a different aesthetic. This could work similar to clap_generate.

[epage]

I think #962 could be useful which might come at odds with showing the aliases first.

Thoughts on how these two might interact?

[pksunkara]

How do we show the aliases in args? I think we print them as [alias: s] etc at the end of the help, right? Maybe we could follow a similar pattern in order to not conflict with #962.

But I think #2914 should actually solve this and #962

[epage]

Yes, I believe subcommands are currently rendered like args, with a trailing [alias: s], so "doing nothing" makes it so we don't conflict with #962.

The big question is how much logic should be built-in and how much should we punt to people doing it themselves with #2914. I lean towards closing this in favor of #2914 but keeping #962 open. I'd like to try it out on some commands to see how well it works to give an idea for how universally useful it would be which could bump its prioritization for being built-in.

One idea I had for #2963 was to experiment with making all parenthetical information dimmed, giving it a different visual than the about, making it easier to scan for one vs the other. In terms of scanning, that would also help improve things here.