Don't collapse optional positional arguments into [ARGS] in the usage string

[dotdash]

Rust Version

rustc 1.15.0-nightly (daf8c1dfc 2016-12-05)

Affected Version of clap

2.19.1

Expected Behavior Summary

If I have one required and two optional positional arguments, I expect the usage string to say:

USAGE:
    clap-test <FILE> [<WIDTH> [<HEIGHT>]]

to properly represent the order in which the arguments need to be given.

Actual Behavior Summary

The optional positional arguments are collapsed into a single [ARGS] placeholder, and I have to look at the ARGS block and know it tells me the required order.

USAGE:
    clap-test <FILE> [ARGS]

FLAGS:
        --help       Prints help information
    -V, --version    Prints version information

ARGS:
    <FILE>      the configuration file
    <WIDTH>     texture width [default: 512]
    <HEIGHT>    texture height [default: 512]

Steps to Reproduce the issue

Run the program with --help.

Sample Code or Link to Sample Code

extern crate clap;
use clap::{Arg, App};

fn main() {
    let matches = App::new("My  app")
        .version("0.1")
        .author("Me <me@ma.il>")
        .about("Does stuff")
        .arg(Arg::with_name("config")
             .value_name("FILE")
             .help("the configuration file")
             .required(true)
             .takes_value(true)
             .index(1))
        .arg(Arg::with_name("width")
             .value_name("WIDTH")
             .help("texture width")
             .takes_value(true)
             .default_value("512")
             .index(2))
        .arg(Arg::with_name("height")
             .value_name("HEIGHT")
             .help("texture height")
             .takes_value(true)
             .default_value("512")
             .index(3))
        .get_matches();
}

[kbknapp]

I do agree, but at the same time I worry about applications that have lots of positional arguments. I'd like to get some others opinions on this issue before merging.

One point I'd like to change from your proposal though is the $ prog <required> [<optional1> <optional2>]

I'd prefer that go to $ prog <required> [optional1] [optional2]. This is personal preference but I dislike the CLIs that give me a usage strings like $ prog <opt> [[<req>|[-e <some>]] | [other]] It gests difficult to parse (mentally) very quickly.

[dotdash]

Oh, I meant to mention that I'd be fine with not nesting the square brackets. Not sure what the best option is for handling lots of optional positional arguments, but the same problem already exists for required positional arguments, so a common solution would be nice.

[kbknapp]

So we already don't collapse them down if it's only 2 positional arguments (I believe...I can't remember 😜 ). So it's entirely possible that we only collapse them after only after a [higher] certain number (perhaps up the number to...5?).

[dotdash]

They're collapsed to [ARGS] if there are two or more. I guess I could live with collapsing only if there are more than X items, or even just an option that allows me to just disable it altogether.

[kbknapp]

Adding an option to just disable the collapsing is easy, and I think the route I'll go since that won't mess with current usage strings (i.e. it's an opt-in feature).