[MCOMPILER-529] Update docs about version schema (Maven 3)

This PR updates several parts of the documentation for Maven 3 based on JDK 8 and aligns the docs to the new Java version schema. In particular on the front page it's mentioned that "8" is the default, where in the code it's actual "1.8" - but I wanted to keep docs consistent here.

Author: Bukama

src/site/apt/examples/set-compiler-release.apt.vm

@@ -28,14 +28,14 @@
 
 Setting the <<<--release>>> of the Java Compiler
 
-  Starting JDK 9, the <<<javac>>> executable can accept the <<<--release>>>
+  Starting with JDK 9, the <<<javac>>> executable can accept the <<<--release>>>
   option to specify against which Java SE release you want to build the project.
   For example, you have JDK 11 installed and used by Maven, but you want to
   build the project against Java 8.
   The <<<--release>>> option ensures that the code is compiled following the
   rules of the programming language of the specified release, and that generated
   classes target the release as well as the public API of that release. This
-  means that, unlike the
+  means that, unlike the old
   {{{../examples/set-compiler-source-and-target.html}<<<-source>>> and <<<-target>>> options}},
   the compiler will detect and generate an error when using APIs that don't exist
   in previous releases of Java SE.
@@ -76,18 +76,20 @@ Setting the <<<--release>>> of the Java Compiler
 </project>
 +-----
 
