Skip to main content

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

On Feb 19, 2021, at 2:31 AM, Dan Allen <dan@xxxxxxxxxxxxxx> wrote:

> as "a cross-reference link to the content AUTHORED in the document foo.adoc", then it suddenly doesn't matter what the output filename(s)
might be.
> There doesn't even need to be an actual file named "foo.adoc" (it could be an entry in a database table), but this is the canonical name of another document it in cross-references.
> Flipping it around to think of it as a cross-reference to the AsciiDoc source document rather than to an output file stands the entire problem on its head and suddenly I'm totally happy with it, file extension and all!
> Dan, is this how you think of xrefs?

There's one gap in the current assumption that David Jencks discovered while working on Antora (the static documentation site generator for AsciiDoc). He pointed out that we shouldn't look for just the .adoc file extension, but rather any file extension. That would allow for making an xref to a document that was converted, but not from AsciiDoc. One example is an xref to an HTML file generated from Javadoc. In this case, the xref is not "source to source" as I often describe, but still a reference to a structured document. It's something I think we need to take under consideration. That aside, if the reference is in an AsciiDoc document, then it should definitely be source to source (so we can control how the reference is constructed in the output document).

From my perspective that I’ve been pushing, that the discussion of xrefs has to be in the context of a set of documents, these html documents are in the set of sources, so the xref is decidedly source to source.  The transformation these particular sources go through is a bit simpler (‘copying’) than that for AsciiDoc documents.

David Jencks

Best Regards,


Dan Allen, Vice President | OpenDevise Inc.
Pronouns: he, him, his
Content ∙ Strategy ∙ Community
asciidoc-lang-dev mailing list
To change your delivery options, retrieve your password, or unsubscribe from this list, visit

Back to the top