From bd1e7333ce1f9f2bb05f424ee3cdb8ae91e2fac5 Mon Sep 17 00:00:00 2001
From: "lina.wolf" <lwolf@w-commerce.de>
Date: Mon, 23 Mar 2026 08:10:20 +0100
Subject: [PATCH] [TASK] Improve the format.html docs

Releases: main, 13.4
---
 Documentation/Global/Format/Html.rst | 165 +++++++++++++++++++++------
 1 file changed, 127 insertions(+), 38 deletions(-)

diff --git a/Documentation/Global/Format/Html.rst b/Documentation/Global/Format/Html.rst
index d20697c..48f208d 100644
--- a/Documentation/Global/Format/Html.rst
+++ b/Documentation/Global/Format/Html.rst
@@ -9,83 +9,172 @@ Format.html ViewHelper `<f:format.html>`
 
 ..  typo3:viewhelper:: format.html
     :source: ../../Global.json
+    :display: tags,description,gitHubLink
+    :noindex:
+
+..  contents:: Table of contents
 
 ..  _typo3-fluid-format-html-example:
 
-Examples
-========
+Using the `<f:format.html>` ViewHelper with default arguments
+=============================================================
+
+..  code-block:: html
+
+    <f:format.html>
+        {$myConstant.project} is a cool <b>CMS</b>
+        (<a href="https://www.typo3.org">TYPO3</a>).
+    </f:format.html>
+
+..  code-block:: html
+
+    <p class="bodytext">TYPO3 is a cool <strong>CMS</strong>
+    (<a href="https://www.typo3.org" target="_blank">TYPO3</a>).</p>
+
+The exact output depends on TYPO3 constants.
+
+..  _typo3-fluid-format-html-arguments:
+
+Arguments of the `<f:format.html>` ViewHelper
+=============================================
+
+..  typo3:viewhelper:: format.html
+    :source: ../../Global.json
+    :display: arguments-only
+
+..  _typo3-fluid-format-html-parseFunc:
+
+parseFuncTSPath argument: formatting text with a custom parsing function
+------------------------------------------------------------------------
 
-Default parameters
-------------------
+The `parseFuncTSPath` argument specifies which TypoScript `parseFunc`
+configuration is used to process the content.
 
-::
+..  code-block:: html
 
-   <f:format.html>{$myConstant.project} is a cool <b>CMS</b> (<a href="https://www.typo3.org">TYPO3</a>).</f:format.html>
+    <f:format.html parseFuncTSPath="lib.parseFunc">
+        {someText}
+    </f:format.html>
 
-Output::
+or inline:
 
-   <p class="bodytext">TYPO3 is a cool <strong>CMS</strong> (<a href="https://www.typo3.org" target="_blank">TYPO3</a>).</p>
+..  code-block:: html
 
-Depending on TYPO3 constants.
+    {someText -> f:format.html(parseFuncTSPath: 'lib.myParseFunc')}
 
-Custom parseFunc
-----------------
+With a custom parsing function defined in TypoScript:
 
-::
+..  code-block:: typoscript
+    :caption: config/site/mysite/setup.typoscript
 
-   <f:format.html parseFuncTSPath="lib.parseFunc">TYPO3 is a cool <b>CMS</b> (<a href="https://www.typo3.org">TYPO3</a>).</f:format.html>
+    lib.myParseFunc < lib.parseFunc
+    lib.myParseFunc {
+        // replace --- with soft-hyphen
+        short.--- = &shy;
+    }
 
-Output::
+..  seealso::
 
-   TYPO3 is a cool <strong>CMS</strong> (<a href="https://www.typo3.org" target="_blank">TYPO3</a>).
+    For all options see the
+    `TypoScript reference, chapter parseFunc <https://docs.typo3.org/permalink/t3tsref:parsefunc>`_.
+
+..  _typo3-fluid-format-html-arguments-data:
 
 Data argument
 --------------
 
-If you work with TypoScript :typoscript:`field` property, you should add the current record as `data`
-to the ViewHelper to allow processing the `field` and `dataWrap` properties correctly.
+If you use TypoScript properties such as :typoscript:`field` or :typoscript:`dataWrap`,
+you should pass the current record as `data`. This ensures that field references like
+`{FIELD:title}` are resolved correctly.
+
+..  code-block:: html
+
+    <f:format.html
+        data="{newsRecord}"
+        parseFuncTSPath="lib.myParseFunc"
+    >
+        News title:
+    </f:format.html>
+
+You may get the following output:
+
+..  code-block:: html
+
+    News title: <strong>TYPO3, greatest CMS ever</strong>
 
-::
+With a custom parsing function defined in TypoScript:
 
-   <f:format.html data="{newsRecord}" parseFuncTSPath="lib.news">News title: </f:format.html>
+..  code-block:: typoscript
+    :caption: config/site/mysite/setup.typoscript
 
-After "dataWrap = |<strong>{FIELD:title}</strong>" you may have this Output::
+    lib.myParseFunc < lib.parseFunc
+    lib.myParseFunc {
+        dataWrap = |<strong>{FIELD:title}</strong>
+    }
 
-   News title: <strong>TYPO3, greatest CMS ever</strong>
+..  _typo3-fluid-format-html-arguments-data-current:
 
 Current argument
 -----------------
 
-Use the `current` argument to set the current value of the content object.
+Use the `current` argument to override the current value used by the TypoScript
+content object.
 
-::
+..  code-block:: html
 
-   <f:format.html current="{strContent}" parseFuncTSPath="lib.info">I'm gone</f:format.html>
+    <f:format.html
+        current="{strContent}"
+        parseFuncTSPath="lib.myParseFunc"
+    >
+        I'm gone
+    </f:format.html>
 
-After `setContentToCurrent = 1` you may have this output::
+You may get the following output:
 
-   Thanks Kasper for this great CMS
+..  code-block:: html
+
+    Thanks Kasper for this great CMS
+
+With the following custom parsing function defined in TypoScript:
+
+..  code-block:: typoscript
+    :caption: config/site/mysite/setup.typoscript
+
+    lib.myParseFunc < lib.parseFunc
+    lib.myParseFunc {
+        setContentToCurrent = 1
+    }
+
+..  _typo3-fluid-format-html-arguments-data-CurrentValueKey:
 
 CurrentValueKey argument
 -------------------------
 
-Use the `currentValueKey` argument to define a value of data object as the current value.
-
-::
+Use the `currentValueKey` argument to define a value of data object as the
+current value.
 
-   <f:format.html data="{contentRecord}" currentValueKey="header" parseFuncTSPath="lib.content">Content: </f:format.html>
+..  code-block:: html
 
-After `dataWrap = |{CURRENT:1}` you may have this Output::
+    <f:format.html
+        data="{contentRecord}"
+        currentValueKey="header"
+        parseFuncTSPath="lib.content"
+    >
+        Content:
+    </f:format.html>
 
-   Content: How to install TYPO3 in under 2 minutes ;-)
+You may get the following output:
 
-Inline notation
----------------
+..  code-block:: html
 
-::
+    Content: How to install TYPO3 in under 2 minutes ;-)
 
-   {someText -> f:format.html(parseFuncTSPath: 'lib.parseFunc')}
+With the following custom parsing function defined in TypoScript:
 
-Output::
+..  code-block:: typoscript
+    :caption: config/site/mysite/setup.typoscript
 
-   TYPO3 is a cool <strong>CMS</strong> (<a href="https://www.typo3.org" target="_blank">TYPO3</a>).
+    lib.myParseFunc < lib.parseFunc
+    lib.myParseFunc {
+        dataWrap = |{CURRENT:1}
+    }