anchor.diff:  
   [source,java]
   ----
  -Example app = CommandLine.parse(new Example(), "-v", "inputFile1", "inputFile2");
  +String[] args = { "-v", "inputFile1", "inputFile2" };
  +Example app = CommandLine.parse(new Example(), args);
   assert !app.helpRequested;
   assert  app.verbose;
   assert  app.inputFiles != null && app.inputFiles.length == 2;
   ----
   
   == Options and Parameters
  -Options have a name, positional parameters (sometimes called operands) come after the named options.
  -There are no hard and fast rules for when to use options or parameters,
  -but a common theme seems to be that options are optional and parameters are used for mandatory values.
  +Command line arguments can be separated into _options_ (sometimes called _flags_ or _switches_), and _parameters_ (sometimes called _positional parameters_ or _operands_).
  +Options have a name, parameters are the values that follow the options.
  +
  +[source]
  +----
  +<command> -cvf=file1.txt --out result.txt abc def 123 45.6
  +            |      |        |       |      |   |   |   |
  +            |      |        |       |      +---+---+---+--- positional parameters
  +            |      |        |       |
  +            |      |        |       +--- option-parameter for "--out"
  +            |      |        |
  +            |      |        +--- "--out" long option (separated from its parameter)
  +            |      |
  +            |      +--- option-parameter for the "-f" option (attached with '=')
  +            |
  +            +--- three short options ("-c", "-v", "-f") clustered together
  +----
  +Picocli has separate annotations for options and positional parameters because they work slightly differently.
  +
  +.Best Practices
  +[TIP]
  +When designing your command line application you may wonder which arguments to capture in options and which arguments to capture as parameters. While there are no hard and fast rules, a common theme seems to be that options are optional and parameters are used for mandatory values.
   Picocli lets you make options required if you want to, see <<Required Options>>.
  -
  -TIP: The https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html#Command_002dLine-Interfaces[GNU recommendations] for command line interfaces and http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02[POSIX Utility Guidelines] may be useful.
  +The https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html#Command_002dLine-Interfaces[GNU recommendations] for command line interfaces and http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02[POSIX Utility Guidelines] may be useful.
   
   === Options
  -An option can have multiple names. Options usually have a prefix to distinguish them from parameters. There are many different prefixes and different option naming https://en.wikipedia.org/wiki/Command-line_interface#Command-line_option[styles]. Picocli lets you use any style you want.
  +An option must have one or more `names`. Option names usually have a prefix to distinguish them from parameters. Different operating systems and applications use https://en.wikipedia.org/wiki/Command-line_interface#Command-line_option[different prefixing] styles. Picocli lets you use any style you want.
   
   TIP: You may be interested in this http://catb.org/~esr/writings/taoup/html/ch10s05.html#id2948149[list of common option names]. Following these conventions may make your application more intuitive to use.
   
  -The below uses the popular utility `tar` as an example to show how one could use picocli to code options with one or more names, options that take an option parameter, positional parameters, and "help" options.
  +The below example shows options with one or more names, options that take an option parameter, and "help" options.
   [source,java]
   ----
   class Tar {
  
positive.code: :toc-title: Features
  
  A Java command line parsing framework in a single file, so you can include it _in source form_
  and your users can run your application without an external dependency.
  Produces beautiful and easily tailored usage help messages.
  
  How it works: annotate your class and picocli initializes it from the command line arguments,
  
negative.code:             description = "use archive file or device ARCHIVE")
      File archive;
  
      @Parameters(valueLabel = "FILE", description = "one ore more files to archive")
      File[] files;
  }
  
  String[] args = { "-cf", "result.tar", "file1.txt", "file2.txt" };
  Tar tar = CommandLine.parse(new Tar(), args);
  assert  tar.create;
  assert !tar.extract;
  assert  tar.archive.equals(new File("result.tar"));
  assert  Arrays.equals(tar.files, new File[] {new File("file1.txt"), new File("file2.txt")});
  ----
  
  Picocli supports http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02[POSIX clustered short options]:
  One or more options without option-arguments, followed by at most one option that takes an option-argument, should be accepted when grouped behind one '-' delimiter.
  
  
  For example, given this annotated class:
  [source,java]
  ----
  class ClusteredShortOptions {
      @Option(names = "-a") boolean a;
      @Option(names = "-b") boolean b;
      @Option(names = "-c") boolean c;
      @Option(names = "-f") String  f;
  }
  ----
  The following command line arguments are all equivalent and parsing them will give the same result:
  
  [source,java]
  ----
  <command> -abcfInputFile.txt
  <command> -a -b -c -fInputFile.txt
  <command> -a -b -c -f InputFile.txt
  <command> -a -b -c -f=InputFile.txt
  <command> -ab -cf=InputFile.txt
  ...
  ----
  
  
  === Positional Parameters
  Positional parameters (also called operands) are the command line arguments following the options.
  
  Use the (zero-based) `index` attribute to specify exactly which parameters to capture. Omitting the `index` attribute means the field is initialized with all positional parameters (so the field should be an array or a collection).
  The `index` attribute accepts "range" values, so an annotation like `@Parameters(index="2..4")` captures arguments at index 2, 3 and 4. Range values can be open-ended. For example, `@Parameters(index="3..*")` captures all arguments from index 3 and up.
  
  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)  // "hidden": don't show this parameter in usage help message
      List<String> allParameters; // no "index" attribute: captures _all_ arguments (as Strings)
  
      @Parameters(index = "0", valueLabel = "<host>", // index=0: the first positional parameter
                  description = "Host name or IP address to connect to")
      InetAddress host;
  
      @Parameters(index = "1", valueLabel = "<port>", // index=1: the second positional parameter
                  description = "Port number to connect to")
      int port;
  
      @Parameters(index = "2..*", valueLabel = "<files>", description = "the files to process")
      File[] files;
  }
  
  String[] args = { "localhost", "12345", "file1.txt", "file2.txt" };
  PositionalParameters params = CommandLine.parse(new PositionalParameters(), args);
  assert params.host.getHostName().equals("localhost");
  assert params.port == 12345;
  assert Arrays.equals(params.files, new File[] {new File("file1.txt"), new File("file2.txt")});
  assert params.allParameters.equals(Arrays.asList("localhost", "12345", "file1.txt", "file2.txt"));
  ----
  
  See <<Type Conversion>> for which types are supported out of the box and how to add custom types.
  
  === 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.
  