Eric,
Your post triggered an idea in my mind about how to solve this.
As you pointed out, we actually have two use cases here:
1. Link to a standalone document
2. Link to section in the final document that is stored in source form in a separate document
The second use case has provided clarity for the first.
If you are willing to follow two conventions (one which is required anyway) we can make this work simply by modifying the backend templates (which make the HTML / DocBook). Here are those assumptions:
1. Section ids (and other anchors) are globally unique in the final document (Asciidoctor enforces this by appending counters if there is a conflict, but they need to be globally unique in the source documents for this to work cleanly)
2. The name of the document must match the id generated from the section title for any document that gets included in the master document (this is the default on GitHub anyway...don't worry about case, we can handle that)
Now, the reason this is going to work is because Asciidoctor builds a collection of all the ids in the document during parsing. Therefore, you can check if a cross reference is available in the final document. If so, we can make a xref link. If the id is not present, we assume we still have to link to the other document.
Here's how the syntax will work. First, the target of the link will be the AsciiDoc source document. We can recognize known AsciiDoc extensions to understand when we are dealing with this type of link in the renderer.
link:other-document.adoc[]
But that's not enough, because there may be a case when you want to link to the AsciiDoc document directly. So, we add one more requirement. You must specify an anchor on the target. If you want to reference the top-most heading, just append a hash:
link:other-document.adoc#[]
If you want to reference a section within that document:
link:other-document.adoc#example-section[]
Here are the rules for how the information from the macro is processed in the renderer.
1. Check if the target has a known AsciiDoc source extension (.ad, .adoc, .asciidoc, etc), then strip it from the target
2. If an anchor value is given (value after the hash), look for that id in the @document.references[:ids] table
2a. If found, create an cross-reference to that section /END
2b. If not found, use the target and anchor to create an external link to that document and section (e.g., <a href="other-document.html#example-section">...</a>) /END
3. If an anchor value is not given, look for the target in the @document.references[:ids] table
3a. If found, create a cross-reference to that section /END
3b. If not found, use the target to create an external link to the top of that document (e.g., <a href="other-document.html">...</a>)
Voila!
I'll follow up with an example to show how this will work. I just wanted to share that I had come up with a possible scenario.
NOTE: The tricky part is going to be making this work for links that have no file extension, like on the GitHub wiki. We could detect the 'wiki/' prefix, we could add an attribute to the link macro, or we can find some other way to hint to apply this logic.
-Dan