RFR: 8306980: Generated docs should contain correct GPLv2 Legal Documents [v2]

[Jonathan Gibbons]

On Thu, 11 May 2023 08:50:55 GMT, KIRIYAMA Takuya <duke at openjdk.org> wrote:

>> I modified the location from which javadoc copies some legal files to the generated documentation.  If --legal-notices　option is set to default or nothing is specified,, GPLv2 Legal Documents are copied from legal/java.base/ directory, such as LICENSE, ADDITIONAL_LICENSE_INFO and ASSEMBLY_EXCEPTION.
>> 
>> Would you please review this fix?
>
> KIRIYAMA Takuya has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8306980: Generated docs should contain correct GPLv2 Legal Documents

I still (strongly) dislike baking such specific knowledge of the legal files into the javadoc tool. That's just conceptually wrong.

It turns out these files are generated by the `jlink` tool, which somewhat weirdly generates these "descriptive links" to use instead of symbolic links on platforms that do not support symbolic links.

See [jlink DefaultImageBuilder writeSymLinkEntry](https://github.com/openjdk/jdk/blob/aff9cea05468daf60fa80c7d9993b3aa8497b0c5/src/jdk.jlink/share/classes/jdk/tools/jlink/builder/DefaultImageBuilder.java#L469)

In the absence of being able to change this `jlink` behavior, maybe we can work around it.
Instead of baking knowledge of the names and locations of specific files into the Standard Doclet, one possibility would be to read the file, and if it exactly matches `Please see .*\R` then we could substitute the contents of the named file.

In other words, the logic becomes roughly


var s = Files.readString(path);
if (s _matches_ "Please see (.*)\\R") {. // follow jlink descriptive links
    path = Path.of(_specified-file_);
    s = Files.readString(path);
}
Files.writeString(_target_, s);

-------------

Changes requested by jjg (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/13686#pullrequestreview-1458520248