From 99de54c71accef3c4fc3e42322fdef02b300173f Mon Sep 17 00:00:00 2001
From: Lina Wolf <48202465+linawolf@users.noreply.github.com>
Date: Thu, 4 Apr 2024 18:43:52 +0200
Subject: [PATCH] [TASK] Overhaul HMENU Language page (#1176)

* [TASK] Overhaul HMENU Language page

* Use confvals
* Correct indentation
* Overhaul example

releases: main, 12.4, 11.5

* [TASK] Adjustments from review
---
 .../ContentObjects/Hmenu/Language.rst         | 90 ++++++++-----------
 1 file changed, 39 insertions(+), 51 deletions(-)

diff --git a/Documentation/ContentObjects/Hmenu/Language.rst b/Documentation/ContentObjects/Hmenu/Language.rst
index 367533669..cc39ac906 100644
--- a/Documentation/ContentObjects/Hmenu/Language.rst
+++ b/Documentation/ContentObjects/Hmenu/Language.rst
@@ -1,14 +1,14 @@
-.. include:: /Includes.rst.txt
-.. index:: HMENU; special = categories
-.. _hmenu-special-language:
+..  include:: /Includes.rst.txt
+..  index:: HMENU; special = categories
+..  _hmenu-special-language:
 
-===================
+=============
 Language menu
-===================
+=============
 
-.. seealso::
-   The :ref:`LanguageMenuProcessor <LanguageMenuProcessor>` can be used to
-   create a language menu styled by Fluid.
+..  seealso::
+    The :ref:`LanguageMenuProcessor <LanguageMenuProcessor>` can be used to
+    create a language menu styled by Fluid.
 
 Creates a language selector menu.
 
@@ -16,75 +16,63 @@ The :typoscript:`special = language` type will create menu items based on
 the current page record but with the language record for each language
 overlaid if available.
 
-.. contents::
-   :local:
+..  contents::
+    :local:
+
+..  _hmenu-special-language-properties:
 
 Properties
 ==========
 
+..  _hmenu-special-language-value:
 
-.. ### BEGIN~OF~TABLE ###
-
-.. _hmenu-special-language-value:
-
-.. container:: table-row
-
-   Property
-         special.value
-
-   Data type
-         comma list of sys\_language uids /:ref:`stdWrap <stdwrap>` or `auto`
-
-   Description
-         The number of elements in this list determines the number of menu
-         items. Setting to `auto` will include all available languages from
-         the current site.
-
-.. _hmenu-special-language-normalwhennolanguage:
-
-
-.. container:: table-row
+special.value
+-------------
 
-   Property
-         special.normalWhenNoLanguage
+..  confval:: special.value
+    :name: hmenu-language-special-value
+    :type: comma separated list of language UIDs /:ref:`stdWrap <stdwrap>` or `auto`
 
-   Data type
-         boolean
+    The number of elements in this list determines the number of menu
+    items. Setting to `auto` will include all available languages from
+    the current site.
 
-   Description
-         If set to 1, the button for a language will be rendered as a non-
-         disabled button even if no translation is found for the language.
+..  _hmenu-special-language-normalwhennolanguage:
 
+special.normalWhenNoLanguage
+----------------------------
 
-.. ###### END~OF~TABLE ######
 
-[tsref:(cObject).HMENU.special = language]
+..  confval:: special.normalWhenNoLanguage
+    :name: hmenu-language-special-normalWhenNoLanguage
+    :type: boolean
 
+    If set, the button for a language will be rendered as a non-
+    disabled button even if no translation is found for the language.
 
-.. _hmenu-special-language-examples:
 
-Example
-========
+..  _hmenu-special-language-examples:
 
-Creates a language menu with pure Typoscript:
+Example: Create a language menu with pure TypoScript
+====================================================
 
-.. include:: /CodeSnippets/Menu/TypoScript/LanguageMenuLib.rst.txt
+..  include:: /CodeSnippets/Menu/TypoScript/LanguageMenuLib.rst.txt
 
-.. seealso::
+..  seealso::
    For a language menu styled by Fluid see
    :ref:`LanguageMenuProcessor <LanguageMenuProcessor>`.
 
 Note on item states
 ====================
 
-When "TSFE->sys\_language\_uid" matches the sys\_language uid for an
-element the state is set to "ACT", otherwise "NO". However, if a page
+When the language of the menu element matches the current language of the page
+displayed, the state is set to `ACT`, otherwise `NO`. However, if a page
 is not available due to the pages "Localization settings" (which can
 disable translations) or if no Alternative Page Language record was
-found (can be disabled with ".normalWhenNoLanguage", see below) the
-state is set to "USERDEF1" for non-active items and "USERDEF2" for
+found (can be disabled with `.normalWhenNoLanguage`, see below) the
+state is set to `USERDEF1` for non-active items and `USERDEF2` for
 active items. So in total there are four states to create designs for.
 It is recommended to disable the link on menu items rendered with
-"USERDEF1" and "USERDEF2" in this case since they are disabled exactly
+`USERDEF1` and `USERDEF2` in this case since they are disabled exactly
 because a page in that language does not exist and might even issue an
 error if tried accessed (depending on site configuration).