Fix Antora bugs related to using xref instead of Link.

gpx1000 · gpx1000 · commit 4dcb0f0e0010 · 2026-01-03T03:12:28.000-08:00
diff --git a/en/Building_a_Simple_Engine/Advanced_Topics/01_introduction.adoc b/en/Building_a_Simple_Engine/Advanced_Topics/01_introduction.adoc
@@ -6,22 +6,22 @@ Welcome — this section collects short, conversational guides that explain what
 
 Start anywhere that matches your interest:
 
-* xref:Planar_Reflections.adoc[Planar Reflections]
-* xref:Ray_Query_Rendering.adoc[Ray Query Rendering]
-* xref:Ray_Query_Reflections_and_Transparency.adoc[Ray Query Reflections and Transparency]
-* xref:Rendering_Pipeline_Overview.adoc[Rendering Pipeline Overview]
-* xref:Forward_ForwardPlus_Deferred.adoc[Forward, Forward+, Deferred]
-* xref:ForwardPlus_Rendering.adoc[Forward+ Rendering]
-* xref:Culling.adoc[Frustum Culling and Distance LOD]
-* xref:Mipmaps_and_LOD.adoc[Mipmaps and LOD]
-* xref:GLTF_Animation.adoc[glTF Animation & Transform Composition]
-* xref:Push_Constants_Per_Object.adoc[Push Constants (per‑object material)]
-* xref:Descriptor_Indexing_UpdateAfterBind.adoc[Descriptor Indexing & Stable Updates]
-* xref:Separate_Image_Sampler_Descriptors.adoc[Separate Image/Sampler]
-* xref:Synchronization_and_Streaming.adoc[Synchronization & Streaming]
-* xref:Synchronization_2_Frame_Pacing.adoc[Synchronization 2 & Frame Pacing]
-* xref:Robustness2.adoc[VK_EXT_robustness2]
-* xref:Dynamic_Rendering_Local_Read.adoc[Dynamic Rendering Local Read]
-* xref:Shader_Tile_Image.adoc[Shader Tile Image]
+* link:Planar_Reflections.adoc[Planar Reflections]
+* link:Ray_Query_Rendering.adoc[Ray Query Rendering]
+* link:Ray_Query_Reflections_and_Transparency.adoc[Ray Query Reflections and Transparency]
+* link:Rendering_Pipeline_Overview.adoc[Rendering Pipeline Overview]
+* link:Forward_ForwardPlus_Deferred.adoc[Forward, Forward+, Deferred]
+* link:ForwardPlus_Rendering.adoc[Forward+ Rendering]
+* link:Culling.adoc[Frustum Culling and Distance LOD]
+* link:Mipmaps_and_LOD.adoc[Mipmaps and LOD]
+* link:GLTF_Animation.adoc[glTF Animation & Transform Composition]
+* link:Push_Constants_Per_Object.adoc[Push Constants (per‑object material)]
+* link:Descriptor_Indexing_UpdateAfterBind.adoc[Descriptor Indexing & Stable Updates]
+* link:Separate_Image_Sampler_Descriptors.adoc[Separate Image/Sampler]
+* link:Synchronization_and_Streaming.adoc[Synchronization & Streaming]
+* link:Synchronization_2_Frame_Pacing.adoc[Synchronization 2 & Frame Pacing]
+* link:Robustness2.adoc[VK_EXT_robustness2]
+* link:Dynamic_Rendering_Local_Read.adoc[Dynamic Rendering Local Read]
+* link:Shader_Tile_Image.adoc[Shader Tile Image]
 
 link:../index.html[Back to Building a Simple Engine]
diff --git a/en/Building_a_Simple_Engine/Appendix/appendix.adoc b/en/Building_a_Simple_Engine/Appendix/appendix.adoc
@@ -335,5 +335,5 @@ When designing your engine architecture, consider:
 3. *Team Size and Experience* - More complex architectures may be harder to work with for smaller teams.
 4. *Project Scope* - A small project may not need the complexity of a full ECS.
 
