Re: [asciidoc-lang-dev] Proposing olinks

[Dave Gauer <dave@xxxxxxxxxxxxx>]

On 2/17/21 12:50 PM, David Jencks wrote:
> I don’t think I understand what problem you are trying to solve, and 
> I would like to.


The fault is entirely mine! I don't think I provided enough context at
the outset.


> I know pretty much nothing about DocBook


To quote Wikipedia on the relationship:

"AsciiDoc is a human-readable document format, semantically equivalent
to DocBook XML, but using plain-text mark-up conventions."

https://en.wikipedia.org/wiki/AsciiDoc

The AsciiDoc FAQ is likewise littered with references to DocBook:

https://asciidoc.org/faq.html


> - I don’t know if maintaining/increasing DocBook/AsciiDoc 
> compatibility is a goal of anyone in the spec effort


I have no idea if it is either. It was an original AsciiDoc goal, but
the importance of DocBook may have waned over the years.

It's not something I'm personally vested in. I'd be curious what other
opinions are on this list.


> - I regard the current behavior of Asciidoctor as the de-facto
> specification for what AsciiDoc is.


I want to agree with this, but the fact is that some tools out there
still use the old original Python `asciidoc` implementation. Full
backward compatibility should take those into account. (Mind you,
AsciiDoctor does a phenomenal job of this.)


> I don’t see you indicate what your output format is other than “not 
> html”.  If the assumptions above apply, you could write a converter 
> backend for Asciidoctor to render your documents into that output 
> format and translating xrefs into whatever navigation information
> you need.


To be clear: in the case of my wiki, there is _no_ output format! I am
navigating between AsciiDoc (.adoc) files via links. They are never
converted to another form. (It's neat!)

Don't get me wrong, I'm keenly interested in HTML output. But the
concept of a relative link isn't limited to any particular output format.

I posit that, at the moment, AsciiDoc has no formal way of expressing
this concept.


> 
> If you want to propose a new syntax for something that is already 
> supported by Asciidoctor I think you need a strong argument about
> how it will benefit users rather than cause confusion (if there are
> now two ways to do the same thing) and disruption (if the existing
> way no longer works).


While it is *possible* to make AsciiDoctor generate HTML links and make,
say, a web site, it currently requires using "this one weird trick" with
the <<url#,text>> xref syntax. (Or other processing, etc.)

I would argue that it is NOT possible to express a SEMANTIC relative
link to another document.

The key reason is that "xrefs" were NOT designed to link between
documents, but between LOCATIONS in a document.

If AsciiDoc is going to change the meaning of "xrefs" to be links to
locations AND to whole documents, this should be made more explicit than
it currently is (and I'd like to see more examples!).


> I do not regard the current situation as acceptable, but not because 
> of xrefs between documents.  To me, the big problem is that 
> AsciiDoc/Asciidoctor is fundamentally about converting one document, 
> but it makes highly questionable assumptions about how to interpret 
> the symbols encoding the “other document” in xrefs, namely that they 
> refer to file system paths.  I think that AsciiDoc processors should 
> interpret location information as uninterpreted tokens and delegate 
> the interpretation to an extension.  Presumably the default
> extension would provide the current file-system-based behavior.


You would like:

"An implementation-independent concept of a link to a document."

Am I summarizing that correctly? If so, I want that too!

But what I'm asking for initially is:

"A link to a document."


> 
> What I write tends to be hard to understand :-( but I hope that you 
> will be able to explain what you want in more detail and in 
> relationship with what I’ve written, and also explain how it will 
> generally be an improvement to AsciiDoc in comparison to the current 
> Asciidoctor behavior.


Thank you very much for the chance to explain further!

If anyone is interested in going down the rabbit-hole from whence this
proposal came, here's the tragic back-story:

https://github.com/ratfactor/vviki/pull/4

Thank you!

-Dave Gauer