Documentation doesn't show what metadata variants can change

[dgovil]

The documentation on Variants doesn't mention that it can modify metadata on the prim that encloses it, such as modifying the references list like so.

variantSet "models" = {
    "model_cool" (
        prepend references = @./cool.usdz@
    ) {

    }
}

The glossary here: https://graphics.pixar.com/usd/release/glossary.html#usdglossary-variantset
and the tutorial here: https://graphics.pixar.com/usd/release/tut_authoring_variants.html
do not make mention of it. Additionally searching the examples in extras/ in the repo doesn't show any hits.

Additionally, looking at this page here: https://graphics.pixar.com/usd/dev/api/_usd__page__object_model.html#Usd_OM_OtherObjects

The documentation stops at a section called ListOps and List Editing under the Composition Operator Interfaces: UsdReferences, UsdInherits, UsdVariantSets section. It looks like it's meant to reference in some other piece of doc that isn't working?

I think it would be great if the docs/examples were updated to show that variants can modify prim references, since it seems like a useful feature that is under-utilized as a result.

[spiffmon]

Good call, @dgovil ! We in fact use that pattern extensively in our shading layers.

[spiffmon]

And to set expectations... remember that within a layerStack, LIVRPS encapsulates each of the arc-types (except for specializes), so if the "base prim" has references on it also, then the references that any Variants adds will be stronger than the base-prim-references, because V comes before R

[sunyab]

Filed as internal issue #USD-8087