On Wed, 31 Jan 2024 22:10:03 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
>> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java
>> line 543:
>>
>>> 541: @Override
>>> 542: public LinkReferenceDefinition
>>> getLinkReferenceDefinition(String label) {
>>> 543: var l = label.replace("\\[\\]", "[]");
>>
>> That `String.replace` looks suspicious. FWIW, when I removed that `replace`,
>> no tests failed.
>
> My recollection is that you have to escape square brackets in a reference
> label. I will investigate, and if necessary, add a test case.
Yes, you need to escape `[` and `]` within the label of any Markdown reference
link, by preceding each with backslash. (Remember, the label is the string
used to find the URL for the link; not the displayed text of the link).
That's a CommonMark feature independent of this work.
While we could change that `replace` call into two separate ones, in reference
signatures they always appear together as a pair, and can be replaced together.
We need to remove the escape characters in the generated URL so that the
signature is a standard signature with unescaped `[]`
For fun/demo, try the following:
/// First sentence.
/// * Link 0 to [java.lang.Object]
/// * Link 1a to [Arrays-equals][java.util.Arrays#equals(Object[],Object[])]
/// * Link 1b to [Arrays-equals][java.util.Arrays#equals(Object[],Object[])]
/// * Link 2a to [java.util.Arrays#equals(Object[],Object[])]
/// * Link 2b to [java.util.Arrays#equals(Object[],Object[])]
public class C { }
Link 1a and 2a end up as unprocessed "literal" text (because the `[]` were not
escaped.) That is, they are not even recognized by the CommonMark parser as
reference links. Link 1b and 2b get processed as links, as expected.
FWIW, this issue with needing to escape `[]` pairs is specifically mentioned in
the JEP as an inescapable (sic) limitation.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473593860
