Asciidoctor: Inter-document cross references section title resolution implementation status.

[gaganis]

I have been expecting that inter-document cross references would have been able to automatically resolve section titles but they do not as is clearly described in the relevant section of the user manual.
Asciidoctor cannot (yet) resolve the section title in a separate document

The (yet) suggests to me that there might be some work in progress or issue where this is worked on or discussed, but I have not been able to find anything relevant to this. I am interested in this feature so I would appreciate to be pointed in the right direction.

Thanks!
Giorgos

See: http://asciidoctor.org/docs/user-manual/#inter-document-cross-references

[mojavelinux]

You are are correct that the inter-document cross references do not yet reach across the boundaries of a document to resolve the title automatically. The reason is, it would mean we would have to parse the referenced document as well. There's a very good chance we will only change core to use a prepared lookup table of titles and rely on another tool to handle the indexing itself. We are moving in that direction.

[gaganis]

Thank you @mojavelinux for your swift reply!

I have absolutelly no idea of the asciidoctor internals but the way I imagine an implementation for this would be to create a function that would only parse refs and titles and put them in a lookup table. This would only run when a cross reference is encountered for a file.

In my case I worked around this by implementing a groovy script that build a lookup table using regex and then again used regexs for creating the inter-document references and their respective labels.

This script was for a very specific case and somewhat crude, but I can share it :smile: : https://gist.github.com/gaganis/e3ab343bbfbce1b4d019c42c3615ddc1

[mojavelinux]

Thanks for sharing!

I'm going to explore the idea of making the xref resolution an extension point. What I want to avoid is having core loading other files because then it is doing too much...and there are hundreds of ways those files could be loaded. But an extension would have the right scope / visibility to do this task. It could either be done lazily or eagerly. That would be up to the extension. We could certainly provide a reference extension for those who don't want to implement their own.

But before we do any of that, some architecture is definitely needed. That will be the focus of the next several comments.

[cirosantilli]

When this is solved, hopefully we will also get warnings for non-existent broken references :-)

[gaganis]

@cirosantilli There exists the extension jirutka/asciidoctor-interdoc-reftext written by @jirutka that might be helpful your usecase.