Re: [asciidoc-lang-dev] Proposing olinks

[Dave Gauer <dave@xxxxxxxxxxxxx>]

On 2/17/21 4:56 PM, David Jencks wrote:
> Thanks for the updates!
> 
> I’ve been trained to think that the existing asciidoc.org
> <http://asciidoc.org> site is out of date and not really to be trusted.
>  My understanding is that in the near future that domain name will point
> to the AsciiDoc spec project and the existing content will be moved
> elsewhere.  Again, as far as I’m concerned, what AsciiDoc is is the
> existing behavior of Asciidoctor.  


Yes, I would definitely not refer to asciidoc.org to get the current
state-of-the art! :-)


> 
> As this is an effort to come up with a spec, full backward compatibility
> is not a realistic goal.  Maximizing backward compatibility while also
> maximizing usability, clarity, implementability, etc, surely is :-)



Absolutely. Agree 100% with that.


>> 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!)
> 
> I don’t believe you when you say there is no output format :-)  If there
> were no output format, you wouldn’t need a parser, and you’d be happy
> typing “mykindofref:abracadabra-link-to-magic-page{foo!!!}” and having
> it do nothing.


Ha ha. Skepticism is understandable. :-)

The wiki is managed with a Vim plugin (I'm the author):

https://github.com/ratfactor/vviki

To create a new link, you press ENTER on any piece of text. Press ENTER
again to follow the link to a new document with that same name.  (And
yes, links look like "link:foo[foo]" WITHOUT a file extension!)

BACKSPACE takes you to the previous page in your "browsing" history.

And that's pretty much it. It's a really simple system.

Because all content is AsciiDoc, you _can_ turn the wiki into a website
(I do that too!) or any other kind of document.

But in the meantime, it's all just .adoc files sitting in directories.
Most of mine have never been "converted" or "output" into anything.

I think it's also worth mentioning that GitHub AsciiDoc links work this
way as well. If you have a README.adoc file in a repo, you can link to
other .adoc files and the links work exactly like they would in HTML
pages (it IS rendering as HTML, of course), but the filenames you're
visiting are all .adoc. (More on this a linked example to play with are
below.)


>> I posit that, at the moment, AsciiDoc has no formal way of expressing
>> this concept.
> 
> That depends on what you mean by “formal”.  Since there’s no grammar,
> nothing in AsciiDoc is “formal”.  Since xrefs between documents work
> today just fine in Asciidoctor as long as you are happy with the
> restriction that you have to rely on file system organization, and
> Asciidoctor behavior is the de-facto spec, then there is a formal way of
> expressing this concept.


You're right, that wasn't expressed well. I'll give it another shot  in
my answer to the next bit below.


>>
>> 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 think it’s documented pretty clearly here:
>  https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/
> This should appear (possibly with slight modifications) soon as the
> initial contribution to the spec project.


Well, to quote the top of that page:

"The inline xref macro can also link to IDs in other AsciiDoc documents."

To me, the key phrase is "link to IDs". This is the purpose of an xref.

Of course, reading on to the bottom of the page are examples of linking
directly to documents without IDs like so:

    xref:README.adoc[README]

But this is an ESPECIALLY bothersome example for me (and I imagine for
you too). Without the "#" dividing the document filename from the ID for
the cross reference, the ONLY way we can tell this is an inter-document
link is by looking for ".adoc" in the name! (Otherwise it would be
regular cross-reference looking for the ID "README.adoc".)

To put it bluntly, having that ".adoc" extension there perform a magical
conversion feels like a hack to me. And it only adds fuel to the
unfortunate idea that these links are to "files", not "documents".


But I'd like to step back and take another run at this!

So, as we know, the AsciiDoc application was written in Python by Stuart
Rackham nearly 20 years ago and exported these formats:

* XHTML
* LaTeX
* PDF
* DocBook
* OpenDocument
* EPUB
* Man (UNIX man pages)

Looking at this list tells us a lot about what its users expected to
produce: articles, books, and on-line (with a hyphen) manuals.

So it comes as no surprise that AsciiDoc provided the syntax
(conceptually borrowed from DocBook) to have two types of links in
documents: internal cross-references and links to files or resources on
the World Wide Web.

And it is no surprise that it did NOT have the concept of making an
inter-linked collection of small related documents.

I mean, just take a look at this manual for AsciiDoc itself:

https://asciidoc.org/asciidoc.txt

It's a perfect example. It's a huge document full of 105 internal
cross-references and about 50 external "https://..."; URL links. Those
two types of links are all it needs.

Syntactically, the two link types are: "link" macros for files/URLs
(relative or absolute) and "xref" macros for cross-references to
internal sections in the document.

The problem with "link" macros, of course, is that they point to
filenames or URLs verbatim. Which makes it just about impossible to have
a relative link to another document that works for multiple output file
types.

This stops working when you publish the files as PDF instead of HTML:

    link:foo.html[Foo]

So without external processing/conversion, "links" are badly crippled by
this limitation.

Now to COMPOUND this problem (not fix it), at some point we gained the
ability to make cross references to other documents. So this:

    xref:ID[label]
 or
    <<ID,label>>

could now optionally include a filename like this:

    xref:filename#ID[label]
 or
    <<filename#ID,label>>

As with link macros, the filenames in xref macros were verbatim, so they
suffered from the same problem. But adding this ability makes perfect
sense, so no harm done.

Now here's where things get weird for me. For SOME reason, and I don't
know when or why, it was decided that linking between documents (not
just IDs in documents) should be done with "xrefs" instead of "links".

This is despite the fact that every piece of reference material relating
to AsciiDoc that I can find, whether historical or current, says that
"xrefs" are for IDs/anchors and "links" are for documents/files/URLs.

But you know what? It doesn't matter. We can use "xref" instead of
"link" to link to pages. Fine. They're BOTH broken because they expect
verbatim filenames.

EXCEPT come to find out the new rule is that if you put a filename with
a PARTICULAR extension in an "xref:" macro, THEN it will convert that
extension to a different extension of your choosing. (If you set
everything correctly, that is.)

So I did a little digging and it turns out that AsciiDoc's ancestor,
DocBook at some point added this neat "olink" type to encapsulate the
concept of a relative document link independent of filenames (or even
file systems!) and when I saw that, I said, "THERE, now THAT's what we
need."

And here we are. :-)

"olink" Pros and cons:

PRO: A benefit of adding "olink" is that it won't interfere with all the
existing documents out there with "links" and "xrefs". They'll continue
to render exactly as they render now.

CON: It's an additional thing. You're absolutely right to be skeptical
about adding things. The default should always be "no" and the new thing
should justify its existence.

Sure, I like "olinks", but I'm not married to them. The REAL problem is
fixing relative links to "documents", not "files". The current xref
situation "works", but it ain't exactly the solution I was hoping for.


As a bit of a tangent, but mentioned above and certainly related: I did
a test a while back on GitHub to test the relative link examples after
reading the same "Document to Document Cross References" page you linked
above and found that the "xref:" syntax worked as advertised (the link
takes you to foo.adoc), but the "<<filename.adoc,link text>>" example
did not. See for yourself:

https://github.com/ratfactor/gfa-test

Example 6:

    <<foo.adoc,foo>>

Makes this HTML link:

    <a href="#foo.adoc">foo</a>

So maybe that example should be updated in the "AsciiDoc Language
Documentation"? Or GitHub needs to be updated. :-)


Sorry for the length of this email, but I didn't feel like brevity was
helping my case, ha ha.

Thank you for reading and I'd be delighted to hear any and all feedback.

Yours in ASCII,

-Dave Gauer