From 5fe81afdd80d97b5a8ed5a4b5513f5b8de643df0 Mon Sep 17 00:00:00 2001
From: pixar-oss <pixar-oss@users.noreply.github.com>
Date: Thu, 13 Apr 2023 11:16:32 -0700
Subject: [PATCH] Adding info on changing metadata via variants

Fixes #2326

(Internal change: 2271575)
---
 docs/glossary.rst | 40 ++++++++++++++++++++++++++++++++--------
 1 file changed, 32 insertions(+), 8 deletions(-)

diff --git a/docs/glossary.rst b/docs/glossary.rst
index ccbc447a25..27b4200a3b 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -3350,6 +3350,38 @@ with the addition of allowing the "-" character, and an optional leading ".".
    {
    }
 
+A variant can contain overriding opinions (for properties, metadata, and more),
+as well as any arbitrary scene description (entire child prim subtrees, etc).
+Variants can also **include additional composition arcs**. This gives us great
+flexibility in building up variations out of existing, modular pieces that
+can be `referenced <#usdglossary-references>`_, `inherited
+<#usdglossary-inherits>`_, etc. In the following example snippet, the 
+"referenceVariantSet" VariantSet contains two variants that reference different
+USD assets. Changing the variant selection controls which asset is referenced in 
+the scene.
+
+.. code-block:: usda
+   :caption: VariantSet with references
+
+   over "Model" (
+       prepend variantSets = "referenceVariantSet"
+       variants = {
+          string referenceVariantSet = "asset1"
+       }
+   )
+   {
+       variantSet "referenceVariantSet" = {
+           "asset1" (
+               prepend references = @Asset1.usda@
+           ) {          
+           }
+           "asset2" (
+               prepend references = @Asset2.usda@
+           ) {          
+           }
+       }
+   }
+
 .. _usdglossary-variantset:
 
 VariantSet
@@ -3447,14 +3479,6 @@ Here is an example of a very simple VariantSet:
 
        ..
 
-    * Each Variant can contain arbitrary scene description **including the
-      introduction of additional composition arcs**. This gives us great
-      flexibility in building up variations out of existing, modular pieces that
-      can be `referenced <#usdglossary-references>`_, `inherited
-      <#usdglossary-inherits>`_, etc.
-
-       ..
-
     * Because VariantSets are just composition arcs, this implies that
       **VariantSets can be directly nested inside each other**, by allowing a
       Variant of a VariantSet to introduce a new VariantSet. This allows a