Dave,
I agree we need clarification and alignment (that's really what this is all about), but I don't think we need a new macro. What we've been experimenting with in Asciidoctor and Antora is upgrading the xref macro to be able to make deep links to AsciiDoc documents, whether it's the same document or a different one. The target is either just a fragment (like #idname), just a document (like document-b.adoc), or a document with a fragment (like document-b.adoc#idname). What we're after is something like the xref in DITA, though perhaps with even more awareness of context. So what we need to focus on is strengthening the capabilities of our own xref macro. And as David pointed out in another thread, we may want to make the resolution of the target document an extension point so that we don't end up coupling that reference to the filesystem.
> I propose we take a third type of link from DocBook: the olink.
I've always really disliked the olink element in DocBook because it doesn't have a clear meaning. What does the "o" stand for. Even if you told me, it's doubtful most users would be able to figure that out. I might as well have been called link2. xref has a much stronger meaning and we should stick with it.
Best Regards,
-Dan
