[remkop#1428] DOC: make a note about subcommands with the same name a…

…s a default value

docs/index.adoc

@@ -8595,6 +8595,31 @@ class Git : Runnable {
 By default, the synopsis of a command with subcommands shows a trailing `[COMMAND]`, indicating that a subcommand can optionally be specified.
 To show that the subcommand is mandatory, use the `synopsisSubcommandLabel` attribute to replace this string with `COMMAND` (without the `[` and `]` brackets).
 
+=== Subcommands and default values
+
+There are some scenarios where picocli can not parse an option with a default value which is the same as a subcommand name. To work around this, you can parse the option yourself using <<Custom Parameter Processing,`IParameterConsumer`>>. A simple implementation is shown below. See https://github.com/remkop/picocli/issues/1428[this issue] for more details.
+
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+class MyParameterConsumer : CommandLine.IParameterConsumer {
+  override fun consumeParameters(
+    args: Stack<String>,
+    argSpec: CommandLine.Model.ArgSpec,
+    commandSpec: CommandLine.Model.CommandSpec
+  ) {
+    if (args.isEmpty()) {
+      throw CommandLine.ParameterException(
+        commandSpec.commandLine(),
+        "Missing required parameter for option " +
+            (argSpec as CommandLine.Model.OptionSpec).longestName()
+      )
+    }
+    argSpec.setValue(args.pop());
+  }
+}
+----
 
 == Reuse
 You may find yourself defining the same options, parameters or command attributes in many command line applications.