Release notes and documentation polishing

Java 11 is out now, so replace the "expected to work in" with "works in".

Call attention to Oracle's licensing change in Java 11.

Clarify the considerations around building from unreleased snapshot
sources, and how to determine the branch with most recent activity.

Add a note on the SQL syntax needed to call the Saxon-based example
functions as one travels back through PostgreSQL versions.

Mention issue #190 and suggest a workaround for builders of packages
for Windows.

src/site/markdown/build/build.md

@@ -117,6 +117,12 @@ sources.
 From a clone, you can also build specific released versions, by first
 using `git checkout` with the tag that identifies the release.
 
+Building from unreleased, development sources will be of most interest when
+hacking on PL/Java itself. The GitHub "Branches" page can be used to see which
+branch has had the most recent development activity (this will not always be
+the branch named `master`; periods of development can be focused on the branch
+corresponding to current releases).
+
 [git]: https://git-scm.com/
 
 ## The build

src/site/markdown/build/package.md

@@ -21,14 +21,22 @@ where the `...` is the path to the JVM library shared object where it
 would be by default on your target platform. See [here][locatejvm] to find
 the exact file this should refer to.
 
-[locatejvm]: ../install/locatejvm.html
-
 Although PL/Java is currently built with a JDK no later than Java 8, it can
 then run in the database with a newer JVM, and support application code that
 uses the newer Java features. While using Java 8 to build a package, you are
 encouraged to set the default `pljava.libjvm_location` to the library of a
 later JRE that is expected to be present on your platform.
 
+**Note:** when building on Windows, the `-Dpljava.libjvmdefault` option is
+likely to produce a failed build or the wrong stored value for the library
+path. A fix for this option on Windows is unlikely (see [issue 190][bug190]);
+if preparing a package for Windows, it will be simplest to use a patch that
+changes the definition of `PLJAVA_LIBJVMDEFAULT` in
+`pljava-so/src/main/c/Backend.c`.
+
+[locatejvm]: ../install/locatejvm.html
+[bug190]: https://github.com/tada/pljava/issues/190
+
 ## What kind of a package is this?
 
 Your package may be for a distribution that has formal guidelines for how

src/site/markdown/build/versions.md

@@ -1,15 +1,18 @@
 # Versions of external packages needed to build and use PL/Java
 
-As of August 2018, the following version constraints are known.
+As of October 2018, the following version constraints are known.
 
 ## Java
 
 No version of Java before 1.6 ("Java 6") is supported. The PL/Java code
 makes use of Java features first appearing in Java 6.
 
 As for later versions of Java, backward compatibility in the language is
-generally good. The most likely problem areas with a new Java version will
-be additions to the JDBC API that PL/Java has not yet implemented.
+generally good. Before Java 8, most likely problem areas with a new Java
+version tended to be additions to the JDBC API that PL/Java had not yet
+implemented. Since Java 8, even JDBC additions have not caused problems for
+existing PL/Java code, as they have taken advantage of the default-methods
+feature introduced in that release.
 
 In the PL/Java 1.5.x series, the build system has not been reworked for
 building with Java 9 or newer. However, PL/Java can be built with Java 8

src/site/markdown/examples/saxon.md

@@ -148,6 +148,15 @@ of an empty sequence. This lacks, for now, some functionality of the standard
 `XMLTABLE`, where the default expression can refer to other columns of the
 same output row.
 
+#### Syntax in older PostgreSQL versions
+
+The desugared syntax shown above can be used in PostgreSQL versions as old
+as 9.5. In 9.4 and 9.3, the same syntax, but with `=>` replaced by `:=` for
+the named parameters, can be used. The functions remain usable in still
+earlier PostgreSQL versions, but with increasingly convoluted SQL syntax
+needed to call them (before 9.3, for example, there was no `LATERAL` in a
+`SELECT`, a function could not refer to earlier `FROM` items, and so on).
+
 ### Minimizing startup time
 
 Saxon is a large library, and benefits greatly from precompilation into a

src/site/markdown/install/appcds.md

@@ -18,6 +18,7 @@ feature is covered [on its own page][cdsJ9].
 [bcl]: http://www.oracle.com/technetwork/java/javase/terms/license/index.html
 [OpenJDK]: https://adoptopenjdk.net/
 [cdsJ9]: oj9vmopt.html#How_to_set_up_class_sharing_in_OpenJ9
+[o]: https://blogs.oracle.com/java-platform-group/oracle-jdk-releases-for-java-11-and-later
 
 ## License considerations
 
