Re: [asciidoc-lang-dev] Proposing olinks

[Dave Gauer <dave@xxxxxxxxxxxxx>]

Intentional duplication: I'm re-sending this message with proper text
wrapping as a reply. Apologies to anyone who had a hard time reading the
original. If only email messages were written in AsciiDoc format, right?
(And yes, the mail client will be punished.)




== 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