[DO NOT MERGE] Test cross-documents reference format (ADOC, HTML and PDF)

[AByzhynar]

Test new reference format "One-for -all") which will allow to navigate over the documents by clicking highlighted references independently if it is ADOC (navigation between different ADOC documents) or generated HTML/PDF

[CLAassistant]

All committers have signed the CLA.

[gmlueck]

This looks like an interesting feature for GitHub / GitLab document preview. I might use it in some other projects. Do you have a link to more information about it?

However, it doesn't seem like we need this for the SYCL-Docs repo because the Asciidoctor tool already provides cross-file references. What was your motivation for creating this PR? If you are not asking to merge it, can we change it to draft? Or just close it?

[keryell]

I told Andriy to give a small demo of what he wants to do during a next SYCL meeting.

[keryell]

Cf internal https://gitlab.khronos.org/syclsc/Specification/-/merge_requests/108

[AByzhynar]

@keryell I won't be able to make a short demo until someone approves "build" stage on the checks. I mean Specs generation.

[gmlueck]

I approved the CI run. I'm still not sure what your goal is with this PR, though. Changing all the links in our spec as you show would be a very large change, and it's not clear what benefit it would provide.

[AByzhynar]

I approved the CI run. I'm still not sure what your goal is with this PR, though. Changing all the links in our spec as you show would be a very large change, and it's not clear what benefit it would provide.

Thank you @gmlueck. Now I am able to demonstrate potential improvement.

[AByzhynar]

This looks like an interesting feature for GitHub / GitLab document preview. I might use it in some other projects. Do you have a link to more information about it?

However, it doesn't seem like we need this for the SYCL-Docs repo because the Asciidoctor tool already provides cross-file references. What was your motivation for creating this PR? If you are not asking to merge it, can we change it to draft? Or just close it?

Maybe I am missing something. But I can't see Asciidoctor cross-file references working.
I'll join next SYCL WG meeting on Thursday, 12th March, to show 1 minute demo.

[gmlueck]

Maybe I am missing something. But I can't see Asciidoctor cross-file references working.

They work in our official HTML / PDF builds from the CI system. For example, look at the way <<backend>> is rendered here as a link to the glossary:

https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#chapter:sycl-programming-interface

I know the links do not work when you preview the *.adoc file in a browser from the GitHub repo. However, that is not that important, and I don't want to change all the links in the *.adoc sources just to enable this. There are lots of formatting things that are different between the official HTML render and the GitHub browser preview. You won't be able to fix them all unless you can somehow cause the GitHub preview to run asciidoctor with our specific configuration files.

I'll join next SYCL WG meeting on Thursday, 12th March, to show 1 minute demo.

Sounds good!

[AByzhynar]

PR is closed as was created for demonstration purposes ONLY.