Re: [asciidoc-lang-dev] Proposing olinks

[David Jencks <david.a.jencks@xxxxxxxxx>]

After some more thought I’ve refined my perspective a bit.

Currently my concept of Asciidoctor at least is really focussed on processing one source document, and any relationship to other documents is required to be via file system links.

I think a more useful idea is of processing a set of source documents with some logical structure into a set of output documents with a possibly transformed output structure.

For instance, Antora processes a set of source documents into a website, with some of the source transformed into web pages.
As an example (there are other ways to do this), my antora-pdf pipeline extension adds the ability to Antora to, with a little bit of instruction, transform subsets of the source documents into (single) pdfs.
Even just considering normal `include::` usage, there is no 1-1 source-target document correspondence.

From this point of view, I like the idea of `xref` expressing links between source documents in the set and `link` expressing links outside the set.
To me, it makes the most sense to think about this in terms of the output documents.
Then, `olink` doesn’t really make sense, because whether the target is in the same output document or not depends on processing, not source structure.

I think some more thinking is needed about the architecture of the relationship of an AsciiDoc processor to an expression of the source document set structure and boundaries.

David Jencks

> On Feb 18, 2021, at 7:53 AM, Dave Gauer <dave@xxxxxxxxxxxxx> wrote:
> 
> On 2/18/21 4:27 AM, Dan Allen wrote:
>> 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.
> 
> 
> Fair enough. As you and David Jencks pointed out, adding yet another
> link macro may wind up with even more confusion.
> 
> Putting myself in the position of someone who is trying to learn
> AsciiDoc for the first time, I can appreciate how off-putting the
> concept of an "olink" might be. :-)
> 
> 
>> ... 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 can live with that. I think I'll open a new thread to address
> "strengthening the xref" as you say.
> 
> 
>> I've always really disliked the olink element in DocBook because it
>> doesn't have a clear meaning. What does the "o" stand for.
> 
> 
> Ha ha, obviously the "o" stands for "oh dear, this is a hard problem."
> 
> Thanks for your response!
> 
> -Dave Gauer
> _______________________________________________
> asciidoc-lang-dev mailing list
> asciidoc-lang-dev@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe from this list, visit
> https://dev.eclipse.org/mailman/listinfo/asciidoc-lang-dev