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.