Links with Asciidoctor fragments don't work properly?

URIs with significant characters have always presented a challenge to inline parsing in AsciiDoc (as it is currently implemented). This limitation is quite well known given how many variants of it have been reported.

The primary workaround, and a best practice, is to define URIs as attributes, which evades interpretation because of substitution order.

:xref-ehr-package: http://www.openehr.org/releases/RM/{release}/ehr.html#_ehr_package

{xref-ehr-package}[visible in the ehr package], namely, ...

Other workarounds are documented here: http://asciidoctor.org/docs/user-manual/#complex-urls

(This problem goes away once we use an inline parser instead of regex-based substitutions, but not before then).

I'm curious, though, if you are linking to a section in another AsciiDoc document, why aren't you using the xref syntax?

<<ehr#+_ehr_package+>>, namely, ...

The passthrough marks (pluses) are required to escape the fragment name from substitution. The passthrough is preferred over backslashes, which are context sensitive.

You should only need to use one of the link macros if you are linking to an external URI.

Asciidoctor's own generated fragment URLs, which are perfectly fine, aren't understood properly if used as links in Asciidoctor text

This correlation is strictly coincidental. The same problem exists for any URI that contains this pattern.

Cheers,

-Dan

On Tue, Dec 8, 2015 at 5:32 AM, wolandscat [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I think I'm seeing a real error here, but wanted to check before logging it.

The adoc raw text is:

http://www.openehr.org/releases/RM/{release}/ehr.html#_ehr_package[visible in the ehr package], namely `_compositions_`, `_ehr_status_`, `_ehr_access_`, and `_directory_`.

Note the fragment

_ehr_package

 in the URL. If I leave it like this and generate the HTML, I get

http://www.openehr.org/releases/RM/latest/ehr.html#ehr_package[visible in the ehr package], namely _compositions, ehr_status, ehr_access, and directory.

This of course is completely broken. If I put a single backslash quote before

_ehr_package

 like so:

http://www.openehr.org/releases/RM/{release}/ehr.html#\_ehr_package[visible in the ehr package], namely `_compositions_`, `_ehr_status_`, `_ehr_access_`, and `_directory_`.

I nearly get the right output:

 visible in the ehr package, namely _compositions_, ehr_status, ehr_access, and directory.

With the text "visible in the ehr package" having the correct link, including fragment behind it. Except... see the word 'compositions', has literal underscores around it. I suspect this is because the underscore counting in the adoc parser is still confused by the underscores in the URL.

So the first problem is that Asciidoctor's own generated fragment URLs, which are perfectly fine, aren't understood properly if used as links in Asciidoctor text, unless I am mistaken somewhere here. To make them work requires manual insertion of a quote backslash.

The second is that underscores in the fragment part of a URL appear to mess up normal underscore (=italics) processing.

Am I seeing a real problem here, or just doing something wrong? If yes, I'll raise an issue.

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Links-with-Asciidoctor-fragments-don-t-work-properly-tp4037.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen