confusing documentation on parsing multiple subcommands (minor issue)

[0x900C5649]

I am working on a personal project for which I would like to parse a list of subcommands (together with their arguments).
So something like:

./myprogram generatelist --size 12 storelist mylist.txt

I wanted this to give me two subcommands (generatelist and storelist) with their arguments.

I thought this is possible because the [documentation] (https://docs.rs/clap/2.32.0/clap/enum.AppSettings.html#variant.ArgsNegateSubcommands) on AppSettings::ArgsNegateSubcommands states:

By default clap allows arguments between subcommands such as <cmd> [cmd_args] <cmd2> [cmd2_args] <cmd3> [cmd3_args]

As I couldn't make my program work I checked for more sources and found

• Implement multiple subcommands at once #84 (which is marked as W: wont do)
• The comment in clap/examples/20_subcommands.rs:

  // Notice only one command per "level" may be used. You could not, for example, do:
  //
  // $ git clone url push origin path

Both basically state, that what I wanted to do is not possible.

So my best guess is, that the documentation on AppSettings::ArgsNegateSubcommands assumes <cmd3> to be a subcommand of <cmd2>, which should be a subcommand of <cmd>

Possible fix

The simplest solution to avoid this confusion would probably be to rename the subcommands in the documentation to <cmd>, <subcmd> and <subsubcommand>

[ithinuel]

I had the exact same "adventure" than you.

[pksunkara]

The actual issue is #2222 but leaving this issue open for docs fix.