[Bf-docboard-svn] bf-manual: [9510] branches/blender-3.3-release/blender_docs/manual/files/linked_libraries: Update LibOverride page to match recent changes in 3.3.

Wed Aug 24 17:30:47 CEST 2022

Revision: 9510
          https://developer.blender.org/rBM9510
Author:   mont29
Date:     2022-08-24 17:30:47 +0200 (Wed, 24 Aug 2022)
Log Message:
-----------
Update LibOverride page to match recent changes in 3.3.

Modified Paths:
--------------
    branches/blender-3.3-release/blender_docs/manual/files/linked_libraries/library_overrides.rst
    branches/blender-3.3-release/blender_docs/manual/files/linked_libraries/library_proxies.rst

Modified: branches/blender-3.3-release/blender_docs/manual/files/linked_libraries/library_overrides.rst
===================================================================

--- branches/blender-3.3-release/blender_docs/manual/files/linked_libraries/library_overrides.rst	2022-08-22 19:32:46 UTC (rev 9509)
+++ branches/blender-3.3-release/blender_docs/manual/files/linked_libraries/library_overrides.rst	2022-08-24 15:30:47 UTC (rev 9510)
@@ -3,9 +3,10 @@
 Library Overrides
 *****************
 
-Library Overrides is a system designed to replace and supersede
-Proxies. Most types of linked data-blocks can be overridden, and the properties
-of those overrides can then be edited. When the library data changes,
+Library Overrides is a system designed to allow editing
+:doc:`linked data </files/linked_libraries/link_append>`, while keeping it in sync
+with the original library data. Most types of linked data-blocks can be overridden,
+and the properties of these overrides can then be edited. When the library data changes,
 unmodified properties of the overridden one will be updated accordingly.
 
 .. note::
@@ -39,6 +40,15 @@
    of its Armature obdata, if the later goes missing, the pose bones are definitively lost.
 
 
+.. note:: Proper Collections Layout Matters
+
+   For library overrides to work well, it is much better if **all** the collections needed by
+   the character are children of the root (linked and instantiated) one, such that there is a
+   clear hierarchy.
+   Otherwise, some data may not be properly automatically overridden, and other operations
+   may be less reliable.
+
+
 Override Hierarchies
 ====================
 
@@ -45,10 +55,10 @@
 Hierarchy is a very important concept to understand when working with library overrides.
 In Blender, a real-life asset (a character, a prop, a set, etc.) is almost never made of a
 single data-block, but is rather a group of data-blocks with dependency relationships to each-other.
-E.g. a character sill typically have an armature object, several geometry objects,
-rig-controllers objects, the object data for all of those objects, materials, textures, etc.
+E.g. a character will typically have an armature object, several geometry objects,
+rig-controllers objects, the object data for all of these objects, materials, textures, etc.
 
-Those relationships can be represented as a tree, with a root data-block 'linking-in' all its
+These relationships can be represented as a tree, with a root data-block 'linking-in' all its
 dependencies, recursively. With library overrides, typically, the root of the hierarchy is also
 the data-block that is directly linked when importing the asset (usually a collection).
 
@@ -60,6 +70,29 @@
 of a same character.
 
 
+Resyncing Overrides
+===================
+
+The relationships between linked data-blocks can change, resulting in outdated overrides.
+When this happens, overrides need to be resynced to match the new structure of their hierarchy.
+Overrides are automatically resynced if needed on blend-files opening. However,
+it may be needed to resynced them manually sometimes, see `Troubleshoot an Override Hierarchy`_.
+
+.. tip::
+
+   Blender is also able to resync library overrides from external libraries, that are then linked into a
+   working file. However, this is a costly process that needs to be fully redone every time the working
+   file is loaded, since Blender cannot edit/modify the external library directly.
+
+   So users linking overrides (or creating recursive overrides) should ensure that their library files are
+   regularly updated, to avoid this overhead on file load (typically, opening and saving those library files
+   should be enough to update them).
+
+.. tip::
+
+   Auto resyncing can be disabled in the :doc:`Experimental Preferences </editors/preferences/experimental>`.
+
+
 Non-Editable Overrides
 ======================
 
@@ -66,87 +99,133 @@
 For technical reasons (how relationships between data-blocks are stored), Blender needs to create
 overrides of a lot of data-blocks, even when only one or two of them actually needs to be edited
 by the user. To reduce the amount of information and risk of potential unwanted editing, most of
-those data-blocks are now marked as non-editable by default. This can be changed once the
+these data-blocks are now marked as non-editable by default. This can be changed once the
 override has been created.
 
 
-Creating an Override
-====================
+.. _bpy.ops.outliner.liboverride_operation:
+.. _bpy.ops.object.make_override_library:
+.. _bpy.ops.ui.override_idtemplate_make:
 
+Make an Override
+================
+
 .. reference::
 
-   :Editor:    3D Viewport and Outliner
+   :Editor:    3D Viewport, Outliner, Properties
    :Mode:      Object Mode
