[asciidoc-lang-dev] Proposing olinks

[Dave Gauer <dave@xxxxxxxxxxxxx>]

Hello AsciiDocophiles,

I've been eager to pounce on this mailing list. :-)

== What We Have Now

There are currently two types of links in AsciiDoc. (I'll use the 
DocBook documentation to describe these and you'll see why in a moment.)

1. link:http://foo[Foo]

DocBook describes this type of link as:

> "The link is a general-purpose hypertext element. Usually, link 
surrounds the text that should be made "hot" (unlike xref which must 
generate the text)..."

and

2. xref:foo[] (or with optional link label xref:foo[Foo])

> "The xref element forms a cross-reference from the location of the 
xref to the element to which it points. Unlike link and the other 
cross-referencing elements, xref is empty. The processing system has to 
generate appropriate cross-reference text for the reader."

Also note that there exists <<foo>> syntax for xrefs as well, and I have 
found a fair amount of confusion surrounding the two syntax styles.


== The Problem

As an avid fan of the AsciiDoc format, I use it not just for 
"traditional" documents, but also for pretty much everything I write: 
personal wiki, website, notes. These are all inter-linked bodies of 
documentation residing in separate files. I have tooling which 
understands these relationships.

Unfortunately, AsciiDoc currently has no One True Way to make relative 
links between documents.

* link:http://foo[Foo] is intended for absolute URLs

* xref:foo[] is intended for cross-references WITHIN a document

(Yes, xref links _can_ also be used to make relative links to references 
in other documents and it _can_ be "tricked" into linking to another 
document directly in at least one AsciiDoc implementation.)

In practice, I've found that you can coerce EITHER of these link types 
to produce HTML output with relative links between documents (I'm 
personally using "links", others are using "xrefs"). No one method is 
cross-implementation compatible!


== The Proposal

I propose we take a third type of link from DocBook: the olink.

> "Unlike link, the semantics of olink are application specific. The 
olink element provides a mechanism for establishing links across 
documents, where ID/IDREF linking is not possible and URI-based linking 
may be inappropriate.
> In general terms, the strategy employed by olink is to point to the 
target document by URI, and point into that document in some 
application-specific way."

https://tdg.docbook.org/tdg/5.2/olink.html

To put it plainly, this is a link type made expressly for relative 
linking between documents!

I would love for this link type to:

1. Exist
2. Mimic the macro syntax of the existing link types

Therefore, I propose AsciiDoc have these three link types:

    link:http://foo[Foo] <-- absolute URL
    xref:foo[]           <-- reference ("anchor") link
    olink:foo[Foo]       <-- relative link to document

To make the examples even more concrete and using HTML as an example, I 
might expect this output for the above links:

    <a href="http://foo";>Foo</a>
    <a href="#foo">Foo</a>
    <a href="foo.html">Foo</a>

Note the ".html" extension appended to the olink href above, which would 
be application-specific (and user-configurable!).

Lest anyone think all of this is Web-centric, my main purpose in 
proposing this is to have a correct type of link to use for my wiki 
system (a Vim plugin) which navigates local .adoc files natively. Most 
of these are never converted to HTML.


I'm really excited about the standardization of AsciiDoc and appreciate 
this effort!

AsciiDocaly Yours,

Dave Gauer