diff --git a/docs/pages/pmd/userdocs/cli_reference.md b/docs/pages/pmd/userdocs/cli_reference.md
index f1e380e6f5..68909b97a1 100644
--- a/docs/pages/pmd/userdocs/cli_reference.md
+++ b/docs/pages/pmd/userdocs/cli_reference.md
@@ -150,6 +150,16 @@ The tool comes with a rather extensive help text, simply running with `-help`!
     %}
 </table>
 
+## Additional Java Runtime Options
+
+PMD is executed via a Java runtime. In some cases, you might need to set additional runtime options, e.g.
+if you want to analyze a project, that uses one of OpenJDK's [Preview Language Features](http://openjdk.java.net/jeps/12).
+
+Just set the environment variable `PMD_JAVA_OPTS` before executing PMD, e.g.
+
+    export PMD_JAVA_OPTS="--enable-preview"
+    ./run.sh pmd -d ../../../src/main/java/ -f text -R rulesets/java/quickstart.xml
+
 ## Exit Status
 
 Please note that if PMD detects any violations, it will exit with status 4 (since 5.3).
diff --git a/docs/pages/pmd/userdocs/cpd.md b/docs/pages/pmd/userdocs/cpd.md
index ee3e842ea1..8545fd4fbb 100644
--- a/docs/pages/pmd/userdocs/cpd.md
+++ b/docs/pages/pmd/userdocs/cpd.md
@@ -178,11 +178,15 @@ The default format is a text report, and there's also a `csv` report.
 
 Note that CPD is pretty memory-hungry; you may need to give Java more memory to run it, like this:
 
-    $ export HEAPSIZE=512m
+    $ export PMD_JAVA_OPTS=-Xmx512m
     $ ./run.sh cpd --minimum-tokens 100 --files /usr/local/java/src/java
 
-In order to change the heap size under Windows, you'll need to edit the batch file `cpd.bat` set the "OPTS"
-variable to `-Xmx512m`.
+In order to change the heap size under Windows, you'll need to edit the batch file `cpd.bat` or
+set the environment variable `PMD_JAVA_OPTS` prior to starting CPD:
+
+    C:\ > cd C:\pmd-bin-{{site.pmd.version}}\bin
+    C:\...\bin > set PMD_JAVA_OPTS=-Xmx512m
+    C:\...\bin > .\cpd.bat --minimum-tokens 100 --files c:\temp\src
 
 
 If you specify a source directory but don't want to scan the sub-directories, you can use the non-recursive option:
diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md
index a7f700fafa..967c6f1a61 100644
--- a/docs/pages/release_notes.md
+++ b/docs/pages/release_notes.md
@@ -56,6 +56,14 @@ The designer will still be shipped with PMD's binaries.
 
 ### API Changes
 
+#### Command Line Interface
+
+The start scripts `run.sh`, `pmd.bat` and `cpd.bat` support the new environment variable `PMD_JAVA_OPTS`.
+This can be used to set arbitrary JVM options for running PMD, such as memory settings (e.g. `PMD_JAVA_OPTS=-Xmx512m`)
+or enable preview language features (e.g. `PMD_JAVA_OPTS=--enable-preview`).
+
+The previously available variables such as `OPTS` or `HEAPSIZE` are deprecated and will be removed with PMD 7.0.0.
+
 #### Deprecated API
 
 *   {% jdoc core::renderers.CodeClimateRule %} is deprecated in 7.0.0 because it was unused for 2 years and