Improve synopsis for commands with ArgGroups with positional parameters

[deining]

Derived from #1050:

import java.util.List;
import picocli.CommandLine;
import picocli.CommandLine.*;

@Command(name = "grades", mixinStandardHelpOptions = true)
public class App implements Runnable {

    static class StudentGrade {
        @Parameters(index = "0") String name;
        @Parameters(index = "1") int grade;
    }

     @ArgGroup(exclusive = false, multiplicity = "1..*")
    List<StudentGrade> gradeList;

    @Override
    public void run() {
    }

    public static void main(String[] args) {
        System.exit(new CommandLine(new App()).execute("-h"));
    }
}

This results in:

Usage: grades (<name> <grade>)... [-hV]
      <name>
      <grade>
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.

IMHO, it were appropriate to swap parameters and help + version options:

Usage: grades [-hV] (<name> <grade>)... 

[remkop]

One way to accomplish this is to make non-group options always precede argument groups in the synopsis. (Simple, predictable, but potentially some disruption for existing applications.)

Another idea is to only let options precede groups if the groups contain only positional parameters. Not sure if I like that idea. (Less predictable)

Yet another idea is to make this configurable. That would raise more questions: what API do we want to offer, and what is the scope? For example, making the synopsis for groups configurable will be complex.

Finally, we can leave it the way it is. (Simple, predictable, no disruption for existing applications, but sometimes gives a counter-intuitive synopsis.)

Thoughts?

[deining]

One way to accomplish this is to make non-group options always precede argument groups in the synopsis. (Simple, predictable, but potentially some disruption for existing applications.)

IMHO, this is the way to go.

Yet another idea is to make this configurable.

That seems to be overkill for me.

Finally, we can leave it the way it is.

I'm not really happy with the current (inconsistent) way the synposis printed. That's why I raised and authored this issue.

Just my two cents.

[remkop]

One way to accomplish this is to make non-group options always precede argument groups in the synopsis. (Simple, predictable, but potentially some disruption for existing applications.)

IMHO, this is the way to go.

I was thinking the same thing. We will do it that way.
Thanks for the feedback!

[remkop]

One small complication is when the end-of-options [--] delimiter is to be shown in the synopsis.
For groups that have a mixture of options and positional parameters, we have little choice but to show this after the groups. But for groups with only positional parameters it is nice if we can display this between the options and the groups, so we get:

Usage: <main class> [-hV] [--] [<param00> | <param01>]