Document System.exit usage

docs/index.adoc

@@ -3620,6 +3620,8 @@ fun main(args: Array<String>) {
 
 CAUTION: Older versions of picocli had some limited exit code support where picocli would call `System.exit`, but this is now deprecated.
 
+There are cases where calling `System.exit` is not ideal. See <<Usage of `System.exit`>> for details.
+
 === Generating an Exit Code
 
 `@Command`-annotated classes that implement `Callable` and `@Command`-<<command-methods,annotated methods>> can simply return an `int` or `Integer`, and this value will be returned from `CommandLine.execute`. For example:
@@ -11401,6 +11403,22 @@ Multi-line text blocks can be used in command and option descriptions, headers a
 
 For more details, see https://www.infoq.com/articles/java-text-blocks/[this article] by Java Language Architect Brian Goetz.
 
+=== Usage of `System.exit`
+
+When an application runs as an independent process, `System.exit` returns an exit code to the caller.
+On the other hand, when an application runs as part of the caller process, `System.exit` halts the caller process and ends up an abrupt finish.
+
+For example, picocli based <<TAB Autocomplete,TAB AutoComplete application>> solves this problem by having link:autocomplete.html#_maven_example[a system property] to determine whether to call `System.exit`.
+
+Another use case is https://www.mojohaus.org/exec-maven-plugin/[`exec-maven-plugin`] with https://www.mojohaus.org/exec-maven-plugin/java-mojo.html[`exec:java` goal].
+This goal invokes the target class on the same maven process.
+The `System.exit` call finishes maven process bypassing the rest of the maven steps including its error handlings.
+
+In such scenarios, you should use `parseArgs` instead.
+You can control whether to propagate the exception to the caller.
+Then, the caller(e.g. maven process) can perform its exception handlings.
+See <<DIY Command Execution>> for details.
+
 
 == Dependency Injection