-  <<Note:>> The value in the <<<release>>> parameter follows the new version naming scheme adopted
-  since Java 9. As such, the release number does not start with 1.x anymore. Also note that the
+  <<Note:>> The value in the <<<release>>> parameter follows
+  {{{https://openjdk.org/jeps/223}Java's new Version-String Scheme (JEP 223)}}} adopted since Java 9.
+  As such, the release number does not start with 1.x anymore. Also note that the
   supported <<<release>>> targets include the release of the currently used JDK plus a limited number
   of previous releases.
 
 * Usage on JDK 8
 
-  The <<<--release>>> option is not supported using JDK 8. To enable a project that targets Java 8
-  to be built using JDK 8 and also JDK 9 or later requires the conditional usage of the
-  <<<--release>>> option.
+  The <<<--release>>> option is not supported using JDK 8.
+  However, since Compiler plugin version <<<3.13.0>>> you can use the <<<release>>> property also on JDK 8.
+  The plugin will convert it to <<<source>>> and <<<target>>> automatically.
 
-  Conditional parametrization is required for the Compiler Plugin version below <<<3.13.0>>>
+  To enable a project that targets Java 8 to be built using JDK 8 and also JDK 9 or later requires the conditional
+  usage of the <<<--release>>> option, when using a plugin version below <<<3.13.0>>>
   or compilerId different that <<<javac>>>.
 
   This may be done through the use of a profile:

src/site/apt/examples/set-compiler-source-and-target.apt.vm

@@ -28,21 +28,25 @@
 
 Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
 
+  (If you're are using version <<<3.13.0>>> or newer of the Compiler Plugin, use the recommended
+  {{{../examples/set-compiler-release.html}<<<maven.compiler.release>>> property}}.)
+
   Sometimes when you may need to compile a certain project to a different
   version than what you are currently using.  The <<<javac>>> can accept
   such command using <<<-source>>> and <<<-target>>>.  The Compiler Plugin
   can also be configured to provide these options during compilation.
+  You have to set the version following {{{https://openjdk.org/jeps/223}Java's new Version-String Scheme (JEP 223)}}}.
 
-  For example, if you want to use the Java 8 language features (<<<-source 1.8>>>)
-  and also want the compiled classes to be compatible with JVM 1.8 (<<<-target 1.8>>>),
-  you can either add the two following properties, which are the default property names for the plugin parameters:
+  For example, if you want to use the Java 8 language features and also want the compiled classes to be compatible
+  with JVM 8 (former 1.8) you can either add the two following properties, which are the default property names
+  for the plugin parameters:
 
 +-----
 <project>
   [...]
   <properties>
-    <maven.compiler.source>1.8</maven.compiler.source>
-    <maven.compiler.target>1.8</maven.compiler.target>
+    <maven.compiler.source>8</maven.compiler.source>
+    <maven.compiler.target>8</maven.compiler.target>
   </properties>
   [...]
 </project>
@@ -61,8 +65,8 @@ Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
         <artifactId>maven-compiler-plugin</artifactId>
         <version>${project.version}</version>
         <configuration>
-          <source>1.8</source>
-          <target>1.8</target>
+          <source>8</source>
+          <target>8</target>
         </configuration>
       </plugin>
     </plugins>
@@ -79,6 +83,10 @@ Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
   {{{http://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/}Animal Sniffer Maven Plugin}}
   to verify your code doesn't use unintended APIs, or better yet use the
   {{{../examples/set-compiler-release.html}<<<release>>> option supported since JDK 9}}.
+  Since plugin version <<<3.13.0>>> you can use the <<<release>>> property also on JDK 8.
+  The compiler plugin will convert it to <<<source>>> and <<<target>>> automatically.
+
   In the same way, setting the <<<source>>> option does not guarantee that your code actually compiles on a JDK with
   the specified version. To compile your code with a specific JDK version, different than the one used to launch Maven,
   refer to the {{{../examples/compile-using-different-jdk.html}Compile Using A Different JDK}} example.
+

src/site/apt/index.apt.vm

@@ -29,20 +29,16 @@
 ${project.name}
 
   The Compiler Plugin is used to compile the sources of your project. The
-  default compiler used to compile Java sources is javax.tools.JavaCompiler.
-  If you want to force the plugin to use  <<<javac>>>, you must configure the plugin option {{{./compile-mojo.html#forceJavacCompilerUse}<<<forceJavacCompilerUse>>>}}.
+  default compiler used to compile Java sources is <<<javac>>>.
+  If you want to use another compiler, refer to the {{{./non-javac-compilers} guide: Using Non-Javac Compilers}}.
 
-  Also note that at present the default <<<source>>> setting is <<<1.8>>> and the default <<<target>>>
-  setting is <<<1.8>>>, independently of the JDK you run Maven with.
-  You are highly encouraged to change these defaults by setting <<<source>>> and <<<target>>>
-  as described in
-  {{{./examples/set-compiler-source-and-target.html}Setting the -source and -target of the Java Compiler}}.
-
-  Other compilers than <<<javac>>> can be used and work has already started
-  on AspectJ, .NET, and C#.
+  At present the default <<<source>>> and the default <<<target>>> setting are both <<<8>>>,
+  independently of the JDK you run Maven with.
+  You are highly encouraged to change these defaults by setting the <<<release>>> option as described in the
+  {{{./examples/set-compiler-release.html}guide: Compile Using The <<<--release>>> javac Option}}.
 
   <<NOTE:>> <To know more about the JDK javac, please see:
-  {{https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javac.html}}.>
+  {{https://docs.oracle.com/javase/8/docs/technotes/guides/javac/index.html}}.>
 
 * Goals Overview
 
@@ -83,7 +79,7 @@ ${project.name}
 
   * {{{./examples/set-compiler-source-and-target.html}Compile Using -source and -target javac Options}}
 
-  * {{{./examples/set-compiler-release.html}Compile Using the --release javac Option (supported since JDK 9)}}
+  * {{{./examples/set-compiler-release.html}Compile Using The --release javac Option}}
 
   * {{{./examples/compile-with-memory-enhancements.html}Compile Using Memory Allocation Enhancement}}
 

src/site/site.xml

@@ -35,7 +35,7 @@ under the License.
     <menu name="Examples">
       <item name="Compile Using A Different JDK" href="examples/compile-using-different-jdk.html"/>
       <item name="Compile Using -source and -target javac Options" href="examples/set-compiler-source-and-target.html"/>
-      <item name="Compile Using the --release javac Option (JDK 9+)" href="examples/set-compiler-release.html"/>
+      <item name="Compile Using the --release javac Option" href="examples/set-compiler-release.html"/>
       <item name="Compile Using Memory Allocation Enhancements" href="examples/compile-with-memory-enhancements.html"/>
       <item name="Pass Compiler Arguments" href="examples/pass-compiler-arguments.html"/>
       <item name="Non-javac compilerIds" href="non-javac-compilers.html"/>