Add documentation on capability system. (#3549)

Fixes #3454.

1 files changed, 86 insertions, 74 deletions

diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html
index dceca681f..9e8c6f57d 100644
--- a/docs/user-guide/toc.html
+++ b/docs/user-guide/toc.html
@@ -1,104 +1,116 @@
 <ul class="toc_root_list"><li data-link="index"><span>Slang User's Guide</span>
 <ul class="toc_list">
-<li data-link="00-introduction"><span>Introduction</span>
+<li data-link="introduction"><span>Introduction</span>
 <ul class="toc_list">
-<li data-link="00-introduction#why-use-slang"><span>Why use Slang?</span></li>
-<li data-link="00-introduction#who-is-slang-for"><span>Who is Slang for?</span></li>
-<li data-link="00-introduction#who-is-this-guide-for"><span>Who is this guide for?</span></li>
-<li data-link="00-introduction#goals-and-non-goals"><span>Goals and Non-Goals</span></li>
+<li data-link="introduction#why-use-slang"><span>Why use Slang?</span></li>
+<li data-link="introduction#who-is-slang-for"><span>Who is Slang for?</span></li>
+<li data-link="introduction#who-is-this-guide-for"><span>Who is this guide for?</span></li>
+<li data-link="introduction#goals-and-non-goals"><span>Goals and Non-Goals</span></li>
 </ul>
 </li>
-<li data-link="01-get-started"><span>Getting Started with Slang</span>
+<li data-link="get-started"><span>Getting Started with Slang</span>
 <ul class="toc_list">
-<li data-link="01-get-started#installation"><span>Installation</span></li>
-<li data-link="01-get-started#your-first-slang-shader"><span>Your first Slang shader</span></li>
-<li data-link="01-get-started#the-full-example"><span>The full example</span></li>
+<li data-link="get-started#installation"><span>Installation</span></li>
+<li data-link="get-started#your-first-slang-shader"><span>Your first Slang shader</span></li>
+<li data-link="get-started#the-full-example"><span>The full example</span></li>
 </ul>
 </li>
-<li data-link="02-conventional-features"><span>Conventional Language Features</span>
+<li data-link="conventional-features"><span>Conventional Language Features</span>
 <ul class="toc_list">
-<li data-link="02-conventional-features#types"><span>Types</span></li>
-<li data-link="02-conventional-features#expressions"><span>Expressions</span></li>
-<li data-link="02-conventional-features#statements"><span>Statements</span></li>
-<li data-link="02-conventional-features#functions"><span>Functions</span></li>
-<li data-link="02-conventional-features#preprocessor"><span>Preprocessor</span></li>
-<li data-link="02-conventional-features#attributes"><span>Attributes</span></li>
-<li data-link="02-conventional-features#global-variables-and-shader-parameters"><span>Global Variables and Shader Parameters</span></li>
-<li data-link="02-conventional-features#shader-entry-points"><span>Shader Entry Points</span></li>
+<li data-link="conventional-features#types"><span>Types</span></li>
+<li data-link="conventional-features#expressions"><span>Expressions</span></li>
+<li data-link="conventional-features#statements"><span>Statements</span></li>
+<li data-link="conventional-features#functions"><span>Functions</span></li>
+<li data-link="conventional-features#preprocessor"><span>Preprocessor</span></li>
+<li data-link="conventional-features#attributes"><span>Attributes</span></li>
+<li data-link="conventional-features#global-variables-and-shader-parameters"><span>Global Variables and Shader Parameters</span></li>
+<li data-link="conventional-features#shader-entry-points"><span>Shader Entry Points</span></li>
+<li data-link="conventional-features#mixed-shader-entry-points"><span>Mixed Shader Entry Points</span></li>
 </ul>
 </li>
-<li data-link="03-convenience-features"><span>Basic Convenience Features</span>
+<li data-link="convenience-features"><span>Basic Convenience Features</span>
 <ul class="toc_list">
-<li data-link="03-convenience-features#type-inference-in-variable-definitions"><span>Type Inference in Variable Definitions</span></li>
-<li data-link="03-convenience-features#immutable-values"><span>Immutable Values</span></li>
-<li data-link="03-convenience-features#namespaces"><span>Namespaces</span></li>
-<li data-link="03-convenience-features#member-functions"><span>Member functions</span></li>
-<li data-link="03-convenience-features#properties"><span>Properties</span></li>
-<li data-link="03-convenience-features#initializers"><span>Initializers</span></li>
-<li data-link="03-convenience-features#operator-overloading"><span>Operator Overloading</span></li>
-<li data-link="03-convenience-features#subscript-operator"><span>Subscript Operator</span></li>
-<li data-link="03-convenience-features#optionalt-type"><span>`Optional&lt;T&gt;` type</span></li>
-<li data-link="03-convenience-features#reinterprett-operation"><span>`reinterpret&lt;T&gt;` operation</span></li>
-<li data-link="03-convenience-features#struct-inheritance-limited"><span>`struct` inheritance (limited)</span></li>
-<li data-link="03-convenience-features#extensions"><span>Extensions</span></li>
-<li data-link="03-convenience-features#multi-level-break"><span>Multi-level break</span></li>
-<li data-link="03-convenience-features#force-inlining"><span>Force inlining</span></li>
-<li data-link="03-convenience-features#special-scoping-syntax"><span>Special Scoping Syntax</span></li>
+<li data-link="convenience-features#type-inference-in-variable-definitions"><span>Type Inference in Variable Definitions</span></li>
+<li data-link="convenience-features#immutable-values"><span>Immutable Values</span></li>
+<li data-link="convenience-features#namespaces"><span>Namespaces</span></li>
+<li data-link="convenience-features#member-functions"><span>Member functions</span></li>
+<li data-link="convenience-features#properties"><span>Properties</span></li>
+<li data-link="convenience-features#initializers"><span>Initializers</span></li>
+<li data-link="convenience-features#operator-overloading"><span>Operator Overloading</span></li>
+<li data-link="convenience-features#subscript-operator"><span>Subscript Operator</span></li>
+<li data-link="convenience-features#optionalt-type"><span>`Optional&lt;T&gt;` type</span></li>
+<li data-link="convenience-features#reinterprett-operation"><span>`reinterpret&lt;T&gt;` operation</span></li>
+<li data-link="convenience-features#struct-inheritance-limited"><span>`struct` inheritance (limited)</span></li>
+<li data-link="convenience-features#extensions"><span>Extensions</span></li>
+<li data-link="convenience-features#multi-level-break"><span>Multi-level break</span></li>
+<li data-link="convenience-features#force-inlining"><span>Force inlining</span></li>
+<li data-link="convenience-features#special-scoping-syntax"><span>Special Scoping Syntax</span></li>
 </ul>
 </li>
-<li data-link="04-modules-and-access-control"><span>Modules and Access Control</span>
+<li data-link="modules"><span>Modules and Access Control</span>
 <ul class="toc_list">
-<li data-link="04-modules-and-access-control#defining-a-module"><span>Defining a Module</span></li>
-<li data-link="04-modules-and-access-control#importing-a-module"><span>Importing a Module</span></li>
-<li data-link="04-modules-and-access-control#access-control"><span>Access Control</span></li>
-<li data-link="04-modules-and-access-control#legacy-modules"><span>Legacy Modules</span></li>
+<li data-link="modules#defining-a-module"><span>Defining a Module</span></li>
+<li data-link="modules#importing-a-module"><span>Importing a Module</span></li>
+<li data-link="modules#access-control"><span>Access Control</span></li>
+<li data-link="modules#legacy-modules"><span>Legacy Modules</span></li>
 </ul>
 </li>
-<li data-link="05-interfaces-generics"><span>Interfaces and Generics</span>
+<li data-link="capabilities"><span>Capabilities</span>
 <ul class="toc_list">
-<li data-link="05-interfaces-generics#interfaces"><span>Interfaces</span></li>
-<li data-link="05-interfaces-generics#generics"><span>Generics</span></li>
-<li data-link="05-interfaces-generics#supported-constructs-in-interface-definitions"><span>Supported Constructs in Interface Definitions</span></li>
-<li data-link="05-interfaces-generics#associated-types"><span>Associated Types</span></li>
-<li data-link="05-interfaces-generics#generic-value-parameters"><span>Generic Value Parameters</span></li>
-<li data-link="05-interfaces-generics#interface-typed-values"><span>Interface-typed Values</span></li>
-<li data-link="05-interfaces-generics#extending-a-type-with-additional-interface-conformances"><span>Extending a Type with Additional Interface Conformances</span></li>
-<li data-link="05-interfaces-generics#is-and-as-operator"><span>`is` and `as` Operator</span></li>
-<li data-link="05-interfaces-generics#extensions-to-interfaces"><span>Extensions to Interfaces</span></li>
+<li data-link="capabilities#capability-atoms-and-capability-requirements"><span>Capability Atoms and Capability Requirements</span></li>
+<li data-link="capabilities#conflicting-capabilities"><span>Conflicting Capabilities</span></li>
+<li data-link="capabilities#requirements-in-parent-scope"><span>Requirements in Parent Scope</span></li>
+<li data-link="capabilities#inferrence-of-capability-requirements"><span>Inferrence of Capability Requirements</span></li>
+<li data-link="capabilities#inferrence-on-target-switch"><span>Inferrence on target_switch</span></li>
+<li data-link="capabilities#capability-aliases"><span>Capability Aliases</span></li>
+<li data-link="capabilities#validation-of-capability-requirements"><span>Validation of Capability Requirements</span></li>
 </ul>
 </li>
-<li data-link="06-compiling"><span>Compiling Code with Slang</span>
+<li data-link="interfaces-generics"><span>Interfaces and Generics</span>
 <ul class="toc_list">
-<li data-link="06-compiling#concepts"><span>Concepts</span></li>
-<li data-link="06-compiling#command-line-compilation-with-slangc"><span>Command-Line Compilation with `slangc`</span></li>
-<li data-link="06-compiling#using-the-compilation-api"><span>Using the Compilation API</span></li>
+<li data-link="interfaces-generics#interfaces"><span>Interfaces</span></li>
+<li data-link="interfaces-generics#generics"><span>Generics</span></li>
+<li data-link="interfaces-generics#supported-constructs-in-interface-definitions"><span>Supported Constructs in Interface Definitions</span></li>
+<li data-link="interfaces-generics#associated-types"><span>Associated Types</span></li>
+<li data-link="interfaces-generics#generic-value-parameters"><span>Generic Value Parameters</span></li>
+<li data-link="interfaces-generics#interface-typed-values"><span>Interface-typed Values</span></li>
+<li data-link="interfaces-generics#extending-a-type-with-additional-interface-conformances"><span>Extending a Type with Additional Interface Conformances</span></li>
+<li data-link="interfaces-generics#is-and-as-operator"><span>`is` and `as` Operator</span></li>
+<li data-link="interfaces-generics#extensions-to-interfaces"><span>Extensions to Interfaces</span></li>
 </ul>
 </li>
-<li data-link="07-targets"><span>Supported Compilation Targets</span>
+<li data-link="autodiff"><span>Automatic Differentiation</span>
 <ul class="toc_list">
-<li data-link="07-targets#background-and-terminology"><span>Background and Terminology</span></li>
-<li data-link="07-targets#direct3d-11"><span>Direct3D 11</span></li>
-<li data-link="07-targets#direct3d-12"><span>Direct3D 12</span></li>
-<li data-link="07-targets#vulkan"><span>Vulkan</span></li>
-<li data-link="07-targets#opengl"><span>OpenGL</span></li>
-<li data-link="07-targets#cuda-and-optix"><span>CUDA and OptiX</span></li>
-<li data-link="07-targets#cpu-compute"><span>CPU Compute</span></li>
-<li data-link="07-targets#summary"><span>Summary</span></li>
+<li data-link="autodiff#using-automatic-differentiation-in-slang"><span>Using Automatic Differentiation in Slang</span></li>
+<li data-link="autodiff#mathematic-concepts-and-terminologies"><span>Mathematic Concepts and Terminologies</span></li>
+<li data-link="autodiff#differentiable-types"><span>Differentiable Types</span></li>
+<li data-link="autodiff#forward-derivative-propagation-function"><span>Forward Derivative Propagation Function</span></li>
+<li data-link="autodiff#backward-derivative-propagation-function"><span>Backward Derivative Propagation Function</span></li>
+<li data-link="autodiff#builtin-differentiable-functions"><span>Builtin Differentiable Functions</span></li>
+<li data-link="autodiff#primal-substitute-functions"><span>Primal Substitute Functions</span></li>
+<li data-link="autodiff#working-with-mixed-differentiable-and-non-differentiable-code"><span>Working with Mixed Differentiable and Non-Differentiable Code</span></li>
+<li data-link="autodiff#higher-order-differentiation"><span>Higher Order Differentiation</span></li>
+<li data-link="autodiff#interactions-with-generics-and-interfaces"><span>Interactions with Generics and Interfaces</span></li>
+<li data-link="autodiff#restrictions-of-automatic-differentiation"><span>Restrictions of Automatic Differentiation</span></li>
 </ul>
 </li>
-<li data-link="08-autodiff"><span>Automatic Differentiation</span>
+<li data-link="compiling"><span>Compiling Code with Slang</span>
 <ul class="toc_list">
-<li data-link="08-autodiff#using-automatic-differentiation-in-slang"><span>Using Automatic Differentiation in Slang</span></li>
-<li data-link="08-autodiff#mathematic-concepts-and-terminologies"><span>Mathematic Concepts and Terminologies</span></li>
-<li data-link="08-autodiff#differentiable-types"><span>Differentiable Types</span></li>
-<li data-link="08-autodiff#forward-derivative-propagation-function"><span>Forward Derivative Propagation Function</span></li>
-<li data-link="08-autodiff#backward-derivative-propagation-function"><span>Backward Derivative Propagation Function</span></li>
-<li data-link="08-autodiff#builtin-differentiable-functions"><span>Builtin Differentiable Functions</span></li>
-<li data-link="08-autodiff#primal-substitute-functions"><span>Primal Substitute Functions</span></li>
-<li data-link="08-autodiff#working-with-mixed-differentiable-and-non-differentiable-code"><span>Working with Mixed Differentiable and Non-Differentiable Code</span></li>
-<li data-link="08-autodiff#higher-order-differentiation"><span>Higher Order Differentiation</span></li>
-<li data-link="08-autodiff#interactions-with-generics-and-interfaces"><span>Interactions with Generics and Interfaces</span></li>
-<li data-link="08-autodiff#restrictions-of-automatic-differentiation"><span>Restrictions of Automatic Differentiation</span></li>
+<li data-link="compiling#concepts"><span>Concepts</span></li>
+<li data-link="compiling#command-line-compilation-with-slangc"><span>Command-Line Compilation with `slangc`</span></li>
+<li data-link="compiling#using-the-compilation-api"><span>Using the Compilation API</span></li>
+</ul>
+</li>
+<li data-link="targets"><span>Supported Compilation Targets</span>
+<ul class="toc_list">
+<li data-link="targets#background-and-terminology"><span>Background and Terminology</span></li>
+<li data-link="targets#direct3d-11"><span>Direct3D 11</span></li>
+<li data-link="targets#direct3d-12"><span>Direct3D 12</span></li>
+<li data-link="targets#vulkan"><span>Vulkan</span></li>
+<li data-link="targets#opengl"><span>OpenGL</span></li>
+<li data-link="targets#cuda-and-optix"><span>CUDA and OptiX</span></li>
+<li data-link="targets#cpu-compute"><span>CPU Compute</span></li>
+<li data-link="targets#summary"><span>Summary</span></li>
 </ul>
 </li>
 <li data-link="a1-special-topics"><span>Special Topics</span>