Non working link in development environment setup

[SaschaWillems]

The chapter for the development environment setup has the following paragraph:

You can now use the link:/attachments/[attachments] directory in this tutorial
as a template for your Vulkan projects. Make a copy, rename it to something like `HelloTriangle`
and remove all the code in `main.cpp`.

Problem is: That links does not work and it's afaik not possible to have Antora link to and display folders.

So people clicking on this might be confused as they expect to see a code file, but instead get a 404 "file not available".

I'm inclined to rephrase this to:

You can now use the code from any of the following chapters as a template for your Vulkan projects. Make a copy, rename it to something like `HelloTriangle` and remove all the code in `main.cpp`.

@gpx1000 : Any thoughts?

[gpx1000]

That looks like a good rephrasing. I might not be responsive today; but I should get back to you tonight and start addressing all these great issues.

[SaschaWillems]

No pressure. Just wanted to write them down while memory is fresh ^^

[oddhack]

Also you can e.g. link:URL[text^] with the ^ causing it to open a new window. I do that for external links in the refpages for similar reasons. We could probably set something up to target an Antora page which imbeds an external link with enough CSS magic.

[oddhack]

Generalizing the issue we should avoid relative links and relative xrefs alike in markup that gets converted to Antora, since they are subject to both rewriting and re-pathing for the Antora structure and the underlying repository is no longer present. This is something amenable to discovery by CI checks for new content.

For the spec content, we require that every include:: must start with an asciidoctor variable (which gets changed appropriately when building the docs site), as well as link: macros that are not URLs.