Improve documentation of "Separating Java and native image compilatio…

…n" section

Fixes: #19460

Co-authored-by: Guillaume Smet <[email protected]>

docs/src/main/asciidoc/building-native-image.adoc

@@ -632,25 +632,25 @@ For this use case, you can set the `quarkus.package.type=native-sources`.
 This will execute the java compilation as if you would have started native compilation (`-Pnative`), but stops before triggering the actual call to GraalVM's `native-image`.
 
 [source,bash]
----
+----
 $ ./mvnw clean package -Dquarkus.package.type=native-sources
----
+----
 
 After compilation has finished, you find the build artifact in `target/native-sources`:
 
 [source,bash]
----
+----
 $ cd target/native-sources
 $ ls
-native-image.args  getting-started-1.0.0-SNAPSHOT-runner.jar
----
+native-image.args  getting-started-1.0.0-SNAPSHOT-runner.jar lib
+----
 
-You see that, beside the expected JAR, a file `native-image.args` was created.
+From the output above one can see that, in addition to the produced jar file and the associated lib directory, a text file named `native-image.args` was created.
 This file holds all parameters (including the name of the JAR to compile) to pass along to GraalVM's `native-image` command.
 If you have GraalVM installed, you can start the native compilation by executing:
 
 [source,bash]
----
+----
 $ cd target/native-source
 $ native-image $(cat native-image.args)
 ...
@@ -659,14 +659,14 @@ native-image.args
 getting-started-1.0.0-SNAPSHOT-runner
 getting-started-1.0.0-SNAPSHOT-runner.build_artifacts.txt
 getting-started-1.0.0-SNAPSHOT-runner.jar
----
+----
 
 The process for Gradle is analogous.
 
 Running the build process in a container is also possible:
 
 [source,bash,subs=attributes+]
----
+----
 cd target/native-image
 docker run \
   -it \
@@ -676,28 +676,28 @@ docker run \
   --entrypoint bin/sh \
   quay.io/quarkus/ubi-quarkus-native-image:{graalvm-flavor} \ <3>
   -c "native-image $(cat native-image.args) -J-Xmx4g" <4>
----
+----
 
 <1> Mount the host's directory `target/native-image` to the container's `/work`. Thus, the generated binary will also be written to this directory.
 <2> Switch the working directory to `/work`, which we have mounted in <1>.
 <3> Use the `quay.io/quarkus/ubi-quarkus-native-image:{graalvm-flavor}` docker image introduced in <<#multistage-docker,Using a multi-stage Docker build>> to build the native image.
-<4> Call `native-image` with the content of file `native-image.args` as arguments. We also supply an additional argument to limit the process's maximum memory limitation to 4 Gigabyte.
+<4> Call `native-image` with the content of file `native-image.args` as arguments. We also supply an additional argument to limit the process's maximum memory to 4 Gigabytes (this may vary depending on the project being built and the machine building it).
 
-In a CI/CD setup, we would:
+[WARNING]
+====
+If you are running on a Windows machine, please keep in mind that the binary was created within a Linux docker container.
+Hence, the binary will not be executable on the host Windows machine.
+====
 
-1. register the output of the step executing `./mvnw ...` command (i.e. directory `target/native-image`) as build artifact,
-2. require this artifact in the step executing the `native-image ...` command, and
-3. register the output of the step executing the `native-image ...` command (i.e. files matching `target/*runner`) as build artifact.
+A CI/CD pipeline a high level overview of the various steps would look like so:
 
-The environment executing `1` only needs access to a Java- and a Maven- (or Gradle)-installation, while the environment executing `3` only needs access to a GraalVM installation (including the `native-image` feature).
+1. Register the output of the step executing `./mvnw ...` command (i.e. directory `target/native-image`) as a build artifact,
+2. Require this artifact in the step executing the `native-image ...` command, and
+3. Register the output of the step executing the `native-image ...` command (i.e. files matching `target/*runner`) as build artifact.
 
-The generated binary can then be used to create a container image, as explained above.
+The environment executing step `1` only needs Java and Maven (or Gradle) installed, while the environment executing step `3` only needs a GraalVM installation (including the `native-image` feature).
 
-[WARNING]
-===
-If you are running on a Windows machine, please keep in mind that the binary was created within a Linux docker container.
-Hence, the binary will not be executable on the host Windows machine.
-===
+Depending on what the final desired output of the CI/CD pipeline is, the generated binary might then be used to create a container image.
 
 == Debugging native executable