-   :Menu:      :menuselection:`3D Viewport --> Header --> Object --> Relations --> Make Override Library`
-               :menuselection:`Outliner --> Context Menu --> ID Data --> Make Library Override Hierarchy`
-               :menuselection:`Outliner --> Context Menu --> ID Data --> Make Library Override Single`
+   :Menu:      :menuselection:`3D Viewport --> Header --> Object --> Library Override --> Make`
+               :menuselection:`Outliner --> Context Menu --> Library Override --> Make`
+               :menuselection:`ID Widget --> Context Menu --> Library Override --> Make`
+   :Shortcut:  :kbd:`Shift-LMB` on the 'linked'/'overridden' button of an ID Widget.
 
-There are two ways to create an override of a linked data-block.
+Create overrides from the selected data-blocks.
 
+Blender automatically create overrides for all required data-blocks to ensure that
+valid override hierarchies are created.
 
-.. _bpy.ops.object.make_override_library:
+Only overrides created from selected items will be user-editable. 
 
-Make Library Override Operator/Make Library Override Hierarchy
---------------------------------------------------------------
+.. warning::
 
-This is the main, recommended way to create overrides.
-This operator goes over linked objects or local empties instantiating a linked collection
-(typically, a linked character).
+   The support for the creation of library overrides from the ID Widget (mainly from within
+   the *Properties* editor) is limited. While the most common usages should be supported,
+   especially with Objects, meshes, etc., much remains to be implemented.
 
-The operator will go through the whole hierarchy
-of collections and objects, and override all those needed to allow posing/animation of a character.
 
-.. note:: Proper Collections Layout Matters
+Selected Items
+--------------
 
-   For this operator to work properly, it is crucial that **all** the collections needed by
-   the character are children of the root (linked and instantiated) one, such that there is a clear hierarchy.
-   Otherwise, some won't be automatically overridden, and manual work will be needed to fix the override.
+Depending on where from the override is created, there are several ways to
+'select' items to be overridden and user-editable.
 
+.. note::
 
-Single Data-Block Override
---------------------------
+   This also applies to the other common operations (*Reset* and *Clear*).
 
-You can override a single data-block from two places:
+   The *Troubleshoot* advanced operations only available from the Outliner
+   always apply to a whole override hierarchy.
 
-- The Outliner (it's in the context menu of IDs), in which case **all** local usages
-  of that linked ID will be remapped to the new local override.
-- The data-block menu in the UI (:kbd:`Shift-LMB` on the chain icon to the right),
-  in which case only that specific usage will be remapped to the new local override.
+3DView
+______
 
-.. note:: Single Overrides Should Be Used With Caution
+The selected objects will be considered as selected.
 
-   While it is always possible to do manual partial override of a hierarchy, this is relatively
-   time consuming and error-prone, and can easily live the override hierarchy in an inconsistent
-   state (regarding relationships between its data-blocks). This can back-fire later, when a resync
-   with the linked data becomes needed e.g.
+When a selected object is a local *Empty* instantiating a linked collection,
+the following will happen:
+* The *Empty* object will be removed.
+* Its linked collection will be overridden, and that override will be instanced
+in the same collection in the current *View Layer*.
+* If the collection contains *Armature* objects, they will be user-editable.
+Otherwise, no created override will be defined as user-editable.
 
+Outliner
+________
 
-Resyncing Overrides
-===================
+The operation can be applied on either the selected items only, their content only, or both.
 
-The relationships between linked data-blocks can change, resulting in outdated overrides.
-When this happens, overrides need to be resynced to match the new structure.
-Overrides are automatically resynced if needed on blend-files opening. However,
-they can also be resynced manually using `Resync Library Override Hierarchy`_.
-
 .. tip::
 
-   Blender is also able to resync library overrides from external libraries, that are then linked into a
-   working file. However, this is a costly process that needs to be fully redone every time the working
-   file is loaded, since Blender cannot edit/modify the external library directly.
+   Using *Selected & Content* is an easy way to get all newly created overrides immediately
+   user-editable.
 
-   So users linking overrides (or creating recursive overrides) should ensure that their library files are
-   regularly updated, to avoid this overhead on file load (typically, opening and saving those library files
-   should be enough to update them).
 
-.. tip::
+ID Widget
+_________
 
-   Auto resyncing can be disabled in the :doc:`Experimental Preferences </editors/preferences/experimental>`.
+Only the linked data-block in the ID Widget is considered as selected, and set as editable
+once overridden.
 
 
-Editing an Override
-===================
+Make Editable
+-------------
 
+That same operation can also be used to make existing overrides user-editable,
+after they have been created, or :ref:`cleared<Clear Override>`
+
+
+.. _bpy.ops.object.reset_override_library:
+.. _bpy.ops.ui.override_idtemplate_reset:
+
+Reset an Override
+=================
+
+.. reference::
+

@@ Diff output truncated at 10240 characters. @@
