Change links in proposals to fix errors and be easier to convert for inclusion in the docs site

Makefile

@@ -472,7 +472,7 @@ MARKUP_SPEC_SOURCES = $(SPECDIR)/[a-z]*.adoc $(SPECDIR)/chapters $(SPECDIR)/appe
 # Look for disallowed contractions
 CHECK_CONTRACTIONS = git grep -n -i -F -f $(ROOTDIR)/config/CI/contractions | grep -v -E -f $(ROOTDIR)/config/CI/contractions-allowed
 check-contractions:
-	if test `$(CHECK_CONTRACTIONS) | wc -l` != 0 ; then \
+	$(QUIET) if test `$(CHECK_CONTRACTIONS) | wc -l` != 0 ; then \
 	    echo "Contractions found that are not allowed:" ; \
 	    $(CHECK_CONTRACTIONS) ; \
 	    exit 1 ; \
@@ -481,8 +481,9 @@ check-contractions:
 # Look for duplicate words
 CHECK_DUPLICATES = $(PYTHON) $(ROOTDIR)/scripts/find_duplicates.py `find *.adoc appendices chapters config scripts style -name '*.adoc'`
 check-duplicates:
-	if ! $(CHECK_DUPLICATES) ; then \
+	$(QUIET) if ! $(CHECK_DUPLICATES) ; then \
 	    echo "Successive duplicate words found that are not allowed" ; \
+	    $(CHECK_DUPLICATES) ; \
 	    exit 1 ; \
 	fi
 
@@ -491,7 +492,7 @@ check-duplicates:
 # check-writing target below.
 CODESPELL = codespell --config $(ROOTDIR)/config/CI/codespellrc
 check-spelling:
-	if ! $(CODESPELL) > /dev/null ; then \
+	$(QUIET) if ! $(CODESPELL) > /dev/null ; then \
 	    echo "Found probable misspellings. Corrections can be added to config/CI/codespell-allowed, or files excluded in config/CI/codespellrc if there is no other option:" ; \
 	    $(CODESPELL) ; \
 	    exit 1 ; \
@@ -502,7 +503,7 @@ check-spelling:
 # made in outstanding extension branches for new text.
 CHECK_WRITING = git grep -n -E -f $(ROOTDIR)/config/CI/writing $(SPECDIR)/[a-z]*.adoc $(SPECDIR)/chapters $(SPECDIR)/appendices
 check-writing:
-	if test `$(CHECK_WRITING) | wc -l` != 0 ; then \
+	$(QUIET) if test `$(CHECK_WRITING) | wc -l` != 0 ; then \
 	    echo "Found old style writing. Please refer to the style guide or similar language in current main branch for fixes:" ; \
 	    $(CHECK_WRITING) ; \
 	    exit 1 ; \
@@ -511,7 +512,7 @@ check-writing:
 # Look for bullet list items not preceded by exactly two spaces, per styleguide
 CHECK_BULLETS = git grep -n -E '^( |   +)[-*]+ ' $(MARKUP_SPEC_SOURCES)
 check-bullets:
-	if test `$(CHECK_BULLETS) | wc -l` != 0 ; then \
+	$(QUIET) if test `$(CHECK_BULLETS) | wc -l` != 0 ; then \
 	    echo "Bullet list item found not preceded by exactly two spaces:" ; \
 	    $(CHECK_BULLETS) ; \
 	    exit 1 ; \
@@ -520,7 +521,7 @@ check-bullets:
 # Look for VU text ending in a period
 CHECK_VUPERIOD = ag --nocolor --asciidoc '\* \[\[VUID[^.]+\.\n( {2}\* \[\[VUID|\*\*\*\*)' $(MARKUP_SPEC_SOURCES)
 check-vuperiod:
-	if test `$(CHECK_VUPERIOD) | wc -l` != 0 ; then \
+	$(QUIET) if test `$(CHECK_VUPERIOD) | wc -l` != 0 ; then \
 	    echo "VU rule ending with a disallowed period found. Note that the matched text may be very long:" ; \
 	    $(CHECK_VUPERIOD) ; \
 	    exit 1 ; \
