Update docs.

docs/assembly.rst

@@ -124,9 +124,22 @@ Access to External Variables, Functions and Libraries
 You can access Solidity variables and other identifiers by using their name.
 
 Local variables of value type are directly usable in inline assembly.
+They can both be read and assigned to.
 
-Local variables that refer to memory or calldata evaluate to the
+Local variables that refer to memory evaluate to the address of the variable in memory not the value itself.
-address of the variable in memory, resp. calldata, not the value itself.
+Such variables can also be assigned to, but note that an assignment will only change the pointer and not the data
+and that it is your responsibility to respect Solidity's memory management.
+See :ref:`Conventions in Solidity <conventions-in-solidity>`.
+
+Similarly, local variables that refer to statically-sized calldata arrays or calldata structs
+evaluate to the address of the variable in calldata, not the value itself.
+The variable can also be assigned a new offset, but note that no validation to ensure that
+the variable will not point beyond ``calldatasize()`` is performed.
+
+For dynamic calldata arrays, you can access
+their calldata offset (in bytes) and length (number of elements) using ``x.offset`` and ``x.length``.
+Both expressions can also be assigned to, but as for the static case, no validation will be performed
+to ensure that the resulting data area is within the bounds of ``calldatasize()``.
 
 For local storage variables or state variables, a single Yul identifier
 is not sufficient, since they do not necessarily occupy a single full storage slot.
@@ -135,9 +148,10 @@ inside that slot. To retrieve the slot pointed to by the variable ``x``, you
 use ``x.slot``, and to retrieve the byte-offset you use ``x.offset``.
 Using ``x`` itself will result in an error.
 
-For dynamic calldata arrays, you can access
+You can also assign to the ``.slot`` part of a local storage variable pointer.
-their calldata offset (in bytes) and length (number of elements) using ``x.offset`` and ``x.length``.
+For these (structs, arrays or mappings), the ``.offset`` part is always zero.
-Both expressions can also be assigned to.
+It is not possible to assign to the ``.slot`` or ``.offset`` part of a state variable,
+though.
 
 Local Solidity variables are available for assignments, for example:
 
@@ -178,17 +192,6 @@ Since Solidity 0.7.0, variables and functions declared inside the
 inline assembly block may not contain ``.``, but using ``.`` is
 valid to access Solidity variables from outside the inline assembly block.
 
-Assignments are possible to assembly-local variables and to function-local
-variables. Take care that when you assign to variables that point to
-memory or storage, you will only change the pointer and not the data.
-
-You can assign to the ``.slot`` part of a local storage variable pointer.
-For these (structs, arrays or mappings), the ``.offset`` part is always zero.
-It is not possible to assign to the ``.slot`` or ``.offset`` part of a state variable,
-though.
-
-
-
 Things to Avoid
 ---------------
 
@@ -199,6 +202,8 @@ functional-style opcodes, counting stack height for
 variable access and removing stack slots for assembly-local variables when the end
 of their block is reached.
 
+.. _conventions-in-solidity:
+
 Conventions in Solidity
 -----------------------