From 5096830b45bdaa2dd20f05897870f9c7767b1d96 Mon Sep 17 00:00:00 2001 From: Chapman Flack Date: Wed, 5 Mar 2025 13:46:53 -0500 Subject: [PATCH 1/2] Assume javadoc-21 form of URLs into Javadoc While PL/Java's docs are meant to build (mvn site site:stage) without failure on any Java version supported for building PL/Java, there have been changes over the Javadoc versions to things like the output directory structure and the spelling of anchor names for use as URL fragment IDs. Therefore, it's necessary to pick a version of Javadoc to be used when generating the docs if such things as links from the Markdown documents into the generated javadocs are to work right. Links from the generated javadocs to Oracle's published JDK javadocs are made to the Java 12 pages as a practical compromise: PL/Java 1.6.x is built for compatibility back to Java 9, but Oracle's published pages for Java 12 are the earliest to have the organization expected by a modern Javadoc. The PL/Java examples (non-modular code) have Javadoc links back to the PL/Java API (modular code), which Javadoc before 15 doesn't know how to do. Later Javadoc versions have some further aesthetic improvements. For now, assume that Javadoc 21 (the recent LTS version) will be used for generating the site javadocs, and adjust the URLs that point into the javadocs accordingly. --- src/site/markdown/develop/node.md | 2 +- src/site/markdown/index.md | 2 +- src/site/markdown/releasenotes.md.vm | 14 +++++++------- src/site/markdown/use/hello.md.vm | 2 +- src/site/markdown/use/jpms.md | 2 +- src/site/markdown/use/unenforced.md | 2 +- src/site/markdown/use/use.md | 2 +- 7 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/site/markdown/develop/node.md b/src/site/markdown/develop/node.md index aaf13e9d4..9cb80ba52 100644 --- a/src/site/markdown/develop/node.md +++ b/src/site/markdown/develop/node.md @@ -453,4 +453,4 @@ a complaint from the `netty` library about Java (correctly!) denying it access to private internals. [jshell]: https://docs.oracle.com/en/java/javase/15/jshell/introduction-jshell.html -[nodeapi]: ../pljava-packaging/apidocs/org/postgresql/pljava/packaging/Node.html#method.summary +[nodeapi]: ../pljava-packaging/apidocs/org/postgresql/pljava/packaging/Node.html#method-summary diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index 983395818..27dfaf763 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -49,7 +49,7 @@ use. [JDBC]: https://docs.oracle.com/javase/tutorial/jdbc/ [pljapi]: pljava-api/apidocs/org.postgresql.pljava/module-summary.html [annotations]: https://docs.oracle.com/javase/tutorial/java/annotations/ -[oppa]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/annotation/package-summary.html#package_description +[oppa]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/annotation/package-summary.html#package-description [trgann]: https://github.com/tada/pljava/blob/master/pljava-examples/src/main/java/org/postgresql/pljava/example/annotation/Triggers.java [depdesc]: https://github.com/tada/pljava/wiki/Sql-deployment-descriptor [jar]: https://docs.oracle.com/javase/tutorial/deployment/jar/index.html diff --git a/src/site/markdown/releasenotes.md.vm b/src/site/markdown/releasenotes.md.vm index 66f722c6f..d6ba07f2d 100644 --- a/src/site/markdown/releasenotes.md.vm +++ b/src/site/markdown/releasenotes.md.vm @@ -247,8 +247,8 @@ $h3 Bugs fixed * [`NEWLINE` pattern can fail to match](${ghbug}455) -[adjlax]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/Adjusting.XML.Parsing.html#method.summary -[adjsfs]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/Adjusting.XML.html#method.detail +[adjlax]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/Adjusting.XML.Parsing.html#method-summary +[adjsfs]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/Adjusting.XML.html#method-detail [egsfs]: https://github.com/tada/pljava/blob/V1_6_6/pljava-examples/src/main/java/org/postgresql/pljava/example/annotation/PassXML.java#L528 $h2 PL/Java 1.6.5 @@ -405,7 +405,7 @@ $h3 Bugs fixed * [Set-returning function has context classloader set too many times](${ghbug}389) * [`java.time.LocalDate` mismapping within 30 years of +/-infinity](${ghbug}390) -[exoneout]: pljava-examples/apidocs/org/postgresql/pljava/example/annotation/ReturnComposite.html#method.summary +[exoneout]: pljava-examples/apidocs/org/postgresql/pljava/example/annotation/ReturnComposite.html#method-summary $h2 PL/Java 1.6.3 (10 October 2021) @@ -575,7 +575,7 @@ $h3 Credits Thanks to Francisco Biete for the report of [#331](${ghbug}331). -[PassXML]: pljava-examples/apidocs/org/postgresql/pljava/example/annotation/PassXML.html#method.summary +[PassXML]: pljava-examples/apidocs/org/postgresql/pljava/example/annotation/PassXML.html#method-summary $h2 PL/Java 1.6.1 (16 November 2020) @@ -635,8 +635,8 @@ $h3 Bugs fixed * [1.6.0: opening a ResourceBundle (or a resource) fails](${ghbug}322) * [Better workaround needed for javac 10 and 11 --release bug](${ghbug}328) -[outprm]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/annotation/Function.html#annotation.type.element.detail -[outprmeg]: pljava-examples/apidocs/org/postgresql/pljava/example/annotation/ReturnComposite.html#method.detail +[outprm]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/annotation/Function.html#annotation-interface-element-detail +[outprmeg]: pljava-examples/apidocs/org/postgresql/pljava/example/annotation/ReturnComposite.html#method-detail [agganno]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/annotation/Aggregate.html [castanno]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/annotation/Cast.html [opranno]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/annotation/Operator.html @@ -837,7 +837,7 @@ continuous integration was supported by Google Summer of Code. [linkage]: examples/examples.html#Exception_resolving_class_or_method_.28message_when_installing_examples.29 [udtd32f84e]: https://github.com/jcflack/pljava-udt-type-extension/commit/d32f84e [udt0066a1e]: https://github.com/jcflack/pljava-udt-type-extension/commit/0066a1e -[variadic]: pljava-examples/apidocs/org/postgresql/pljava/example/annotation/Variadic.html#method.detail +[variadic]: pljava-examples/apidocs/org/postgresql/pljava/example/annotation/Variadic.html#method-detail [charsets]: use/charsets.html [jpms]: use/jpms.html diff --git a/src/site/markdown/use/hello.md.vm b/src/site/markdown/use/hello.md.vm index fa3cb1c49..9731671d8 100644 --- a/src/site/markdown/use/hello.md.vm +++ b/src/site/markdown/use/hello.md.vm @@ -463,6 +463,6 @@ From here, consider: * The user guide pages [on the wiki][uwik] * The many pre-built [examples][] -[pljapi]: ../pljava-api/apidocs/index.html?org/postgresql/pljava/package-summary.html#package_description +[pljapi]: ../pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/package-summary.html#package-description [uwik]: https://github.com/tada/pljava/wiki/User-guide [examples]: ../examples/examples.html diff --git a/src/site/markdown/use/jpms.md b/src/site/markdown/use/jpms.md index 300b84121..4770e06a3 100644 --- a/src/site/markdown/use/jpms.md +++ b/src/site/markdown/use/jpms.md @@ -160,5 +160,5 @@ character. [limitmods]: https://openjdk.org/jeps/261#Limiting-the-observable-modules [unenforced]: unenforced.html [examples]: ../examples/examples.html -[java_modules]: ../pljava-examples/apidocs/index.html?org/postgresql/pljava/example/annotation/Modules.html +[java_modules]: ../pljava-examples/apidocs/org/postgresql/pljava/example/annotation/Modules.html#method-detail [node]: ../develop/node.html diff --git a/src/site/markdown/use/unenforced.md b/src/site/markdown/use/unenforced.md index 1cec7493f..82636be18 100644 --- a/src/site/markdown/use/unenforced.md +++ b/src/site/markdown/use/unenforced.md @@ -242,5 +242,5 @@ modification would otherwise result). [limiting]: jpms.html#Limiting_the_module_graph [mappedudt]: ../pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/annotation/MappedUDT.html [examples]: ../examples/examples.html -[java_modules]: ../pljava-examples/apidocs/index.html?org/postgresql/pljava/example/annotation/Modules.html +[java_modules]: ../pljava-examples/apidocs/org/postgresql/pljava/example/annotation/Modules.html#method-detail [smprop]: ../install/smproperty.html diff --git a/src/site/markdown/use/use.md b/src/site/markdown/use/use.md index 547ac462b..a370ebd33 100644 --- a/src/site/markdown/use/use.md +++ b/src/site/markdown/use/use.md @@ -119,7 +119,7 @@ PL/Java will work most seamlessly when the server encoding in PostgreSQL is `UTF8`. For other cases, please see the [character encoding notes][charsets]. [hello]: hello.html -[pljapi]: ../pljava-api/apidocs/index.html?org/postgresql/pljava/package-summary.html#package_description +[pljapi]: ../pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/package-summary.html#package-description [uwik]: https://github.com/tada/pljava/wiki/User-guide [examples]: ../examples/examples.html [charsets]: charsets.html From e8121eeeb4af2baebe877f18661a915117495af6 Mon Sep 17 00:00:00 2001 From: Chapman Flack Date: Wed, 5 Mar 2025 15:03:24 -0500 Subject: [PATCH 2/2] Likewise update releasenotes-pre1_6 A slightly Orwellian feeling is probably no important reason not to also fix links in releasenotes-pre1_6 so they aren't broken when the docs are built with a present-day javadoc. There will still be unavoidable breakage given that anchor names for functions are generated by recent Javadoc versions to include parentheses, which are sanitized out of links by Velocity's Markdown processor. --- src/site/markdown/releasenotes-pre1_6.md.vm | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/site/markdown/releasenotes-pre1_6.md.vm b/src/site/markdown/releasenotes-pre1_6.md.vm index 405b1a9a1..730a7deb1 100644 --- a/src/site/markdown/releasenotes-pre1_6.md.vm +++ b/src/site/markdown/releasenotes-pre1_6.md.vm @@ -688,7 +688,7 @@ the Saxon-HE XML-processing library) provides a partial implementation of true `XMLQUERY` and `XMLTABLE` functions for PostgreSQL, using the standard-specified XML Query language rather than the XPath 1.0 of the native PostgreSQL functions. -[exxml]: pljava-examples/apidocs/index.html?org/postgresql/pljava/example/annotation/PassXML.html +[exxml]: pljava-examples/apidocs/org/postgresql/pljava/example/annotation/PassXML.html [exsaxon]: examples/saxon.html $h4 New Java property exposes the PostgreSQL server character-set encoding @@ -767,7 +767,7 @@ to PostgreSQL, and there has not been a way to suppress the row operation. The `TriggerData` interface now has a [`suppress`][tgsuppress] method that the trigger can invoke to suppress the operation for the row. -[tgsuppress]: pljava-api/apidocs/index.html?org/postgresql/pljava/TriggerData.html#suppress() +[tgsuppress]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/TriggerData.html#suppress() $h4 Constraint triggers @@ -1076,7 +1076,7 @@ functions, triggers, and user-defined types, both base and composite. [user]: use/use.html [hello]: use/hello.html [exanno]: $project.scm.url/pljava-examples/src/main/java/org/postgresql/pljava/example/annotation -[apianno]: pljava-api/apidocs/index.html?org/postgresql/pljava/annotation/package-summary.html#package_description +[apianno]: pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/annotation/package-summary.html#package-description The history of this feature in PL/Java is long, with the first related commits appearing in 2005, six years in advance of an enhancement request for it. @@ -1164,7 +1164,7 @@ of major version because the prior API, while deprecated, is still available. and ignore the role should be rare, and should be discussed on the mailing list or opened as issues. -#set($sessapi = 'pljava-api/apidocs/index.html?org/postgresql/pljava/Session.html#') +#set($sessapi = 'pljava-api/apidocs/org.postgresql.pljava/org/postgresql/pljava/Session.html#') [goun]: ${sessapi}getOuterUserName() [eaou]: ${sessapi}executeAsOuterUser(java.sql.Connection,java.lang.String)