@@ -529,7 +530,7 @@ check-vuperiod:
 # Look for common macro markup errors
 CHECK_MARKUP = git grep -n -E -f $(ROOTDIR)/config/CI/markup $(MARKUP_SPEC_SOURCES)
 check-markup:
-	if test `$(CHECK_MARKUP) | wc -l` != 0 ; then \
+	$(QUIET) if test `$(CHECK_MARKUP) | wc -l` != 0 ; then \
 	    echo "Common macro markup errors found. Please refer to the style guide or similar markup in current main branch for fixes:" ; \
 	    $(CHECK_MARKUP) ; \
 	    exit 1 ; \
@@ -538,14 +539,14 @@ check-markup:
 # Look for asciidoctor conditionals inside VU statements; and for
 # duplicated VUID numbers, but only in spec sources.
 check-reflow:
-	$(PYTHON) $(SCRIPTS)/reflow.py -nowrite -noflow -check FAIL -checkVUID FAIL $(SPECFILES)
+	$(QUIET) $(PYTHON) $(SCRIPTS)/reflow.py -nowrite -noflow -check FAIL -checkVUID FAIL $(SPECFILES)
 
 # Look for files whose Khronos copyright has not been updated to the
 # current year
 DATE_YEAR = $(shell date +%Y)
 CHECK_DATES = git grep -z -l 'Copyright.*The Khronos' | xargs -0 git grep -L 'Copyright.*$(DATE_YEAR).*The Khronos'
 check-copyright-dates:
-	if test `$(CHECK_DATES) | wc -l` != 0 ; then \
+	$(QUIET) if test `$(CHECK_DATES) | wc -l` != 0 ; then \
 	    echo "Files with out-of-date Khronos copyrights (must be updated to $(DATE_YEAR):" ; \
 	    $(CHECK_DATES) ; \
 	    exit 1 ; \
@@ -554,51 +555,55 @@ check-copyright-dates:
 # Look for proper use of custom markup macros
 #   --ignore_count 0 can be incremented if there are unfixable errors
 check-links:
-	$(PYTHON) $(SCRIPTS)/check_spec_links.py -Werror --ignore_count 0
+	$(QUIET) $(PYTHON) $(SCRIPTS)/check_spec_links.py -Werror --ignore_count 0
 
 # Perform XML consistency checks
 # Use '-warn' option to display warnings as well as errors
 CHECK_UGLY_TYPE_DECL = git grep -E '</type>\*+<name>' $(VKXML)
 check-consistency:
-	$(PYTHON) $(SCRIPTS)/xml_consistency.py
-	if test `$(CHECK_UGLY_TYPE_DECL) | wc -l` != 0 ; then \
+	$(QUIET) $(PYTHON) $(SCRIPTS)/xml_consistency.py
+	$(QUIET) if test `$(CHECK_UGLY_TYPE_DECL) | wc -l` != 0 ; then \
 	    echo "XML contains declarations lacking whitespace:" ; \
 	    $(CHECK_UGLY_TYPE_DECL) ; \
 	    exit 1 ; \
 	fi
 
 # Look for untagged use of 'undefined' in spec sources
 check-undefined:
-	$(SCRIPTS)/ci/check_undefined
+	$(QUIET) $(SCRIPTS)/ci/check_undefined
 
 # Look for use of custom macros in the proposals and other
 # non-Specification document (except for the ChangeLog*.adoc) markup
 CHECK_CUSTOM_MACROS = git grep -n -E -f $(ROOTDIR)/config/CI/custom-macros [A-Z][A-Z]*.adoc proposals/
 CHECK_PROPOSALS = git grep -n -E -f $(ROOTDIR)/config/CI/proposals-disallowed proposals/
 check-custom-macros:
