anchor.diff:      @Parameters Path path;
       @Option(names = "-d") Duration duration;
   }
  -CommandLine commandLine = new CommandLine(new App());
  +----
  +
  +[source,java]
  +----
  +App app = new App();
  +CommandLine commandLine = new CommandLine(app);
   commandLine.registerConverter(java.nio.file.Path.class, s -> java.nio.file.Paths.get(s));
   commandLine.registerConverter(java.time.Duration.class, s -> java.time.Duration.parse(s));
   
  -String[] args = { "-d", "PT15M", "file1.txt" };
  -List<Object> parsed = commandLine.parse(args); // returns parsed commands and subcommands
  -
  -App app = parsed.get(0);
  +commandLine.parse("-d", "PT15M", "file1.txt");
   assert app.path.equals(Paths.get("file1.txt"));
   assert app.duration.equals(Duration.parse("PT15M"));
   ----
   
  +=== Arrays and Collections
  +
  +IMPORTANT: With array fields picocli uses reflection to discover the array element type, but with collections, Java type erasure means picocli cannot find out the generic type of the collection. For non-String collections, use the `type` attribute to explicitly tell picocli what type to convert the command line arguments to.
  +
  +Multiple parameters can be captured together in a single array or `Collection` field. When using a collection, use the `type` attribute to specify the collection element type. For example:
  +
  +[source,java]
  +----
  +class Convert {
  +    @Option(type = java.util.regex.Pattern.class, // List elements are Pattern objects
  +            names = "-patterns", valueLabel = "PATTERN",
  +            description = "the regular expressions to use for the conversion");
  +    List<Pattern> patterns;
  +
  +    @Parameters(type = File.class, // convert arguments to File before adding to the List
  +                valueLabel = "FILE", description = "files to convert")
  +    List<File> files;
  +}
  +----
  +
  +[source,java]
  +----
  +String[] args = { "-patterns", "a*b", "[a-e][i-u]", "--", "file1.txt", "file2.txt" };
  +Convert convert = CommandLine.parse(new Convert(), args);
  +assert convert.patterns.equals(Arrays.asList(Pattern.compile("a*b"),
  +                                             Pattern.compile("[a-e][i-u]")));
  +assert convert.files.equals(Arrays.asList(new File("file1.txt"), new File("file2.txt")));
  +----
  +
  +
  +=== Numeric Arguments
   Numeric values are interpreted as decimal numbers by default. If you want picocli to be more flexible, you can
  -use the https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#decode-java.lang.String-[decode] method
  -to convert strings to numbers.
  +register a custom type converter that delegates to the https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#decode-java.lang.String-[decode] method to convert strings to numbers.
   
   NOTE: The `decode` method looks at the prefix to determine the radix, so numbers
   starting with `0x`, `0X` or `#` are interpreted as hexadecimal numbers, numbers starting with `0` are interpreted
   as octal numbers, and otherwise the number is interpreted as a decimal number.
   
  -[source,java]
  -----
  - commandLine.registerConverter(Byte.class,    s -> Byte::decode);
  - commandLine.registerConverter(Short.class,   s -> Short::decode);
  - commandLine.registerConverter(Integer.class, s -> Integer::decode);
  - commandLine.registerConverter(Long.class,    s -> Long::decode);
  -----
  -
  -=== Converting to Collection Elements
  -Multiple parameters can be captured together in a single array or `Collection` field. When using a collection, use the `type` attribute to specify the collection element type. For example:
  -
  -[source,java]
  -----
  -class Convert {
  -    @Option(names = "-patterns", type = java.util.regex.Pattern.class, valueLabel = "PATTERN",
  -            description = "the regular expressions to use for the conversion");
  -    List<Pattern> patterns;
  -
  -    @Parameters(type = File.class, valueLabel = "FILE", description = "files to convert")
  -    List<File> files;
  -}
  -
  -String[] args = { "-patterns", "a*b", "[a-e][i-u]", "--", "file1.txt", "file2.txt" };
  -Convert convert = CommandLine.parse(new Convert(), args);
  -assert convert.patterns.equals(Arrays.asList(Pattern.compile("a*b"), Pattern.compile("[a-e][i-u]")));
  -assert convert.files.equals(Arrays.asList(new File("file1.txt"), new File("file2.txt")));
  -----
  -
  -IMPORTANT: With array fields picocli uses reflection to discover the array element type, but with collections, Java type erasure means picocli cannot find out the generic type of the collection. The above example uses the `type` attribute to explicitly tell picocli what type to convert the command line arguments to.
  -
  -== Required Options
  -Options can be marked `required` to make it mandatory for the user to specify them on the command line. When a required option is not specified, a `MissingParameterException` is thrown from the `parse` method. For example:
  +Java 8-style lambdas:
  +[source,java]
  +----
  +commandLine.registerConverter(Byte.class,    s -> Byte::decode);
  +commandLine.registerConverter(Short.class,   s -> Short::decode);
  +commandLine.registerConverter(Integer.class, s -> Integer::decode);
  +commandLine.registerConverter(Long.class,    s -> Long::decode);
  +----
  +
  +In Java 5 this becomes a bit more verbose:
  +[source,java]
  +----
  +commandLine.registerConverter(Byte.class,    new ITypeConverter<Byte>()   { public Byte    convert(String s) {return Byte.decode(s);}});
  +commandLine.registerConverter(Short.class,   new ITypeConverter<Short>()  { public Short   convert(String s) {return Short.decode(s);}});
  +commandLine.registerConverter(Integer.class, new ITypeConverter<Integer>(){ public Integer convert(String s) {return Integer.decode(s);}});
  +commandLine.registerConverter(Long.class,    new ITypeConverter<Long>()   { public Long    convert(String s) {return Long.decode(s);}});
  +----
  +
  +
  +== Arity
  +Arity is the number of parameters that will be consumed by an option.
  +Most of the time picocli will consume the right number of parameters automatically and you don't need to worry about this.
  +
  +When an option or parameters field has a type that can hold multiple values (an array or a collection),
  +the `arity` attribute lets you control exactly how many parameters are captured by this field.
  +
  +=== Default Arity
  +The default arity value of a field annotated with `@Option` or `@Parameters` depends on the field's type.
  +
  +* Boolean fields: arity is zero (no parameter is consumed - the field is set to `true` when the option name is recognized).
  +* Single-valued types like `int`, `String`, `File`: arity is one (consume one parameter). Omitting the option parameter results in a ParameterException: "Missing required parameter for field '<field-name>'".
  +* Multi-valued types like arrays or collections: consume from zero up to all available parameters.
  +
  +
  +=== Boolean Options with Explicit Parameters
  +It is possible to explicitly specify "true" or "false" as a parameter for a boolean option by defining an explicit <<Arity: Minimum and Maximum Number of Parameters,`arity`>> attribute. A boolean option with `arity = "0..1"` accepts zero to one parameters, `arity = "1"` means the option _must_ have one parameter. For example:
  +
  +[source, java]
  +----
  +class BooleanOptionWithParameters {
  +    @Option(names = "-x", arity = "1", description = "1 mandatory parameter")
  +    boolean x;
  +
  +    @Option(names = "-y", arity = "0..1", description = "min 0 and max 1 parameter")
  +    boolean y;
  +}
  +----
  +
  +The following ways to invoke the program will be accepted (values are not case sensitive):
  +----
  +<command> -x true
  +<command> -x FALSE
  +<command> -x TRUE -y
  +<command> -x True -y False
  +----
  +
  +But trying to specify the `-x` option without a parameter, or with a value other than "true" or "false" (case insensitive) will result in a `ParameterException`.
  +
  +=== Arrays and Collections
  +Option fields of type array or `List` (or any class extending `Collection`) will be able to hold multiple values.
  +By default, picocli will capture arguments into these fields until it encounters a command line argument that is
  +an option name or a registered command name.
  +
  +The `arity` attribute can be used to specify the exact number of required parameters, or a range with a minimum and a maximum number of parameters. The maximum can be a fixed number, or can be `"*"` to denote "any number" of parameters. For example:
   [source, java]
   ----
   class MyProgram {
       @Parameters(arity = "3", descriptions = "exactly three Files")
       File[] files;
   
  -    @Option(names = "-x", description = "optional switch")
  -    boolean x;
  -
  -    @Option(names = "-y", required = true, description = "mandatory switch")
  -    boolean y;
  -
  +    @Option(names = "-f", arity = "2..4", description = "two to four floating point numbers")
  +    double[] doubles;
  +
  +    @Option(names = "-s", arity = "1..*", description = "at least one string")
  +    String[] strings;
  +}
  +----
  +A `MissingParameterException` is thrown when fewer than the miminum number of required parameters is specified as command line arguments. Options with an exact number or an exact range will consume up to the maximum number of parameters.
  +
  +Once the minimum number of parameters is consumed, picocli will check for each subsequent command line argument whether it is another parameter, or a new option. For example:
  +
  +----
  +<command> -s A B C -f 1.0 2.0 3.0
  +----
  +The above command line arguments will be parsed as three parameters for the `-s` option, followed by three parameters for the `-f` option.
  +
  +=== Ambiguous Input
  +Positional parameters do not have an option name, so it is not always easy to decide where they start. The below example command line arguments will be parsed as six parameters for the `-s` option, not as three strings and three files:
  +----
  +<command> -s A B C file1 file2 file3
  +----
  +
  +Users can disambiguate the input by specifying a double dash (`--`) after the option parameters.
  +The argument `--` is interpreted as a delimiter indicating the end of options. Any following arguments are treated as positional parameters. For example, the following command line arguments will be parsed as three strings and three files:
  +----
  +<command> -s A B C -- file1 file2 file3
  +----
  +
  +=== Option-Parameter Separators and Arity
  +
  +IMPORTANT: A separator clarifies that a parameter belongs to an option, but does not prevent subsequent parameters from also being assigned to the same option. For example:
  +
  +[source,java]
  +----
  +@Option(names = "-opt", arity = "2") List<String> values;
  +@Parameters                          List<String> remainder;
  +----
  +Because arity is 2, both parameters in the below example are assigned to the `-opt` option:
  +----
  +<command> -opt=val1 val2
  +----
  +
  +
  +
  +== Required Options
  +=== Options
  +Options can be marked `required` to make it mandatory for the user to specify them on the command line. When a required option is not specified, a `MissingParameterException` is thrown from the `parse` method. For example:
  +[source, java]
  +----
  +class MandatoryOption {
       @Option(names = "-n", required = true, description = "mandatory number")
       int number;
  -}
  -----
  -The following command line arguments would result in an exception complaining that `y` and `number` are missing:
  -----
  -String[] args = { "-x", "file1", "file2", "file3" };
  -CommandLine.parse(new MyProgram(), args);
  +
  +    @Parameters
  +    File[] files;
  +}
  +----
  +The following command line arguments would result in an exception complaining that `number` is missing:
  +----
  +// invalid: missing option -n
  +<command> file1 file2 file3
   ----
   The following command line arguments would be accepted:
   ----
  -String[] args = { "-x", "-y", "-n", "123", "file1", "file2", "file3" };
  -CommandLine.parse(new MyProgram(), args);
  -----
  -
  -
  -IMPORTANT: if arity>1 and args="-opt=val1 val2", arity overrules the "=": both values are assigned
  +// valid: required option -n has a value
  +<command> -n 123 file1 file2 file3
  +----
  +
  +=== Parameters
  +Use the `arity` attribute to make `@Parameters` mandatory:
  +[source, java]
  +----
  +class BothOptionAndParametersMandatory {
  +    @Parameters(arity = "1..*", descriptions = "at least one File")
  +    File[] files;
  +
  +    @Option(names = "-n", required = true, description = "mandatory number")
  +    int number;
  +}
  +----
  +The following command line arguments would result in an exception complaining that `files` are missing:
  +----
  +// invalid: missing file parameters
  +<command> -n 123
  +----
  +The following command line arguments would be accepted:
  +----
  +// valid: both required fields have a value
  +<command> -n 123 file1
  +----
  +
   
   
   == Help Options
   Options with the `help` attribute set to `true` are special: if one of the command line arguments is a "help" option, picocli will stop parsing the remaining arguments and will not check for required options.
   
  +[source,java]
  +----
  +@Option(names = {"-h", "--help"}, help = true, description = "display this help message")
  +boolean helpRequested;
  +----
   This is suitable for options that should trigger the usage help message or application version information being shown on the console.
   
  -== Hidden Options and Parameters
  +It is the responsibility of the application to check the field and show the usage help message:
  +[source,java]
  +----
  +Compress app = CommandLine.parse(new App(), args);
  +if (app.helpRequested) {
  +   CommandLine.usage(new App(), System.err);
  +   return;
  +}
  +----
  +
  +== Usage Help
  +=== Example
  +=== Command Name
  +=== Parameter Labels
  +
  +=== Hidden Options and Parameters
   Options and Parameters with the `hidden` attribute set to `true` will not be shown in the usage help message.
  +
  +
  +== Customizing Usage Help
  +=== Abbreviated Synopsis
  +=== Custom Synopsis
  +=== Command Header and Description
  +=== Footer
  +=== Section Headings
  +=== Option-Parameter Separators
  +
  +
  +== Advanced Usage Help Customization
  +=== Option List with Custom Layout
  +
  +
  +
  +== Subcommands
  +=== Registering Subcommands
  +=== Usage Help for Subcommands
  +
  +
   
   == Subclassing to Reuse Options and Command Attributes
   Picocli will walk the class hierarchy to check for annotations, so you can declare common @Options and @Command attributes on a superclass and override these fields or attributes on a subclass.
  
positive.code: ----
  
  === Option-Parameter Separators
  Options may take an _option parameter_ (also called _option-argument_).
  For POSIX-style short options (like `-f` or `-c`), the option parameter may be attached to the option,
  or it may be separated by a space or the _separator string_ (`=` by default).
  
negative.code: <command> --fileoutput.txt
  ----
  
  ==== Custom Separators
  The separator string can be customized programmatically or declaratively.
  
  Use the `separator` attribute of the `@Command` annotation to declaratively set a separator string:
  [source,java]
  ----
  @Command(separator = ":")  // declaratively set a separator
  class OptionArg {
      @Option(names = { "-f", "--file" }) String file;
  }
  OptionArg optionArg = CommandLine.parse(new OptionArg(), "-f:output.txt");
  assert optionArg.file.equals("output.txt");
  ----
  
  Alternatively, the separator string can be changed programmatically with the `CommandLine.setSeparator(String separator)` method.
  For example:
  [source,java]
  ----
  OptionArg optionArg     = new OptionArg();
  CommandLine commandLine = new CommandLine(optionArg);
  
  