-xref:../Engine_Architecture/02_architectural_patterns.adoc[Back to Architectural Patterns]
-xref:../Engine_Architecture/05_rendering_pipeline.adoc[Back to Rendering Pipeline]
+link:../Engine_Architecture/02_architectural_patterns.adoc[Back to Architectural Patterns]
+link:../Engine_Architecture/05_rendering_pipeline.adoc[Back to Rendering Pipeline]
diff --git a/en/Building_a_Simple_Engine/Camera_Transformations/01_introduction.adoc b/en/Building_a_Simple_Engine/Camera_Transformations/01_introduction.adoc
@@ -28,4 +28,4 @@ Before starting this chapter, you should have completed the main Vulkan tutorial
 * xref:../../05_Uniform_buffers/00_Descriptor_set_layout_and_buffer.adoc[Uniform buffers]
 * Basic programming concepts and C++
 
-xref:02_math_foundations.adoc[Next: Mathematical Foundations]
+link:02_math_foundations.adoc[Next: Mathematical Foundations]
diff --git a/en/Building_a_Simple_Engine/Camera_Transformations/04_camera_implementation.adoc b/en/Building_a_Simple_Engine/Camera_Transformations/04_camera_implementation.adoc
@@ -686,9 +686,9 @@ void gameLoop(float deltaTime) {
 
 [NOTE]
 ====
-For more advanced camera techniques, refer to the Advanced Camera Techniques section in the xref:../Appendix/appendix.adoc[Appendix].
+For more advanced camera techniques, refer to the Advanced Camera Techniques section in the link:../Appendix/appendix.adoc[Appendix].
 ====
 
 In the next section, we'll integrate our camera system with Vulkan to render 3D scenes.
 
-xref:05_vulkan_integration.adoc[Next: Vulkan Integration]
+link:05_vulkan_integration.adoc[Next: Vulkan Integration]
diff --git a/en/Building_a_Simple_Engine/Camera_Transformations/06_conclusion.adoc b/en/Building_a_Simple_Engine/Camera_Transformations/06_conclusion.adoc
@@ -52,4 +52,4 @@ A well-designed camera system is essential for any 3D application. It serves as
 
 Remember that the code provided in this chapter is a starting point. Feel free to modify and extend it to suit your specific needs and application requirements.
 
-xref:../Engine_Architecture/conclusion.adoc[Previous: Engine Architecture] | xref:../Lighting_Materials/01_introduction.adoc[Next: Lighting & Materials]
+link:../Engine_Architecture/conclusion.adoc[Previous: Engine Architecture] | link:../Lighting_Materials/01_introduction.adoc[Next: Lighting & Materials]
diff --git a/en/Building_a_Simple_Engine/Engine_Architecture/02_architectural_patterns.adoc b/en/Building_a_Simple_Engine/Engine_Architecture/02_architectural_patterns.adoc
@@ -23,7 +23,7 @@ image::../../../images/layered_architecture_diagram.png[Layered Architecture Dia
 * Easier to understand and maintain
 * Can replace or modify individual layers without affecting others
 
-For detailed information and implementation examples, see the xref:../Appendix/appendix.adoc#layered-architecture[Appendix: Layered Architecture].
+For detailed information and implementation examples, see the link:../Appendix/appendix.adoc#layered-architecture[Appendix: Layered Architecture].
 
 ==== link:https://www.youtube.com/watch?v=rX0ItVEVjHc[Data-Oriented Design]
 
@@ -36,7 +36,7 @@ image::../../../images/data_oriented_design_diagram.svg[Data-Oriented Design Dia
 * More efficient memory usage
 * Easier to parallelize
 
-For detailed information and implementation examples, see the xref:../Appendix/appendix.adoc#data-oriented-design[Appendix: Data-Oriented Design].
+For detailed information and implementation examples, see the link:../Appendix/appendix.adoc#data-oriented-design[Appendix: Data-Oriented Design].
 
 ==== link:https://gameprogrammingpatterns.com/service-locator.html[Service Locator Pattern]
 
@@ -49,7 +49,7 @@ image::../../../images/service_locator_pattern_diagram.svg[Service Locator Patte
 * Allows for easy service replacement
 * Facilitates testing with mock services
 
-For detailed information and implementation examples, see the xref:../Appendix/appendix.adoc#service-locator-pattern[Appendix: Service Locator Pattern].
+For detailed information and implementation examples, see the link:../Appendix/appendix.adoc#service-locator-pattern[Appendix: Service Locator Pattern].
 
 === link:https://gameprogrammingpatterns.com/component.html[Component-Based Architecture]
 
@@ -164,8 +164,8 @@ While other architectural patterns have their merits, component-based architectu
 
 === Conclusion
 
-We've provided a brief overview of common architectural patterns, with a focus on Component-Based Architecture which we'll use throughout this tutorial. For more detailed information about other architectural patterns, including implementation examples and comparative analysis, see the xref:../Appendix/appendix.adoc[Appendix: Detailed Architectural Patterns].
+We've provided a brief overview of common architectural patterns, with a focus on Component-Based Architecture which we'll use throughout this tutorial. For more detailed information about other architectural patterns, including implementation examples and comparative analysis, see the link:../Appendix/appendix.adoc[Appendix: Detailed Architectural Patterns].
 
 In the next section, we'll dive deeper into component systems and how to implement them effectively in your engine.
 
-xref:01_introduction.adoc[Previous: Introduction] | xref:03_component_systems.adoc[Next: Component Systems]
+link:01_introduction.adoc[Previous: Introduction] | link:03_component_systems.adoc[Next: Component Systems]
diff --git a/en/Building_a_Simple_Engine/Engine_Architecture/conclusion.adoc b/en/Building_a_Simple_Engine/Engine_Architecture/conclusion.adoc
@@ -36,7 +36,7 @@ The architectural foundation we've established in this chapter will support ever
 
 Active implementation proves far more valuable than passive reading when learning engine architecture. Build the code examples as you encounter them, but don't stop there—experiment with variations to understand how different approaches affect your engine's behavior. This experimentation develops the intuitive understanding that separates competent engine developers from those who merely copy implementations.
 
-The architectural concepts we've covered provide a foundation, but production engines require additional sophistication. The xref:../Appendix/appendix.adoc[Appendix] explores advanced rendering techniques and architectural patterns that build on these fundamentals, helping you understand how simple patterns scale to handle complex real-world requirements.
+The architectural concepts we've covered provide a foundation, but production engines require additional sophistication. The link:../Appendix/appendix.adoc[Appendix] explores advanced rendering techniques and architectural patterns that build on these fundamentals, helping you understand how simple patterns scale to handle complex real-world requirements.
 
 Studying existing open-source engines like link:https://github.com/TheCherno/Hazel[Hazel] or examining the architectural decisions in established frameworks like link:https://github.com/LWJGL/lwjgl3[LWJGL] provides valuable perspective on how these concepts apply in practice. Look for patterns we've discussed and notice how different engines make different trade-offs based on their specific goals and constraints.
 
@@ -50,4 +50,4 @@ Building a rendering engine is a challenging but rewarding endeavor. By applying
 
 Good luck with your engine development journey!
 
-xref:06_event_systems.adoc[Previous: Event Systems] | xref:../Camera_Transformations/01_introduction.adoc[Next: Camera Transformations]
+link:06_event_systems.adoc[Previous: Event Systems] | link:../Camera_Transformations/01_introduction.adoc[Next: Camera Transformations]
diff --git a/en/Building_a_Simple_Engine/Loading_Models/01_introduction.adoc b/en/Building_a_Simple_Engine/Loading_Models/01_introduction.adoc
@@ -30,4 +30,4 @@ xref:../../06_Texture_mapping/00_Images.adoc[Texture mapping] skills are particu
 
 Finally, basic 3D math understanding (matrices, vectors, quaternions) is crucial for handling model transformations, animations, and scene hierarchies. If you need a refresher, see the xref:../../Building_a_Simple_Engine/Camera_Transformations/02_math_foundations.adoc[Camera Transformations chapter] for detailed coverage of these mathematical concepts.
 
-xref:../GUI/06_conclusion.adoc[Previous: GUI] | xref:02_project_setup.adoc[Next: Setting Up the Project]
+link:../GUI/06_conclusion.adoc[Previous: GUI] | link:02_project_setup.adoc[Next: Setting Up the Project]
diff --git a/en/Building_a_Simple_Engine/Loading_Models/05_pbr_rendering.adoc b/en/Building_a_Simple_Engine/Loading_Models/05_pbr_rendering.adoc
@@ -6,7 +6,7 @@
 
 === Building on PBR Knowledge
 
-In the xref:../Lighting_Materials/01_introduction.adoc[Lighting & Materials chapter], we explored the fundamentals of Physically Based Rendering (PBR), including its core principles, the BRDF, and material properties. Now, we'll apply that knowledge to implement a PBR pipeline for the glTF models we've loaded.
+In the link:../Lighting_Materials/01_introduction.adoc[Lighting & Materials chapter], we explored the fundamentals of Physically Based Rendering (PBR), including its core principles, the BRDF, and material properties. Now, we'll apply that knowledge to implement a PBR pipeline for the glTF models we've loaded.
 
 As we learned in the link:../../15_GLTF_KTX2_Migration.html[glTF and KTX2 Migration chapter], glTF uses PBR with the metallic-roughness workflow for its material system. This aligns perfectly with the PBR concepts we've already covered, making it straightforward to render our glTF models with physically accurate lighting.
 
@@ -61,7 +61,7 @@ This uniform buffer includes:
 
 [NOTE]
 ====
-We introduced push constants earlier in xref:../Lighting_Materials/03_push_constants.adoc[push constants]; here we focus on how the same mechanism carries glTF metallic‑roughness material knobs efficiently per draw.
+We introduced push constants earlier in link:../Lighting_Materials/03_push_constants.adoc[push constants]; here we focus on how the same mechanism carries glTF metallic‑roughness material knobs efficiently per draw.
 ====
 
 We'll use link:https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#descriptorsets-pushconstant[push constants] to pass material properties to the shader:
@@ -574,4 +574,4 @@ In the next chapter, we'll explore how to render multiple objects with different
 
 If you want to dive deeper into lighting and materials, refer back to the Lighting & Materials chapter, where we explored the theory behind PBR in detail.
 
-xref:04_loading_gltf.adoc[Previous: Loading a glTF Model] | xref:06_multiple_objects.adoc[Next: Rendering Multiple Objects]
+link:04_loading_gltf.adoc[Previous: Loading a glTF Model] | link:06_multiple_objects.adoc[Next: Rendering Multiple Objects]
diff --git a/en/Building_a_Simple_Engine/Mobile_Development/06_conclusion.adoc b/en/Building_a_Simple_Engine/Mobile_Development/06_conclusion.adoc
@@ -193,9 +193,9 @@ private:
 
 The following short, focused tutorials build directly on the Simple Engine and are great next steps:
 
-- xref:../Advanced_Topics/01_introduction.adoc[Tutorials Index — browse all topics]
-- xref:../Advanced_Topics/Mipmaps_and_LOD.adoc[Mipmaps and LOD] — practical guidance on stable texture sampling and anisotropy.
-- xref:../Advanced_Topics/Dynamic_Rendering_Local_Read.adoc[Dynamic Rendering Local Read] — optimize same‑pass reads via tile/local memory when supported.
+- link:../Advanced_Topics/01_introduction.adoc[Tutorials Index — browse all topics]
+- link:../Advanced_Topics/Mipmaps_and_LOD.adoc[Mipmaps and LOD] — practical guidance on stable texture sampling and anisotropy.
+- link:../Advanced_Topics/Dynamic_Rendering_Local_Read.adoc[Dynamic Rendering Local Read] — optimize same‑pass reads via tile/local memory when supported.
 
 === Code Examples
 
@@ -206,4 +206,4 @@ link:../../attachments/simple_engine/37_mobile_optimizations.cpp[Mobile Optimiza
 link:../../attachments/simple_engine/38_tbr_optimizations.cpp[TBR Optimizations C{pp} code]
 link:../../attachments/simple_engine/39_mobile_extensions.cpp[Mobile Extensions C{pp} code]
 
-xref:05_vulkan_extensions.adoc[Previous: Vulkan Extensions for Mobile] | link:../index.html[Back to Building a Simple Engine]
+link:05_vulkan_extensions.adoc[Previous: Vulkan Extensions for Mobile] | link:../index.html[Back to Building a Simple Engine]
diff --git a/en/Building_a_Simple_Engine/Subsystems/06_conclusion.adoc b/en/Building_a_Simple_Engine/Subsystems/06_conclusion.adoc
@@ -108,4 +108,4 @@ The complete code for this chapter can be found in the following files:
 link:../../attachments/simple_engine/30_audio_subsystem.cpp[Audio Subsystem C{pp} code]
 link:../../attachments/simple_engine/31_physics_subsystem.cpp[Physics Subsystem C{pp} code]
 
-xref:05_vulkan_physics.adoc[Previous: Vulkan for Physics Simulation] | xref:../Tooling/01_introduction.adoc[Next: Tooling] | link:../index.html[Back to Building a Simple Engine]
+link:05_vulkan_physics.adoc[Previous: Vulkan for Physics Simulation] | link:../Tooling/01_introduction.adoc[Next: Tooling] | link:../index.html[Back to Building a Simple Engine]
diff --git a/en/Building_a_Simple_Engine/Tooling/07_conclusion.adoc b/en/Building_a_Simple_Engine/Tooling/07_conclusion.adoc
@@ -229,4 +229,4 @@ link:../../attachments/simple_engine/33_debug_utils.cpp[Debug Utils C{pp} code]
 link:../../attachments/simple_engine/34_crash_handling.cpp[Crash Handling C{pp} code]
 link:../../attachments/simple_engine/35_robustness_extensions.cpp[Robustness Extensions C{pp} code]
 
-xref:06_packaging_and_distribution.adoc[Previous: Packaging and Distribution] | xref:../Mobile_Development/01_introduction.adoc[Next: Mobile Development]
+link:06_packaging_and_distribution.adoc[Previous: Packaging and Distribution] | link:../Mobile_Development/01_introduction.adoc[Next: Mobile Development]
diff --git a/en/Building_a_Simple_Engine/introduction.adoc b/en/Building_a_Simple_Engine/introduction.adoc
@@ -36,18 +36,18 @@ Each chapter builds on the last to assemble a small but capable engine. Read a c
 
 Let's begin our journey into engine development with these chapters:
 
-1. xref:Engine_Architecture/01_introduction.adoc[Engine Architecture] - How to structure your code for flexibility, maintainability, and extensibility.
-2. xref:Camera_Transformations/01_introduction.adoc[Camera Transformations] - Implementation of camera systems and transformations.
-3. xref:Lighting_Materials/01_introduction.adoc[Lighting & Materials] - Basic lighting models and push constants.
-4. xref:GUI/01_introduction.adoc[GUI] - Implementation of a graphical user interface using Dear ImGui.
-5. xref:Loading_Models/01_introduction.adoc[Loading Models] - More sophisticated approaches to handling models, textures, and other assets.
-6. xref:Subsystems/01_introduction.adoc[Subsystems] - Implementation of Audio and Physics subsystems with Vulkan compute capabilities.
-7. xref:Tooling/01_introduction.adoc[Tooling] - CI/CD, Debugging, Crash minidump, Distribution, and Vulkan extensions for robustness.
-8. xref:Mobile_Development/01_introduction.adoc[Mobile Development] - Adapting the engine for Android/iOS, focusing on performance considerations and mobile-specific Vulkan extensions.
-
-9. xref:Advanced_Topics/01_introduction.adoc[Advanced Topics] - Short, focused tutorials that extend the Simple Engine with specific features and optimizations.
-
-xref:../conclusion.adoc[Previous: Main Tutorial Conclusion] | xref:Engine_Architecture/01_introduction.adoc[Next: Engine Architecture]
+1. link:Engine_Architecture/01_introduction.adoc[Engine Architecture] - How to structure your code for flexibility, maintainability, and extensibility.
+2. link:Camera_Transformations/01_introduction.adoc[Camera Transformations] - Implementation of camera systems and transformations.
+3. link:Lighting_Materials/01_introduction.adoc[Lighting & Materials] - Basic lighting models and push constants.
+4. link:GUI/01_introduction.adoc[GUI] - Implementation of a graphical user interface using Dear ImGui.
+5. link:Loading_Models/01_introduction.adoc[Loading Models] - More sophisticated approaches to handling models, textures, and other assets.
+6. link:Subsystems/01_introduction.adoc[Subsystems] - Implementation of Audio and Physics subsystems with Vulkan compute capabilities.
+7. link:Tooling/01_introduction.adoc[Tooling] - CI/CD, Debugging, Crash minidump, Distribution, and Vulkan extensions for robustness.
+8. link:Mobile_Development/01_introduction.adoc[Mobile Development] - Adapting the engine for Android/iOS, focusing on performance considerations and mobile-specific Vulkan extensions.
+
+9. link:Advanced_Topics/01_introduction.adoc[Advanced Topics] - Short, focused tutorials that extend the Simple Engine with specific features and optimizations.
+
+xref:../conclusion.adoc[Previous: Main Tutorial Conclusion] | link:Engine_Architecture/01_introduction.adoc[Next: Engine Architecture]
 
 
 === Getting Started with Example Assets

Original file line number	Diff line number	Diff line change
`@@ -52,4 +52,4 @@ A well-designed camera system is essential for any 3D application. It serves as`
`52`	`52`
`53`	`53`	`Remember that the code provided in this chapter is a starting point. Feel free to modify and extend it to suit your specific needs and application requirements.`
`54`	`54`
`55`		`-xref:../Engine_Architecture/conclusion.adoc[Previous: Engine Architecture] \| xref:../Lighting_Materials/01_introduction.adoc[Next: Lighting & Materials]`
	`55`	`+link:../Engine_Architecture/conclusion.adoc[Previous: Engine Architecture] \| link:../Lighting_Materials/01_introduction.adoc[Next: Lighting & Materials]`
Original file line number	Diff line number	Diff line change
`@@ -30,4 +30,4 @@ xref:../../06_Texture_mapping/00_Images.adoc[Texture mapping] skills are particu`
`30`	`30`
`31`	`31`	`Finally, basic 3D math understanding (matrices, vectors, quaternions) is crucial for handling model transformations, animations, and scene hierarchies. If you need a refresher, see the xref:../../Building_a_Simple_Engine/Camera_Transformations/02_math_foundations.adoc[Camera Transformations chapter] for detailed coverage of these mathematical concepts.`
`32`	`32`
`33`		`-xref:../GUI/06_conclusion.adoc[Previous: GUI] \| xref:02_project_setup.adoc[Next: Setting Up the Project]`
	`33`	`+link:../GUI/06_conclusion.adoc[Previous: GUI] \| link:02_project_setup.adoc[Next: Setting Up the Project]`