documentation #4903 Fix documentation inaccuracies found during the 3.29 review (fabpot)

This PR was squashed before being merged into the 3.x branch.

Discussion
----------

Fix documentation inaccuracies found during the 3.29 review

Aligns the docs with actual behavior: `include_only` globals, `html_attr` `data-*` iterables, destructuring slot consumption and iterator reuse, a caution for the Tempest converter, `MacroNode::compile()` overrides, and a duplicated CHANGELOG entry.

Commits
-------

59f7d67848 Document that reusing a non-rewindable iterator after destructuring is unsupported
099fa3471a Document that sequence destructuring consumes one value per pattern slot
abbdf82823 Fix the html_attr documentation about iterables in data attributes
be220e6fd8 Warn about untrusted input with the default Tempest markdown converter
1205b8b6ca Document that overriding MacroNode::compile() is not supported anymore
7bd052dd91 Merge overlapping CHANGELOG entries for the destructuring fatal error fix
207f873739 Document that include_only keeps global variables available

CHANGELOG

@@ -3,8 +3,7 @@
  * Add the `HtmlExtension::htmlAttrValue()` method to resolve a single HTML attribute value the way the `html_attr` function renders it
  * Fix `html_attr` JSON encoding a `Stringable` value in a `data-*` attribute instead of using its string representation
  * Add documentation comments to attach metadata to nodes (experimental)
- * Fix destructuring patterns with no variables, including sequences containing only empty slots, triggering a PHP fatal error instead of a `SyntaxError`
- * Fix an empty destructuring pattern triggering a PHP fatal error instead of a `SyntaxError`
+ * Fix destructuring patterns containing no variables (empty patterns or sequences with only empty slots) triggering a PHP fatal error instead of a `SyntaxError`
  * Fix object and mapping destructuring evaluating the right-hand expression more than once
  * Fix sequence destructuring of iterators throwing a `TypeError`
  * Add `TempestMarkdown` to use `tempest/markdown` as the `markdown_to_html` converter

doc/deprecated.rst

@@ -12,7 +12,10 @@ Classes
   final in Twig 4.0. Use ``Twig\Markup`` directly instead of extending it.
 
 * The ``Twig\Node\MacroNode`` class is considered final as of Twig 3.29 and
-  will be final in Twig 4.0.
+  will be final in Twig 4.0. Note that macros are compiled as closures stored
+  in a per-template registry as of Twig 3.29, so overriding
+  ``MacroNode::compile()`` based on the previous contract (emitting a
+  ``macro_``-prefixed method) is not supported anymore.
 
 Functions
 ---------

doc/filters/markdown_to_html.rst

@@ -105,6 +105,13 @@ to another implementation (for instance ``ParsedownExtra``, which extends
     (``# Title``) instead, and any YAML front matter is parsed out of the
     rendered HTML rather than being rendered.
 
+.. caution::
+
+    The output of the filter is marked as safe for HTML. The default
+    ``tempest/markdown`` converter passes raw HTML, raw ``@@ ... @@`` blocks,
+    and unsafe links through, so only use it on trusted input, or pass a
+    converter configured to sanitize its output to ``TempestMarkdown``.
+
 When using ``twig/extra-bundle``, register your converter as the
 ``twig.markdown.default`` service to make it the one used by the filter:
 

doc/functions/html_attr.rst

@@ -124,10 +124,10 @@ Data Attributes
 ---------------
 
 For ``data-*`` attributes, a boolean ``true`` is converted to the string
-``"true"``, and any non-scalar value is JSON-encoded. Two exceptions behave as
-they do for any other attribute: an iterable is rendered as a token list, and
-a ``Stringable`` object is cast to its string representation. When an object
-is both, the iterable behavior wins.
+``"true"``, and any non-scalar value is JSON-encoded, including arrays and
+other iterables. The only exception is a ``Stringable`` object, which behaves
+as it does for any other attribute: it is cast to its string representation,
+or rendered as a token list when it is also iterable.
 
 .. code-block:: html+twig
 

doc/functions/include_only.rst

@@ -17,6 +17,9 @@ Variables from the active context are not passed implicitly. This makes the
 data a template relies on explicit, which is often clearer and easier to
 reason about.
 
+Note that global variables (like the ones registered via ``addGlobal()``) are
+not part of the context: they remain available in the included template.
+
 Returned Value
 --------------
 
@@ -40,7 +43,7 @@ explicitly:
 
 .. code-block:: twig
 
-    {# template.html.twig will only have access to the "name" variable #}
+    {# template.html.twig only gets the "name" variable from the caller #}
     {{ include_only('template.html.twig', {name: 'Fabien'}) }}
 
 When passing a variable from the current context, you can use the following

doc/templates.rst

@@ -1216,8 +1216,14 @@ You can skip values by leaving a slot empty:
 
 Sequence destructuring also works with iterators (any ``Traversable``
 value). Values are extracted in iteration order and keys are ignored. The
-iterator is consumed lazily: only as many values as there are variables are
-fetched, and the expression returns the iterator itself.
+iterator is consumed lazily: only as many values as there are slots in the
+pattern are fetched (an empty slot consumes a value too), and the expression
+returns the iterator itself.
+
+Do not reuse a non-rewindable iterator (like a generator) after destructuring
+it: Twig does not define the iteration state it is left in. A rewindable
+iterator can be traversed again afterwards and restarts from the beginning,
+according to its own behavior.
 
 Object Destructuring
 ~~~~~~~~~~~~~~~~~~~~