Subcommands arguments

[plmuninn]

Is there a way or plan to display arguments for subcommands?

I think it would be handy to have them in detail in Subcommands section and in usage part with shorter version.

[bkirwi]

So, for context: currently, we display usage for subcommands more or less when we'd display it for the top-level command -- so eg. command --help shows the top-level usage including subcommand list, and command subcommand --help shows the subcommand-specific usage. (Ditto for parse failures -- command subcommand --unknown-option will show subcommand-specific usage info.)

In general, I think having the full details in the "Subcommands" section is a bad idea, though I know some other libs have gone that way... for complex tools the usage text becomes unmanageably large & confusing, and it goes against the precedent set by popular tools like git.

It might be the case that we could add some basic usage info to the subcommand-list section. I worry that this won't scale to complex subcommands, and so this will add new inconsistency to the interface. I'll think it over.

[johnynek]

I can imagine ways to send options to build the help screen. The default could use some heuristic to try fit on one page, if you have a simple help show the whole help.

But you could also have a way users could customize the help message.

[plmuninn]

@bkirwi I get you, but I also think library like this should give you some ways of handling requirements like that. I'm now working on CLI where having full options would be perfect. Right now I was able to display Help manually but its really "ugly" way of doing it.
I also tried to fork decline and implement it, I did subcommands argument descriptions without problem but I failed on displaying arguments in usage part.

@johnynek I don't think it should be configurable per se - maybe just Help should have different forms / subtypes, type class for displaying it or smth.

[bkirwi]

Yeah, it's an interesting balance.

One way to go about it would be to capture more structure in the Help case class, so that you could pull information from it in more interesting ways. But I'd still prefer keeping the interface small if we can swing it.

One good avenue into the question -- are there popular CLI tools with usage text that uses the style you're suggesting? eg. alexjg did a great job collecting examples and prior art for a previous change.

[ivan-klass]

Just thinking in loud: what if having something like

trait HelpPolicy {
   def displayIfShallower(depth: Int): Boolean
}
object HelpPolicy {
  def limitDepth(limit: Int) : HelpPolicy = _ <= limit
  implicit val defaultHelpPolicy: HelpPolicy = limitDepth(1)
}

so we need an instance for that when parsing or when generating help options

[bkirwi]

I think in practise that ends up equivalent to...

val help: Help = ???
help.display(ifShallower = 1)

I've been trying not to introduce too many typeclasses etc. if possible... nice to keep the library small!

Re: the depth idea... I'm definitely supportive of keeping enough structure in the Help that you could do such things, but I'm not sure I'd want to have that rendering method built in. (The built-in stuff tries to follow bog-standard UNIX idioms, and I've never seen another UNIX tool render stuff that way. Would consider it if folks find examples though!)

[ivan-klass]

Totally agree that structured help is a most flexible choice!

[bkirwi]

Closing in favour of #138!