-	if test `$(CHECK_CUSTOM_MACROS) | wc -l` != 0 ; then \
+	$(QUIET) if test `$(CHECK_CUSTOM_MACROS) | wc -l` != 0 ; then \
 	    echo "Found use of specification macros in proposal or repository metadocumentation, where they are not allowed. Please use straight asciidoc markup like *must* for fixes:" ; \
 	    $(CHECK_CUSTOM_MACROS) ; \
 	    exit 1 ; \
 	fi
-	if test `$(CHECK_PROPOSALS) | wc -l` != 0 ; then \
-	    echo "Found use of {refpage} attribute in proposals (use {docs} or {extensions}, see proposals/template.adoc); or of asciidoctor markup which cannot be rendered on github, such as include: or asciimath: directives:" ; \
+	$(QUIET) if test `$(CHECK_PROPOSALS) | wc -l` != 0 ; then \
+	    echo "Found use of one or more of:" ; \
+	    echo "  - {extensions} attribute in proposals (use xref:{docs} or xref:{refpages})" ; \
+	    echo "  - link: used with {docs} or {extensions} (use xref:)" ; \
+	    echo "  - asciidoctor markup which cannot be rendered on github, such as include: or asciimath: directives" ; \
+	    echo "(see proposals/template.adoc) for examples" ; \
 	    $(CHECK_PROPOSALS) ; \
 	    exit 1 ; \
 	fi
 
 # Look for '.txt' and '.asciidoc' files, which should almost all be .adoc now
 CHECK_TXTFILES = find . -name '*.txt' -o -name '*.asciidoc' | grep -v -E -f $(ROOTDIR)/config/CI/txt-files-allowed
 check-txtfiles:
-	if test `$(CHECK_TXTFILES) | wc -l` != 0 ; then \
+	$(QUIET) if test `$(CHECK_TXTFILES) | wc -l` != 0 ; then \
 	    echo "*.txt and/or .asciidoc files found that are not allowed (use .adoc):" ; \
 	    $(CHECK_TXTFILES) ; \
 	    exit 1 ; \
 	fi
 
 # Check for valid xrefs in the output html
 check-xrefs: $(HTMLDIR)/vkspec.html
-	$(PYTHON) $(SCRIPTS)/check_html_xrefs.py $(HTMLDIR)/vkspec.html
+	$(QUIET) $(PYTHON) $(SCRIPTS)/check_html_xrefs.py $(HTMLDIR)/vkspec.html
 
 # Check for stuff that should not be published.
 # This is not part of 'allchecks' since it would fail in most new
@@ -608,7 +613,7 @@ check-internal-phrasing: check-proposed check-gitlab
 # Check for UNRESOLVED or PROPOSED issues in extension appendices
 CHECK_PROPOSED = git grep -n -E 'PROPOSED|UNRESOLVED' $(SPECDIR)/appendices/
 check-proposed:
-	if test `$(CHECK_PROPOSED) | wc -l` != 0 ; then \
+	$(QUIET) if test `$(CHECK_PROPOSED) | wc -l` != 0 ; then \
 	    echo "PROPOSED or UNRESOLVED issues should not be published in extension appendices:" ; \
 	    $(CHECK_PROPOSED) ; \
 	    exit 1 ; \
@@ -617,7 +622,7 @@ check-proposed:
 # Check for internal gitlab links anywhere in markup sources
 CHECK_GITLAB = git grep -n 'gitlab.khronos.org' $(MARKUP_SPEC_SOURCES) proposals/
 check-gitlab:
-	if test `$(CHECK_GITLAB) | wc -l` != 0 ; then \
+	$(QUIET) if test `$(CHECK_GITLAB) | wc -l` != 0 ; then \
 	    echo "Internal gitlab.khronos.org links should not be published, use corresponding github links instead:" ; \
 	    $(CHECK_GITLAB) ; \
 	    exit 1 ; \

config/CI/proposals-disallowed

