anchor.diff:  
   [source,java]
   ----
  - 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));
  -----
  -
  -NOTE: Numeric values are interpreted as decimal numbers by default. If you want picocli to be more flexible, you can
  +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));
  +----
  +
  +After registering custom converters, call the `parse(String...)` method on the `CommandLine` instance where the converters are registered. The static `parse` method cannot be used. For example:
  +
  +[source,java]
  +----
  +class App {
  +    @Parameters Path path;
  +    @Option(names = "-d") Duration duration;
  +}
  +CommandLine commandLine = new CommandLine(new 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);
  +assert app.path.equals(Paths.get("file1.txt"));
  +assert app.duration.equals(Duration.parse("PT15M"));
  +----
  +
  +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. The `decode` method looks at the prefix to determine the radix, so numbers
  +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.
   
  
positive.code:             description = "use archive file or device ARCHIVE")
      File archive;
  
      @Option(names = { "-v", "--verbose" }, description = "verbosely list files processed")
      boolean verbose;
  
      @Option(names = { "-h", "-?", "--help" }, help = true,
              description = "give this help list")
      boolean helpRequested;
  
      @Option(names = { "-V", "--version" }, help = true,
              description = "print program version")
      boolean versionRequested;
  
      @Parameters(valueLabel = "FILE", description = "one ore more files to archive")
      File[] files;
  }
  ----
  
  === Positional Parameters
  Positional parameters (also called operands) are the command line arguments following the options.
  Positional parameters can be captured together as an array or a List, or you can capture individual parameters in separate fields. The advantage of capturing individual parameters in separate fields is that you can enforce strong typing. For example:
  
  [source,java]
  ----
  class PositionalParameters {
      @Parameters(hidden = true) // don't show this parameter in usage help message
      List<String> allParameters;
  
      @Parameters(index = 0, valueLabel = "<host>",
                  description = "Host name or IP address to connect to")
      InetAddress host;
  
      @Parameters(index = 1, valueLabel = "<port>",
                  description = "Port number to connect to")
      int port;
  }
  ----
  
  If all parameters are the same type, you can capture them together in a single array or `Collection` field.  For example:
  
  [source,java]
  ----
  class Convert {
      @Parameters(type = File.class, valueLabel = "FILES",
                  description = "The files to convert.")
      List<File> files;
  }
  ----
  
  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.
  
  === Double dash (`--`)
  When one of the command line arguments is two dashes without any characters attached (`--`), picocli interprets all following arguments as positional parameters, even arguments that match an option name.
  
negative.code:  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:
  [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 = "-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);
  ----
  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
  
  
  == 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.
  
  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
  Options and Parameters with the `hidden` attribute set to `true` will not be shown in the usage help message.
  
  == 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.
  
  The below example shows how common options like `help` and `version` can be declared as fields in a superclass so they are available in all subclasses. Similarly, annotating the superclass with default `@Command` attributes means subclasses won't need to set these attributes.
  
  [source,java]
  ----
  @Command(synopsisHeading      = "%nUsage:%n%n",      descriptionHeading = "%nDescription:%n%n",
           parameterListHeading = "%nParameters:%n%n", optionListHeading  = "%nOptions:%n%n",
           commandListHeading   = "%nCommands:%n%n",   showDefaultValues  = false)
  public abstract class AbstractCommand {
  
      @Option(names = { "-h", "-?", "--help" }, help = true,
              description = "give this help list")
      protected boolean helpRequested;
  
      @Option(names = { "-V", "--version" }, help = true,
              description = "print program version")
      protected boolean versionRequested;
  }
  ----
  
  All commands that extend `AbstractCommand` support the `--help` and `--version` options, and generate a usage help message in the same spacious style. For example:
  
  [source,java]
  ----
  @Command(name        = "zip",
           header      = "Compresses the specified FILE(s).",
           description = "The default action is to add or replace zipfile entries from list, " +
                         "which can include the special name - to compress standard input.",
           footer      = "Copyright (c) 1990-2008 Info-ZIP - Type 'zip "-L"' for software license.")
  public class ZipCommand extends AbstractCommand {
      @Option(names = { "-o", "--output" }, description = "output file to write to")
      private File output;
  
      @Parameter(valueLabel = "FILE", description = "FILEs to compress")
      private File[] files;
  }
  ----
  
  
  == Putting it all Together
  Imagine an application that takes some input files and compresses them to an output file.
  