Evaluate cross module linkage

[SaschaWillems]

As per mail discussion, it would be great if we somehow could get cross module linkage instead of external linkage. One sample is the guide that has links to the Vulkan samples. But that links point to the github repository instead of the Antora module. So when you click such a link from the docs site you jump to github instead of the samples Antora module. Same for the spec/registry links.

[oddhack]

I see it as an issue of link density. If we need only a few cross-module links then conditionalizing them in the asciidoc markup is the way to go. If it becomes a systematic issue because we are linking more heavily, some different solutions will be needed. For example, in the API spec we could add macros that expand to the proper URLs whether built for regular asciidoctor cross-document or Antora component output - I am already doing stuff like this for some of the Ruby macros.

It is a different problem for the components written in straight asciidoc markup without macros, like the Guide. However, since we are running preprocessing scripts to convert their markup for Antora anyway, recognizing HTML links to other components and rewriting them as well may be viable. This will all be a nuisance and maybe we will eventually be able to migrate entirely to Antora, but there are so many stakeholders with different needs and publication schedules that it won't be soon, if so.

[spencer-lunarg]

same with the Vulkan-Guide, I realize the links go to the old spec instead of staying in Antora. Now sure how to approach it but happy to take action against the Guide to update the links in anyway needed

[SaschaWillems]

While it means additional work the optimal solution would be using defines to select cross module links when the guide is built for Antora. I'm doing this with the sample's documentation too. That way you won't break github linkage.

For that, Antora has a generator define that you can use like this:

ifdef::site-gen-antora[]
* xref:guide:ROOT:index.adoc[Vulkan Guide]
endif::[]

ifndef::site-gen-antora[]
* https://github.com/KhronosGroup/Vulkan-Guide[Vulkan Guide]
endif::[]

The upper block is used when the Antora docs site is build, and uses cross module links. The lower block is used for other generators like github and uses external links.

For a few links this is fine, but it can get cumbersome, esp. with with links that are part of paragraphs.

For some of the docs site modules (samples, tutorials) we already use built-time scripts that fix up some stuff like linkage. So maybe we can come up with something similar for the guide, that changes external spec links to cross module references?

[oddhack]

I did something along these lines for resolving links from the spec extension appendices into the proposal documents, as follows:

• Define an attribute 'proposalRefPath' which expands to 'link:repoURL/' when building the regular spec, and to 'xref:proposals:' when building the Antora site
• Reference proposals as '{proposalRefPath}proposals/name-of-proposal.adoc[link text]'

This is only generalizable to the extent that there is a suffix component that is the same for both builds, but it does seem to work.