@@ -1,4 +1,4 @@
-:refpage:
-\{refpage\}
+link:\{(docs|refpages)\}
+\{extensions\}
 (^|[^-_.&:<>\[[:alnum:]])(asciimath|latexmath|stem):
 ^include::

proposals/Roadmap.adoc

@@ -5,7 +5,7 @@
 = Vulkan Roadmap
 :toc: left
 :docs: https://docs.vulkan.org/spec/latest/
-:extensions: {docs}appendices/extensions.html#
+:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/
 :sectnums:
 
 This document proposes the development of a shared public roadmap for features across mid-to-high-end devices in smartphone, tablet, laptop, console, and desktop markets.

proposals/VK_AMDX_dense_geometry_format.adoc

@@ -5,7 +5,7 @@
 = VK_AMDX_dense_geometry_format
 :toc: left
 :docs: https://docs.vulkan.org/spec/latest/
-:extensions: {docs}appendices/extensions.html#
+:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/
 :sectnums:
 // Required so images render in github
 ifndef::images[:images: ../images]
@@ -38,7 +38,7 @@ A new geometry type is introduced for supplying pre-compressed geometry data to
 
 The <<VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX-struct, VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX>> structure provides a compressed bit-stream to the acceleration structure build.  The number of encoded triangles is also available for use by the implementation.  This enables the existence of a "fallback layer" which decodes the geometry and maps it to a conventional acceleration structure.  It is expected that native support will ultimately evolve, but acknowledged that on-the-fly translation may be a necessary intermediate step.
 
-For link:{docs}chapters/resources.html#vkGetAccelerationStructureBuildSizesKHR[vkGetAccelerationStructureBuildSizesKHR] the application must supply both the total number of triangles and the expected size of the compressed data.  The latter is required so that implementations can use a 1:1 mapping between compressed blocks and acceleration structure nodes.
+For xref:{refpages}vkGetAccelerationStructureBuildSizesKHR.html[vkGetAccelerationStructureBuildSizesKHR] the application must supply both the total number of triangles and the expected size of the compressed data.  The latter is required so that implementations can use a 1:1 mapping between compressed blocks and acceleration structure nodes.
 
 === Bottom-level Acceleration Structure Update Constraints
 
@@ -52,9 +52,9 @@ Additional constraints apply depending on the compression format:
 
 When pre-compressed geometry is in use, the geometry indices for the triangles are directly encoded in the input data on a per-triangle basis.  The number of <<VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX-struct, VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX>> structures supplied at BLAS build has no effect on shader table indexing or the results of the `GeometryIndex()` intrinsic.
 
-The `OPAQUE` flag is also supplied on a per-triangle basis.  The `VK_GEOMETRY_OPAQUE_BIT_KHR` flag on the link:{docs}chapters/accelstructures.html#VkAccelerationStructureGeometryKHR[VkAccelerationStructureGeometryKHR] structure has no effect for compressed geometry.
+The `OPAQUE` flag is also supplied on a per-triangle basis.  The `VK_GEOMETRY_OPAQUE_BIT_KHR` flag on the xref:{refpages}VkAccelerationStructureGeometryKHR.html[VkAccelerationStructureGeometryKHR] structure has no effect for compressed geometry.
 
-Multiple link:{docs}chapters/accelstructures.html#VkAccelerationStructureGeometryKHR[VkAccelerationStructureGeometryKHR] structures can be used to glue disconnected blobs of compressed data together into a larger acceleration structure, or for specifying different values for `VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR` for different sets of DGF blocks.
+Multiple xref:{refpages}VkAccelerationStructureGeometryKHR.html[VkAccelerationStructureGeometryKHR] structures can be used to glue disconnected blobs of compressed data together into a larger acceleration structure, or for specifying different values for `VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR` for different sets of DGF blocks.
 
 The values returned by the `PrimitiveIndex()` intrinsic are also directly encoded in the input, and may be sparsely specified or even duplicated, if the application finds some use for this.  There is no relationship between the value of <<VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX-struct, VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX::NumTriangles>>
 and the maximum primitive index.
@@ -154,7 +154,7 @@ The indirect method achieve the lowest memory overhead unless vertex data are ve
 
 === API Changes
 
-To build acceleration structures using pre-compressed triangle data, the link:{docs}chapters/accelstructures.html#VkAccelerationStructureGeometryKHR[VkAccelerationStructureGeometryKHR] structure is extended using a new enum value in link:{docs}chapters/resources.html#VkGeometryTypeKHR[VkGeometryTypeKHR]:
+To build acceleration structures using pre-compressed triangle data, the xref:{refpages}VkAccelerationStructureGeometryKHR.html[VkAccelerationStructureGeometryKHR] structure is extended using a new enum value in xref:{refpages}VkGeometryTypeKHR.html[VkGeometryTypeKHR]:
 
 [source,c]
 ----
@@ -164,7 +164,7 @@ typedef enum VkGeometryTypeKHR {
 } VkGeometryTypeKHR;
 ----
 
-When the `geometryType` member of link:{docs}chapters/accelstructures.html#VkAccelerationStructureGeometryKHR[VkAccelerationStructureGeometryKHR] is set to `VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX`, a `VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX` structure in its `pNext` chain describes pre-compressed triangle geometry:
+When the `geometryType` member of xref:{refpages}VkAccelerationStructureGeometryKHR.html[VkAccelerationStructureGeometryKHR] is set to `VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX`, a `VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX` structure in its `pNext` chain describes pre-compressed triangle geometry:
 
 [[VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX-struct]]
 [source,c]
@@ -208,9 +208,9 @@ Two defines are added that specify the alignment and stride requirements of the
 #define VK_COMPRESSED_TRIANGLE_FORMAT_DGF1_BYTE_STRIDE_AMDX 128U
 ----
 
-Note that a host builds are not supported, and a link:{docs}chapters/accelstructures.html#VkAccelerationStructureBuildRangeInfoKHR[VkAccelerationStructureBuildRangeInfoKHR] structure is not used when building an acceleration structure with a geometry type of `VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX`.
+Note that a host builds are not supported, and a xref:{refpages}VkAccelerationStructureBuildRangeInfoKHR.html[VkAccelerationStructureBuildRangeInfoKHR] structure is not used when building an acceleration structure with a geometry type of `VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX`.
 
-To use an link:{docs}chapters/VK_EXT_opacity_micromap/micromaps.html[Opacity Micromap] with the compressed triangle data, a link:{docs}chapters/accelstructures.html#VkAccelerationStructureTrianglesOpacityMicromapEXT[VkAccelerationStructureTrianglesOpacityMicromapEXT] structure can be added to the `pNext` chain of `VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX`.
+To use an xref:{docs}chapters/VK_EXT_opacity_micromap/micromaps.html[Opacity Micromap] with the compressed triangle data, a xref:{refpages}VkAccelerationStructureTrianglesOpacityMicromapEXT.html[VkAccelerationStructureTrianglesOpacityMicromapEXT] structure can be added to the `pNext` chain of `VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX`.
 
 ==== Features
 

proposals/VK_AMDX_shader_enqueue.adoc

@@ -5,7 +5,7 @@
 = VK_AMDX_shader_enqueue
 :toc: left
 :docs: https://docs.vulkan.org/spec/latest/
-:extensions: {docs}appendices/extensions.html#
+:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/
 :sectnums:
 
 This extension adds the ability for developers to enqueue mesh pipelines and compute shader workgroups from other compute shaders.
@@ -90,7 +90,7 @@ VK_PIPELINE_CREATE_2_EXECUTION_GRAPH_BIT_AMDX = 0x100000000ULL
 ----
 
 Each shader in an execution graph is associated with a name and an index, which are used to identify the target shader when dispatching a payload.
-The `VkPipelineShaderStageNodeCreateInfoAMDX` provides options for specifying how the shader is specified with regards to its entry point name and index, and can be chained to the link:{docs}chapters/pipelines.html#VkPipelineShaderStageCreateInfo[VkPipelineShaderStageCreateInfo] structure.
+The `VkPipelineShaderStageNodeCreateInfoAMDX` provides options for specifying how the shader is specified with regards to its entry point name and index, and can be chained to the xref:{refpages}VkPipelineShaderStageCreateInfo.html[VkPipelineShaderStageCreateInfo] structure.
 
 [source,c]
 ----
@@ -124,7 +124,7 @@ Additionally, if an input payload is declared in the dispatched shader, the inpu
 
 When adding a graphics pipeline to an execution graph pipeline, applications must specify a graphics pipeline with a complete set of state, and the `VK_PIPELINE_CREATE_2_LIBRARY_BIT_KHR` and `VK_PIPELINE_CREATE_2_EXECUTION_GRAPH_BIT_AMDX` flags set.
 Graphics pipelines must only include mesh shaders; vertex shader pipelines or mesh pipelines with task shaders are not supported.
-When creating such a graphics pipeline from libraries as an interaction with link:{extensions}VK_EXT_graphics_pipeline_library[VK_EXT_graphics_pipeline_library], those libraries must also have been created with those flags.
+When creating such a graphics pipeline from libraries as an interaction with xref:{refpages}VK_EXT_graphics_pipeline_library.html[VK_EXT_graphics_pipeline_library], those libraries must also have been created with those flags.
 
 For graphics pipelines defined in this way, only the following dynamic state is allowed:
 
@@ -450,9 +450,9 @@ An application must not dispatch the shader with a number of workgroups in any d
 
 `StaticNumWorkgroupsAMDX` allows the declaration of the number of workgroups to dispatch to be coded into the shader itself, which can be useful for optimizing some algorithms. When a compute shader is dispatched using existing `vkCmdDispatchGraph*` commands, the workgroup counts specified there are overridden. When enqueuing such shaders with a payload, these arguments will not be consumed from the payload before application-specified data begins.
 
-The values of `MaxNumWorkgroupsAMDX` and `StaticNumWorkgroupsAMDX` must be less than or equal to `link:{docs}chapters/limits.html#VkPhysicalDeviceShaderEnqueuePropertiesAMDX[VkPhysicalDeviceShaderEnqueuePropertiesAMDX]::maxExecutionGraphWorkgroupCount`.
+The values of `MaxNumWorkgroupsAMDX` and `StaticNumWorkgroupsAMDX` must be less than or equal to `xref:{refpages}VkPhysicalDeviceShaderEnqueuePropertiesAMDX.html[VkPhysicalDeviceShaderEnqueuePropertiesAMDX]::maxExecutionGraphWorkgroupCount`.
 
-The product of the X, Y, and Z values of `MaxNumWorkgroupsAMDX` and `StaticNumWorkgroupsAMDX` must be less than or equal to `link:{docs}chapters/limits.html#VkPhysicalDeviceShaderEnqueuePropertiesAMDX[VkPhysicalDeviceShaderEnqueuePropertiesAMDX]::maxExecutionGraphWorkgroups`.
+The product of the X, Y, and Z values of `MaxNumWorkgroupsAMDX` and `StaticNumWorkgroupsAMDX` must be less than or equal to `xref:{refpages}VkPhysicalDeviceShaderEnqueuePropertiesAMDX.html[VkPhysicalDeviceShaderEnqueuePropertiesAMDX]::maxExecutionGraphWorkgroups`.
 
 The arguments to each of these execution modes must be a constant 32-bit integer value, and may be supplied via specialization constants.
 

proposals/VK_AMD_anti_lag.adoc

@@ -5,7 +5,7 @@
 = VK_AMD_anti_lag
 :toc: left
 :docs: https://docs.vulkan.org/spec/latest/
-:extensions: {docs}appendices/extensions.html#
+:refpages: https://docs.vulkan.org/refpages/latest/refpages/source/
 :sectnums:
 
 This document describes a proposal for a new AMD function that allows the precision of AntiLag to be improved.