@@ -34,16 +35,31 @@ additional performance margin can be given a price.
 
 The same feature in OpenJDK with Hotspot is available from Java 10 onward,
 and does not require any additional license or `-XX:+UnlockCommercialFeatures`
-option. The equivalent feature in OpenJDK with OpenJ9,
-[described separately][cdsJ9] is available from Java 8 onward, also with no
+option.
+
+Starting in Java 11, Oracle offers
+[Oracle-branded downloads of both "Oracle JDK" and "Oracle's OpenJDK builds"][o]
+that are "functionally identical aside from some cosmetic and packaging
+differences". "Oracle's OpenJDK builds" may be used for production or
+commercial purposes with no additional licensing, while any such use of
+"Oracle JDK" requires a commercial license. The application class data sharing
+feature is available in both, and no longer requires the
+`-XX:+UnlockCommercialFeatures` option in either case (not in
+"Oracle's OpenJDK builds" because their use is unrestricted, and not in
+"Oracle JDK" because the "commercial feature" is now, effectively, the entire
+JDK).
+
+The equivalent feature in OpenJDK with OpenJ9,
+[described separately][cdsJ9], is available from Java 8 onward, also with no
 additional license or setup needed.
 
 ## Setup
 
 The setup instructions on this page are for Hotspot, whether in Oracle Java
 or OpenJDK with Hotspot. The two differ only in that, wherever an
 `-XX:+UnlockCommercialFeatures` option is shown in the steps below,
-**it is needed in Oracle Java but not in OpenJDK/Hotspot**.
+**it is needed in Oracle Java 8, 9, or 10, but not in OpenJDK/Hotspot, or
+Oracle JDK 11 or later**.
 
 Setting up PL/Java to use application class data sharing is a three-step
 process. Each step is done by setting a different combination of options

src/site/markdown/install/vmoptions.md

@@ -110,6 +110,17 @@ is available and set up in the same way, but is freely usable; it does not
 require any additional license, and does not require any
 `-XX:+UnlockCommercialFeatures` to be added to the options.
 
+Starting in Java 11, Oracle offers
+[Oracle-branded downloads of both "Oracle JDK" and "Oracle's OpenJDK builds"][o]
+that are "functionally identical aside from some cosmetic and packaging
+differences". "Oracle's OpenJDK builds" may be used for production or
+commercial purposes with no additional licensing, while any such use of
+"Oracle JDK" requires a commercial license. The application class data sharing
+feature is available in both, and no longer requires the
+`-XX:+UnlockCommercialFeatures` in either case (not in "Oracle's OpenJDK builds"
+because their use is unrestricted, and not in "Oracle JDK" because the
+"commercial feature" is now, effectively, the entire JDK).
+
 [In OpenJDK (with OpenJ9)][OpenJDK], the class-sharing feature present from
 Java 8 onward will naturally share PL/Java's classes as well as the Java
 runtime's, with no additional setup steps.
@@ -128,6 +139,7 @@ classes!) in OpenJ9][cdsJ9].
 [iads]: appcds.html
 [vmoptJ9]: oj9vmopt.html
 [cdsJ9]: oj9vmopt.html#How_to_set_up_class_sharing_in_OpenJ9
+[o]: https://blogs.oracle.com/java-platform-group/oracle-jdk-releases-for-java-11-and-later
 
 ## `-XX:+DisableAttachMechanism`
 

src/site/markdown/releasenotes.md.vm

@@ -83,10 +83,9 @@ $h3 Version compatibility
 
 PL/Java 1.5.1 can be built against recent PostgreSQL versions including 11beta4,
 and older ones back to 8.2, using Java SE 8, 7, or 6. It can _run_ using newer
-Java versions including Java 10 (and is expected to work with Java 11 when that
-is released). PL/Java functions can be written for, and use features of, the
-Java version loaded at run time. See [version compatibility][versions] for more
-detail.
+Java versions including Java 11. PL/Java functions can be written for, and use
+features of, the Java version loaded at run time. See
+[version compatibility][versions] for more detail.
 
 OpenJDK is supported, and can be downloaded in versions using the Hotspot or the
 OpenJ9 JVM. Features of modern Java VMs can drastically reduce memory footprint
@@ -363,6 +362,7 @@ $h4 Since 1.5.1-BETA2
 * [java.lang.ClassNotFoundException installing examples jar](${ghbug}178)
 * [Preprocessor errors building on Windows with MSVC](${ghbug}182)
 * [Saxon example does not build since Saxon 9.9 released](${ghbug}185)
+* [Segfault in VarlenaWrapper.Input on 32-bit](${ghbug}177)
 
 $h4 In 1.5.1-BETA2