Multiple subcommand categories / help_headings

[BrettMayson]

Feature Request Summary

It would be nice to be able to have multiple subcommand groupings.

Sample

An example of what I mean can be found at BrettMayson/HEMTT#195

[epage]

@pksunkara we were just talking about whether App::subcommand_help_heading should be supported in a way to allow individual subcommands to have their own help heading like args.

[pksunkara]

Looks like I didn't need to create an issue for what we were talking about.

[epage]

The question we need to resolve with this is how to handle naming

App::help_heading applies to future args

App::subcommand_help_heading globally applies to subcommands as if you called App::help_heading at the start and never called Arg::help_heading.

Maybe if we changed the behavior so that

• App::help_heading applied to future args and subcommands
• App::subcommand_help_heading applied to the current subcommand like Arg::subcommand
  • We'd have to deal with what to name App::subcommand_value_name because that was mean to be parallel to the current behavior

This would be a breaking change and one that doesn't offer a transition path with deprecations. Any other ideas for how we could do this?

[pksunkara]

Bikeshedding on the name to make it more clear,

• App::help_heading => Command::help_heading_group
• App::subcommand_help_heading => Command::help_heading (similar to Arg::help_heading)

One concern with combining the arg and app help heading setting in one function is what to do when they have a common heading? How do we display the help?

[epage]

One option I had been considering that I forgot until your post is Command::next_help_heading.

I worry people will just refer to what help headings as groups or categories, so using a _group suffix I don't think will convey the intent of "all following are being grouped under the this heading" (which I'm assuming is the intent of the suggestion).

[pksunkara]

Yeah, I think I am trying to convey that the function sets help heading for both args and subcommands. Maybe it's better if we just divide them into args_help_heading and subcommands_help_heading. But I think next_help_heading is better than help_heading_group definitely.

[epage]

So to summarize the solution:

• App::help_heading would
  • Be renamed App::next_help_heading
  • Will also apply to subcommands
• App::subcommand_help_heading would be removed
• App::help_heading would be added and acts like Arg::help_heading but for subcommands
• We would need to add tests to make sure next_help_heading on a derive(Subcommand) behaves as expected.

I guess the downside to the name next_help_heading is in derives. This is also getting me thinking that maybe we should provide some more flexibility by renaming our attribute from clap to clap::app and clap::arg. This would allow a user to set app settings in the middle of the derive. If that idea sounds like it has potential, I'll create a separate issue for further discussion.

[epage]

#3414 changed App::help_heading -> App::next_help_heading. The rest of the work is reserved for clap 4.

[epage]

Think I'm going to push this out.

In working on this, I realized a problem we'd have is how to set the help heading for the implicit help subcommand and help/version flags.

[milesj]

Been a year now, has there been any movement on this?

[YamatoSecurity]

We would love this feature as well... only being able to have one group for commands is very limiting and makes for a bad UI for the user.

[Fiedzia]

I am trying to implement it. I am wondering where to place command that do not belong to any groups and the "commands" heading.
Option 1: commands not belonging to any group go to top

Commands:
cmd1 ...
cmd2 ...

Group1:
cmd3
cmd4

Group2:
cmd5
cmd6

meaning placing commands not belonging to any group on top.
Alternatively, They could go to bottom. This makes more sense to me,
but maybe not to other people.

Group1:
cmd3
cmd4

Group2:
cmd5
cmd6

Commands:
cmd1
cmd2

and what to do when heading is provided, but all commands are grouped:

Commands:

Group1:
cmd3
cmd4

Any thoughts?

[epage]

I'd recommend doing what we do for Options.

However, before going to far down this, how do you plan to handle the help subcommand? That is why I stopped this work before. In clap v3, we had a bunch of specific helpers for overriding builtin arguments (--help, --version) and we simplified things a lot (improving performance and reducing binary bloat) by only supporting users disabling the built-in argument and providing it themself. Currently, there isn't a way to do the same thing with the help subcommand. My assumption is that we need to solve that problem first before we add custom help headings for subcommands.

[Fiedzia]

Currently a CommandGroup would be added, and it can have optional heading (group won't show a name for group unless you specify heading).

[epage]

I would like this to be consistent with arguments. If there is a reason we should change arguments, we should have that as a separate conversation.

That said, that doesn't say how users can use this with a built-in command (help). As I said, there is likely something we need to solve there first.

[Fiedzia]

I would like this to be consistent with arguments.

Ok, makes sense. Arguments print heading and a list of ungrouped arguments on top, no heading if there are no ungrouped arguments.

that doesn't say how users can use this with a built-in command (help)

With current implementation I have, it treats it as any other command. By default it is ungrouped. You can put it into a group if you wish (well, you can via builder, not sure about derive). Seems intuitive to me.

[epage]

Ok, makes sense. Arguments print heading and a list of ungrouped arguments on top, no heading if there are no ungrouped arguments.

Also, you specify a help heading. Argument groups are for associations and not visualization.

With current implementation I have, it treats it as any other command. By default it is ungrouped. You can put it into a group if you wish (well, you can via builder, not sure about derive). Seems intuitive to me.

How do you put help under a custom heading?