Improve attach docs.

PiperOrigin-RevId: 834366494
Change-Id: I9086097990f09e848d0b76d9c22f4fd2bbd70718

doc/XMLreference.rst

@@ -183,10 +183,11 @@ replicating 200 times, suffixes will be ``000, 001, ...`` etc). All referencing
 and namespaced appropriately. Detailed examples of models using replicate can be found in the
 `model/replicate/ <https://github.com/google-deepmind/mujoco/tree/main/model/replicate>`__ directory.
 
-There is a caveat concerning :ref:`keyframes<keyframe>` when using replicate. Since :ref:`mjs_attach` is used to
+There are some caveats concerning :ref:`keyframes<keyframe>` when using replicate. Since :ref:`mjs_attach` is used to
 self-attach multiple times the enclosed kinematic tree, if this tree contains further :ref:`attach<body-attach>`
 elements, keyframes will not be replicated nor namespaced by :ref:`replicate<replicate>`, but they will be attached and
-namespaced once by the innermost call of :ref:`mjs_attach`. See the limitations discussed in :ref:`attach<body-attach>`.
+namespaced once by the innermost call of :ref:`mjs_attach`. See the limitations discussed in
+:ref:`attachment<meAttachment>`.
 
 .. _replicate-count:
 
@@ -3918,25 +3919,16 @@ Associate this body with an :ref:`engine plugin<exPlugin>`. Either :at:`plugin`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The :el:`attach` element is used to insert a sub-tree of bodies from another model into this model's kinematic tree.
-Unlike :ref:`include<include>`, which is implemented in the parser and is equivalent to copying and pasting XML from
+Unlike :ref:`include<include>`, which is implemented in the parser and is equivalent to copying and pasting XML from one
-one file into another, :el:`attach` is implemented in the model compiler. In order to use this element, the sub-model
+file into another, :el:`attach` is implemented in the model compiler. In order to use this element, the sub-model must
-must first be defined as an :ref:`asset<asset-model>`. When creating an attachment, the top body of the attached subtree
+first be defined as an :ref:`asset<asset-model>`. When creating an attachment, the top body of the attached subtree is
-is specified, and all referencing elements outside the kinematic tree (e.g., sensors and actuators), are
+specified, and all referencing elements outside the kinematic tree (e.g., sensors and actuators), are also copied into
-also copied into the top-level model. Additionally, any elements referenced from within the attached subtree (e.g.
+the top-level model. Additionally, any elements referenced from within the attached subtree (e.g. defaults and assets)
-defaults and assets) will be copied in to the top-level model. :el:`attach` is a :ref:`meta-element`, so upon saving
+will be copied in to the top-level model. :el:`attach` is a :ref:`meta-element`, so upon saving all attachments will
-all attachments will appear in the saved XML file.
+appear in the saved XML file. Note that this element is a subset of the functionality of the procedural
-
+:ref:`attachment<meAttachment>` functionality. As such, it shares the same limitations as described there. In addition,
-.. admonition:: Known issues
+when the :el:`attach` element is used, it is not possible to attach an entire model (i.e. including all elements,
-   :class: note
+referenced or not).
-
-   The following known limitations exist, to be addressed in a future release:
-
-   - An entire model cannot be attached (i.e. including all elements, referenced or not).
-   - All assets from the child model will be copied in, whether they are referenced or not.
-   - Circular references are not checked for and will lead to infinite loops.
-   - When attaching a model with :ref:`keyframes<keyframe>`, model compilation is required for the re-indexing to be
-     finalized. If a second attachment is performed without compilation, the keyframes from the first attachment will be
-     lost.
 
 .. _body-attach-model:
 

doc/programming/modeledit.rst

@@ -126,7 +126,7 @@ referencing elements from outside the kinematic tree (e.g., actuators and sensor
 remove all associated elements from the model. The default behavior ("shallow copy") is to move the child into the
 parent while attaching, so subsequent changes to the child will also change the parent. Alternatively, the user can
 choose to make an entirely new copy during attach using :ref:`mjs_setDeepCopy`. This flag is temporarily set to true
-while parsing XMLs. It is possible to :ref:`attach a body to a frame<mjs_attach>`:
+while parsing XMLs. It is possible to :ref:`attach a body or an mjSpec to a frame<mjs_attach>`:
 
 .. code-block:: C
 
@@ -138,7 +138,7 @@ while parsing XMLs. It is possible to :ref:`attach a body to a frame<mjs_attach>
    mjsElement* body = mjs_addBody(mjs_findBody(child, "world"), NULL)->element;
    mjsBody* attached_body_1 = mjs_asBody(mjs_attach(frame, body, "attached-", "-1"));
 
-or :ref:`attach a body to a site<mjs_attach>`:
+or :ref:`attach a body or an mjSpec to a site<mjs_attach>`:
 
 .. code-block:: C
 
@@ -148,7 +148,7 @@ or :ref:`attach a body to a site<mjs_attach>`:
    mjsElement* body = mjs_addBody(mjs_findBody(child, "world"), NULL)->element;
    mjsBody* attached_body_2 = mjs_asBody(mjs_attach(site, body, "attached-", "-2"));
 
-or :ref:`attach a frame to a body<mjs_attach>`:
+or :ref:`attach a frame or an mjSpec to a body<mjs_attach>`:
 
 .. code-block:: C
 
@@ -165,6 +165,18 @@ flags, while the parent will be compiled using the parent flags.
 
 Note also that once a child is attached by reference to a parent, the child cannot be compiled on its own.
 
+.. admonition:: Known issues
+   :class: note
+
+   The following known limitations exist:
+
+   - All assets from the child model will be copied in, whether they are referenced or not, if the parent and the child
+     are not the same mjSpec.
+   - Circular references are not checked for and will lead to infinite loops.
+   - When attaching a model with :ref:`keyframes<keyframe>`, model compilation is required for the re-indexing to be
+     finalized. If a second attachment is performed without compilation, the keyframes from the first attachment will be
+     lost.
+
 .. _meDefault:
 
 Default classes