From fb104f67a0cd6a5ae69994274cf2b2d0496dec22 Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Fri, 24 Dec 2021 12:12:13 +0100
Subject: [PATCH] Update to latest version of spec, with extensions as in
 https://github.com/ansible-community/antsibull/pull/281#issuecomment-1000769798.

---
 lib/ansible/cli/doc.py | 47 ++++++++++++++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 6 deletions(-)

diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py
index 874608d2c84fcb..a8c3994626ca63 100755
--- a/lib/ansible/cli/doc.py
+++ b/lib/ansible/cli/doc.py
@@ -355,11 +355,18 @@ class DocCLI(CLI, RoleMixin):
     _URL = re.compile(r"\bU\(([^)]+)\)")
     _REF = re.compile(r"\bR\(([^)]+), *([^)]+)\)")
     _CONST = re.compile(r"\bC\(([^)]+)\)")
-    _SEM_OPTION_NAME = re.compile(r"\bO\(([^)]+)\)")
-    _SEM_OPTION_VALUE = re.compile(r"\bV\(([^)]+)\)")
-    _SEM_ENV_VARIABLE = re.compile(r"\bE\(([^)]+)\)")
+    _SEM_PARAMETER_STRING = r"\(((?:[^\\)]+|\\.)+)\)"
+    _SEM_OPTION_NAME = re.compile(r"\bO" + _SEM_PARAMETER_STRING)
+    _SEM_OPTION_VALUE = re.compile(r"\bV" + _SEM_PARAMETER_STRING)
+    _SEM_ENV_VARIABLE = re.compile(r"\bE" + _SEM_PARAMETER_STRING)
+    _SEM_RET_VALUE = re.compile(r"\bRV" + _SEM_PARAMETER_STRING)
     _RULER = re.compile(r"\bHORIZONTALLINE\b")
 
+    # helper for unescaping
+    _UNESCAPE = re.compile(r"\\(.)")
+    _FQCN_TYPE_PREFIX_RE = re.compile(r'^([^.]+\.[^.]+\.[^#]+)#([a-z]+):(.*)$')
+    _IGNORE_MARKER = 'ignore:'
+
     # rst specific
     _RST_NOTE = re.compile(r".. note::")
     _RST_SEEALSO = re.compile(r".. seealso::")
@@ -371,6 +378,33 @@ def __init__(self, args):
         super(DocCLI, self).__init__(args)
         self.plugin_list = set()
 
+    @staticmethod
+    def _tty_ify_sem_simle(matcher):
+        text = DocCLI._UNESCAPE.sub(r'\1', matcher.group(1))
+        return f"`{text}'"
+
+    @staticmethod
+    def _tty_ify_sem_complex(matcher):
+        text = DocCLI._UNESCAPE.sub(r'\1', matcher.group(1))
+        value = None
+        if '=' in text:
+            text, value = text.split('=', 1)
+        m = DocCLI._FQCN_TYPE_PREFIX_RE.match(text)
+        if m:
+            plugin_fqcn = m.group(1)
+            plugin_type = m.group(2)
+            text = m.group(3)
+        elif text.startswith(DocCLI._IGNORE_MARKER):
+            text = text[len(DocCLI._IGNORE_MARKER):]
+            plugin_fqcn = plugin_type = ''
+        else:
+            plugin_fqcn = plugin_type = ''
+        if value is not None:
+            text = f"{text}={value}"
+        if plugin_fqcn and plugin_type:
+            return f"`{text}' (of {plugin_type} {plugin_fqcn})"
+        return f"`{text}'"
+
     @classmethod
     def tty_ify(cls, text):
 
@@ -383,9 +417,10 @@ def tty_ify(cls, text):
         t = cls._PLUGIN.sub("[" + r"\1" + "]", t)       # P(word#type) => [word]
         t = cls._REF.sub(r"\1", t)            # R(word, sphinx-ref) => word
         t = cls._CONST.sub(r"`\1'", t)        # C(word) => `word'
-        t = cls._SEM_OPTION_NAME.sub(r"`\1'", t)        # O(word) => `word'
-        t = cls._SEM_OPTION_VALUE.sub(r"`\1'", t)       # V(word) => `word'
-        t = cls._SEM_ENV_VARIABLE.sub(r"`\1'", t)       # E(word) => `word'
+        t = cls._SEM_OPTION_NAME.sub(cls._tty_ify_sem_complex, t)  # O(expr)
+        t = cls._SEM_OPTION_VALUE.sub(cls._tty_ify_sem_simle, t)  # V(expr)
+        t = cls._SEM_ENV_VARIABLE.sub(cls._tty_ify_sem_simle, t)  # E(expr)
+        t = cls._SEM_RET_VALUE.sub(cls._tty_ify_sem_complex, t)  # RV(expr)
         t = cls._RULER.sub("\n{0}\n".format("-" * 13), t)   # HORIZONTALLINE => -------
 
         # remove rst