Confusion between link target and displayed text when link?

[jerstlouis]

In OGC API - Maps, Annex B / Section 2 we noticed the following.

A link in the ASCIIDoc is written as:

https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json[https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal]

The intent was to show the link to the reader without the ?f=json, while resulting in the JSON representation of the resource being returned if the reader clicks on the link. This is because f is not a standard parameter but an alternative to an Accept: application/json request header that cannot be specified in a URL.

The current behavior is not as expected, and is opposite between the HTML and the PDF rendering of the document (with both behaviors unexpected).

• The HTML document shows the link as https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal and links to https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal without the ?f=json
• The PDF document shows the link as https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json and links to https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json
• The expected behaviors in both cases would be to show the link as https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal but link to https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json

Is there some special logic which tries to determine whether the linked text is itself a link which is behind these unexpected behaviors? I would just expect the text to be written as-is -- that's the whole point of explicitly specifying a link as opposed to just writing the URL and having it automatically turned into a link.

[ronaldtse]

Thanks @jerstlouis for the report.

Do you happen to know what the XML encoding of this link is? There is clearly a bug there... Thanks!

[jerstlouis]

@ronaldtse quite interestingly it has TWO nested <link> tags:

<p id="_711a69b2-5c0b-e0d9-04ae-4d97b2bd5ba3">
   <link target="https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json">
      <link target="https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal"/>
   </link>
</p>

A fix would be to either consistently use the target of the inner link as the text, and use the outer link for the generated link target in both the PDF and HTML rendering, OR to not generate an inner link but directly using the text when generating the XML.

[Intelligent2013]

@jerstlouis the similar issue was reported in #664. The solution is - escape https by \ in the brackets:

https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json[\https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal]

Sample rendering in PDF:

[jerstlouis]

@Intelligent2013 Thank you for the work-around.

Since the metanorma PDF and HTML renderings are inconsistent, I would still consider this a bug.

This does seem to be related to #664, which I just finally wrapped my head around (see #664 (comment)) and applied the work-around.

Ideally, anything inside of the text supplied for a link should disable any kind of link extraction for the text inside the [ ].

I realize that ASCIIDoc itself seems broken in that regard, but metanorma behaves differently in requiring this extra \ (which renders as an actual \ with asciidoctor-pdf).

From the perspective of the intermediate metanorma XML, ideally this <link/> inside another <link> should never be generated. And the rendering to HTML / PDF of that broken XML should also ideally be consistent.

This is what works with asciidoctor-pdf:

https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json[https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal]

https://maps.gnosis.earth/ogcapi/collections/blueMarble/map?bbox-crs=%5BEPSG:3395%5D&bbox=-4596385.263861,2080129.089271,4596385.263861,11273386.415933&crs=%5BEPSG:3395%5D["https://maps.gnosis.earth/ogcapi/collections/blueMarble/map?bbox-crs=[EPSG:3395\]&bbox=-4596385.263861,2080129.089271,4596385.263861,11273386.415933&crs=[EPSG:3395\]"]

and this is the equivalent which works with metanorma:

https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json[\https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal]

https://maps.gnosis.earth/ogcapi/collections/blueMarble/map?bbox-crs=%5BEPSG:3395%5D&bbox=-4596385.263861,2080129.089271,4596385.263861,11273386.415933&crs=%5BEPSG:3395%5D["\https://maps.gnosis.earth/ogcapi/collections/blueMarble/map?bbox-crs=[EPSG:3395\]&bbox=-4596385.263861,2080129.089271,4596385.263861,11273386.415933&crs=[EPSG:3395\]"]

(except that in this particular case that last link gets cut off and not line-breaked for the PDF rendering -- see #664 (comment))

Thanks for all the help trying to make metanorma easier to use for us poor editors :)

[opoudjis]

Not urgent.

[jerstlouis]

Just noticed that the \ escaping the link inside the text are now showing as \ on https://opengeospatial.github.io/ogcna-auto-review/21-038.html#toc94 but not with my local metanorma gem version... -- Curious why that is! :)

[Intelligent2013]

@opoudjis FYI, I've tried to generate the presentation XML with the old Gemfile.lock (Gemfile.zip) (1 year ago) for the adoc:

Link TC1: https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json[https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal]

Link TC2: https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json[\https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal]

Link TC3: link:https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json[https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal]

Link TC4: http://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json[http://maps.gnosis.earth/ogcapi/collections/OpenMapLocal]

The Presentation XML contains \ in TC2, and TC1, TC3 and TC4 is ok:

<ogc-standard xmlns="https://www.metanorma.org/ns/ogc" type="presentation" version="2.3.9" schema-version="v1.2.1">
...
<p id="_">Link TC1: <link target="https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json">https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal</link>
</p>
<p id="_">Link TC2: <link target="https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json">\https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal</link>
</p>
<p id="_">Link TC3: <link target="https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json">https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal</link>
</p>
<p id="_">Link TC4: <link target="http://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json">http://maps.gnosis.earth/ogcapi/collections/OpenMapLocal</link>
</p>

With today's generated Gemfile.lock (by bundle update) the presentation XML is ok for TC2, but nested links for another cases:

<ogc-standard xmlns="https://www.metanorma.org/ns/ogc" type="presentation" version="2.5.9" schema-version="v1.3.2">
...
<p id="_">Link TC1: <link target="https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json"><link target="https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal"/></link></p>
<p id="_">Link TC2: <link target="https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json">https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal</link></p>
<p id="_">Link TC3: <link target="https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json"><link target="https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal"/></link></p>
<p id="_">Link TC4: <link target="http://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json"><link target="http://maps.gnosis.earth/ogcapi/collections/OpenMapLocal"/></link></p>

Source Gemfile:

source "https://rubygems.org"

gem "metanorma-cli"

[opoudjis]

Ugh. Urgent.

[opoudjis]

Now that I've finally had the time to look at what Alex reports: we used to require no \ . Now we do require \ . And at issue is, what has changed in processing in the past year.

I'll investigate, but won't spend days on this...

[opoudjis]

Yup, I know what it is.

This change in processing was introduced in metanorma/metanorma-standoc#808

Asciidoctor out of the box applies character substitution globally, including to URLs. That means it converts ... to …, (c) to ©, and other undesirable happenings, culminating in e ending up as `e in a URL (!!!). This is a 10-year old unresolved issue in Asciidoctor. (The list of those is long.)

To prevent that behaviour, I've introduced preprocessing that escapes all such links as passthrough text, so they are not text-substituted, and then converts them back to URLs in postprocessing. In that process, I've lost the ability to deal with URLs with URL text.

If I have to have either Asciidoctor mangling legitimate links, or authors having to escape URL text in URL macros, I'm going to choose the former. Let me investigate whether I can refine the preprocessing.

[opoudjis]

So in the macro,

https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json[https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal]

is escaped as

link:++https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json++[https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal]

What we want, and what the \ is having to do, is the equivalent of converting it instead to:

link:++https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal?f=json++[++https://maps.gnosis.earth/ogcapi/collections/OpenMapLocal++]

[opoudjis]

Addressed: running the link detection recursively. (The recursion does bottom out.) The \ will now be unneeded after all.

[opoudjis]

... No, that doesn't work. Will need to insert \ before any http inside [] in links, during preprocessing.