Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[asciidoc-lang-dev] Proposing olinks

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)..."


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."

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

Back to the top