From 0eaf9ff55598a44dedb1c1a9e40f4cadb552d388 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 13:38:42 -0400
Subject: [PATCH 01/22] Treat --command-line-options specially

---
 doc/cabaldomain.py | 56 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 9b0f1e004f2..699669640aa 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -592,6 +592,45 @@ def run(self):
 class ConfigField(CabalField):
     section_key = 'cabal:cfg-section'
     indextemplate = '%s ; cabal project option'
+
+    def get_signatures(self):
+        signatures = super(ConfigField, self).get_signatures()
+        long_options = []
+        non_option_signatures = []
+
+        for signature in signatures:
+            stripped = signature.strip()
+            if stripped.startswith('-'):
+                long_options.extend(self._extract_long_options(stripped))
+            elif stripped:
+                non_option_signatures.append(signature)
+
+        # Keep only the primary cfg-field signature and render command-line
+        # variants as links to standard command-line options.
+        if non_option_signatures:
+            self.command_line_options = self._deduplicate_long_options(long_options)
+            return [non_option_signatures[0]]
+
+        self.command_line_options = []
+        return signatures
+
+    def _extract_long_options(self, signature):
+        options = []
+        for match in re.findall(r'--[^,\s]+', signature):
+            target = match.split('[', 1)[0].split('=', 1)[0]
+            options.append((match, target))
+        return options
+
+    def _deduplicate_long_options(self, options):
+        unique = []
+        seen = set()
+        for option in options:
+            if option in seen:
+                continue
+            seen.add(option)
+            unique.append(option)
+        return unique
+
     def handle_signature(self, sig, signode):
         sig = sig.strip()
         if sig.startswith('-'):
@@ -599,6 +638,23 @@ def handle_signature(self, sig, signode):
         else:
             name = super(ConfigField, self).handle_signature(sig, signode)
 
+        options = getattr(self, 'command_line_options', [])
+        if options:
+            signode += addnodes.desc_addname(' ', ' ')
+            signode += addnodes.desc_annotation('(', '(')
+            for i, (label, target) in enumerate(options):
+                if i > 0:
+                    signode += addnodes.desc_annotation(', ', ', ')
+
+                refnode = addnodes.pending_xref('',
+                                                refdomain='std',
+                                                reftype='option',
+                                                reftarget=target)
+                refnode += nodes.literal(label, label)
+                signode += refnode
+
+            signode += addnodes.desc_annotation(')', ')')
+
         return name
 
     def get_index_entry(self, env, name):

From 18e2d1465df1dfd6f095061bd9b861d52f7127d2 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 13:46:23 -0400
Subject: [PATCH 02/22] refwarn=False

---
 doc/cabaldomain.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 699669640aa..d69522c6123 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -649,7 +649,8 @@ def handle_signature(self, sig, signode):
                 refnode = addnodes.pending_xref('',
                                                 refdomain='std',
                                                 reftype='option',
-                                                reftarget=target)
+                                                reftarget=target,
+                                                refwarn=False)
                 refnode += nodes.literal(label, label)
                 signode += refnode
 

From 10d286b3e917565d666b6b38acc819dacbf11c1f Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 13:53:52 -0400
Subject: [PATCH 03/22] Add directive :command-line-options:

---
 doc/cabal-project-description-file.rst | 4 ++--
 doc/cabaldomain.py                     | 6 ++++++
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst
index 8f7639ee1b8..51b4ce60ba9 100644
--- a/doc/cabal-project-description-file.rst
+++ b/doc/cabal-project-description-file.rst
@@ -613,7 +613,7 @@ The following settings control the behavior of the dependency solver:
     the flag multiple times.
 
 .. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated)
-               --allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
+    :command-line-options: --allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
     :synopsis: Lift dependencies upper bound constraints.
 
     :default: ``none``
@@ -706,7 +706,7 @@ The following settings control the behavior of the dependency solver:
     bare ``--allow-newer`` is equivalent to ``--allow-newer=all``.
 
 .. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated)
-               --allow-older, --allow-older=[none,all,[scope:][^]pkg]
+    :command-line-options: --allow-older, --allow-older=[none,all,[scope:][^]pkg]
     :synopsis: Lift dependency lower bound constraints.
     :since: 2.0
 
diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index d69522c6123..41b73da0979 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -592,12 +592,18 @@ def run(self):
 class ConfigField(CabalField):
     section_key = 'cabal:cfg-section'
     indextemplate = '%s ; cabal project option'
+    option_spec = dict(CabalField.option_spec,
+                       **{'command-line-options': lambda x: x})
 
     def get_signatures(self):
         signatures = super(ConfigField, self).get_signatures()
         long_options = []
         non_option_signatures = []
 
+        explicit_options = self.options.get('command-line-options')
+        if explicit_options:
+            long_options.extend(self._extract_long_options(explicit_options))
+
         for signature in signatures:
             stripped = signature.strip()
             if stripped.startswith('-'):

From caad384ac7924d3434c233c13387b1f6b9fd3fef Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 13:58:07 -0400
Subject: [PATCH 04/22] Use tip-like command-line options

---
 doc/cabaldomain.py | 54 +++++++++++++++++++++++++++++++---------------
 1 file changed, 37 insertions(+), 17 deletions(-)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 41b73da0979..acde7a8ee79 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -644,25 +644,45 @@ def handle_signature(self, sig, signode):
         else:
             name = super(ConfigField, self).handle_signature(sig, signode)
 
+        return name
+
+    def _make_command_line_options_tip(self, options):
+        tip = nodes.container(classes=['admonition', 'tip', 'cabal-command-line-options'])
+        tip += nodes.paragraph('Command-line options', 'Command-line options',
+                               classes=['admonition-title'])
+
+        body = nodes.paragraph()
+        for i, (label, target) in enumerate(options):
+            if i > 0:
+                body += nodes.Text(', ')
+
+            refnode = addnodes.pending_xref('',
+                                            refdomain='std',
+                                            reftype='option',
+                                            reftarget=target,
+                                            refwarn=False)
+            refnode += nodes.literal(label, label)
+            body += refnode
+
+        tip += body
+        return tip
+
+    def run(self):
+        result = super(ConfigField, self).run()
         options = getattr(self, 'command_line_options', [])
-        if options:
-            signode += addnodes.desc_addname(' ', ' ')
-            signode += addnodes.desc_annotation('(', '(')
-            for i, (label, target) in enumerate(options):
-                if i > 0:
-                    signode += addnodes.desc_annotation(', ', ', ')
-
-                refnode = addnodes.pending_xref('',
-                                                refdomain='std',
-                                                reftype='option',
-                                                reftarget=target,
-                                                refwarn=False)
-                refnode += nodes.literal(label, label)
-                signode += refnode
-
-            signode += addnodes.desc_annotation(')', ')')
+        if not options:
+            return result
 
-        return name
+        for item in result:
+            if not isinstance(item, addnodes.desc):
+                continue
+
+            for desc_item in item:
+                if isinstance(desc_item, addnodes.desc_content):
+                    desc_item.insert(0, self._make_command_line_options_tip(options))
+                    return result
+
+        return result
 
     def get_index_entry(self, env, name):
         if name.startswith('-'):

From cf2988c96cf9c0c58e7adb187e08e6d5f692fcca Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 14:02:26 -0400
Subject: [PATCH 05/22] Precede each command line option with $

---
 doc/cabaldomain.py | 21 +++++++++------------
 1 file changed, 9 insertions(+), 12 deletions(-)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index acde7a8ee79..32759ba277e 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -646,15 +646,12 @@ def handle_signature(self, sig, signode):
 
         return name
 
-    def _make_command_line_options_tip(self, options):
-        tip = nodes.container(classes=['admonition', 'tip', 'cabal-command-line-options'])
-        tip += nodes.paragraph('Command-line options', 'Command-line options',
-                               classes=['admonition-title'])
+    def _make_command_line_options_block(self, options):
+        block = nodes.container(classes=['cabal-command-line-options'])
 
-        body = nodes.paragraph()
-        for i, (label, target) in enumerate(options):
-            if i > 0:
-                body += nodes.Text(', ')
+        for label, target in options:
+            line = nodes.paragraph(classes=['cabal-command-line-option'])
+            line += nodes.inline('$ ', '$ ', classes=['cabal-command-line-icon'])
 
             refnode = addnodes.pending_xref('',
                                             refdomain='std',
@@ -662,10 +659,10 @@ def _make_command_line_options_tip(self, options):
                                             reftarget=target,
                                             refwarn=False)
             refnode += nodes.literal(label, label)
-            body += refnode
+            line += refnode
+            block += line
 
-        tip += body
-        return tip
+        return block
 
     def run(self):
         result = super(ConfigField, self).run()
@@ -679,7 +676,7 @@ def run(self):
 
             for desc_item in item:
                 if isinstance(desc_item, addnodes.desc_content):
-                    desc_item.insert(0, self._make_command_line_options_tip(options))
+                    desc_item.insert(0, self._make_command_line_options_block(options))
                     return result
 
         return result

From 13e4e5aa05198434aa52a7365e7653ca37b3ca28 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 14:05:22 -0400
Subject: [PATCH 06/22] Add custom style for command-line-option

---
 doc/_static/css/custom.css | 17 +++++++++++++++++
 doc/conf.py                |  3 ++-
 2 files changed, 19 insertions(+), 1 deletion(-)
 create mode 100644 doc/_static/css/custom.css

diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
new file mode 100644
index 00000000000..93caf1d0ec8
--- /dev/null
+++ b/doc/_static/css/custom.css
@@ -0,0 +1,17 @@
+.rst-content .cabal-command-line-options {
+  margin-top: 0.3rem;
+  margin-bottom: 0.5rem;
+}
+
+.rst-content .cabal-command-line-options .cabal-command-line-option {
+  margin-top: 0;
+  margin-bottom: 0.12rem;
+}
+
+.rst-content .cabal-command-line-options .cabal-command-line-option:last-child {
+  margin-bottom: 0;
+}
+
+.rst-content .cabal-command-line-options .cabal-command-line-icon {
+  opacity: 0.65;
+}
diff --git a/doc/conf.py b/doc/conf.py
index 671aa2adfde..eea05cf8784 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -69,7 +69,8 @@
 html_title = "Cabal {} User's Guide".format(release)
 html_short_title = "Cabal %s User's Guide" % release
 html_logo = 'images/Cabal-dark.png'
-html_static_path = ['images']
+html_static_path = ['images', '_static']
+html_css_files = ['css/custom.css']
 # Convert quotes and dashes to typographically correct entities
 html_use_smartypants = True
 html_show_copyright = True

From 442c05eecea75fa0b5e692e19028ea2b35933af3 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 14:07:30 -0400
Subject: [PATCH 07/22] Remove border and color

---
 doc/_static/css/custom.css | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
index 93caf1d0ec8..c830cc43f28 100644
--- a/doc/_static/css/custom.css
+++ b/doc/_static/css/custom.css
@@ -15,3 +15,12 @@
 .rst-content .cabal-command-line-options .cabal-command-line-icon {
   opacity: 0.65;
 }
+
+.rst-content .cabal-command-line-options .cabal-command-line-option code,
+.rst-content .cabal-command-line-options .cabal-command-line-option code.literal,
+.rst-content .cabal-command-line-options .cabal-command-line-option tt.literal {
+  border: 0;
+  background: transparent;
+  padding: 0;
+  color: inherit;
+}

From 9f92dca33b0dff786030b80406caedd482a2c556 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 14:19:03 -0400
Subject: [PATCH 08/22] Handle spaces with --package-db

---
 doc/cabaldomain.py | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 32759ba277e..bf756b4a03b 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -622,9 +622,32 @@ def get_signatures(self):
 
     def _extract_long_options(self, signature):
         options = []
-        for match in re.findall(r'--[^,\s]+', signature):
-            target = match.split('[', 1)[0].split('=', 1)[0]
-            options.append((match, target))
+        i = 0
+        n = len(signature)
+
+        while i < n:
+            start = signature.find('--', i)
+            if start < 0:
+                break
+
+            j = start + 2
+            bracket_depth = 0
+            while j < n:
+                ch = signature[j]
+                if ch == '[':
+                    bracket_depth += 1
+                elif ch == ']' and bracket_depth > 0:
+                    bracket_depth -= 1
+                elif bracket_depth == 0 and (ch == ',' or ch == ';' or ch.isspace()):
+                    break
+                j += 1
+
+            label = signature[start:j].rstrip(',;')
+            if len(label) > 2:
+                target = label.split('[', 1)[0].split('=', 1)[0]
+                options.append((label, target))
+
+            i = j + 1
         return options
 
     def _deduplicate_long_options(self, options):

From c12be52593f1e6ab9dcd1a72f1f359693044c9f6 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 14:20:10 -0400
Subject: [PATCH 09/22] Avoid spaces in --package-db values

---
 doc/cabal-project-description-file.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst
index 51b4ce60ba9..a714f79117c 100644
--- a/doc/cabal-project-description-file.rst
+++ b/doc/cabal-project-description-file.rst
@@ -452,7 +452,7 @@ package, and thus apply globally:
     Specifies the name of the directory of the global package store.
 
 .. cfg-field:: package-dbs: package DB stack (comma separated)
-               --package-db=[clear, global, user, PATH]
+               --package-db=[clear,global,user,PATH]
     :synopsis: PackageDB stack manipulation
     :since: 3.7
 

From 02570ab8819ceb0638c4bfa20b5472e4e3e5905b Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 14:46:01 -0400
Subject: [PATCH 10/22] Rename to cmdline-opts

---
 doc/_static/css/custom.css             | 14 +++++++-------
 doc/cabal-project-description-file.rst |  9 +++++----
 doc/cabaldomain.py                     |  6 +++---
 3 files changed, 15 insertions(+), 14 deletions(-)

diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
index c830cc43f28..063b0a677ce 100644
--- a/doc/_static/css/custom.css
+++ b/doc/_static/css/custom.css
@@ -1,24 +1,24 @@
-.rst-content .cabal-command-line-options {
+.rst-content .cabal-cmdline-opts {
   margin-top: 0.3rem;
   margin-bottom: 0.5rem;
 }
 
-.rst-content .cabal-command-line-options .cabal-command-line-option {
+.rst-content .cabal-cmdline-opts .cabal-command-line-option {
   margin-top: 0;
   margin-bottom: 0.12rem;
 }
 
-.rst-content .cabal-command-line-options .cabal-command-line-option:last-child {
+.rst-content .cabal-cmdline-opts .cabal-command-line-option:last-child {
   margin-bottom: 0;
 }
 
-.rst-content .cabal-command-line-options .cabal-command-line-icon {
+.rst-content .cabal-cmdline-opts .cabal-command-line-icon {
   opacity: 0.65;
 }
 
-.rst-content .cabal-command-line-options .cabal-command-line-option code,
-.rst-content .cabal-command-line-options .cabal-command-line-option code.literal,
-.rst-content .cabal-command-line-options .cabal-command-line-option tt.literal {
+.rst-content .cabal-cmdline-opts .cabal-command-line-option code,
+.rst-content .cabal-cmdline-opts .cabal-command-line-option code.literal,
+.rst-content .cabal-cmdline-opts .cabal-command-line-option tt.literal {
   border: 0;
   background: transparent;
   padding: 0;
diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst
index a714f79117c..8e260a0a3c9 100644
--- a/doc/cabal-project-description-file.rst
+++ b/doc/cabal-project-description-file.rst
@@ -613,7 +613,7 @@ The following settings control the behavior of the dependency solver:
     the flag multiple times.
 
 .. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated)
-    :command-line-options: --allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
+    :cmdline-opts: --allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
     :synopsis: Lift dependencies upper bound constraints.
 
     :default: ``none``
@@ -706,7 +706,7 @@ The following settings control the behavior of the dependency solver:
     bare ``--allow-newer`` is equivalent to ``--allow-newer=all``.
 
 .. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated)
-    :command-line-options: --allow-older, --allow-older=[none,all,[scope:][^]pkg]
+    :cmdline-opts: --allow-older, --allow-older=[none,all,[scope:][^]pkg]
     :synopsis: Lift dependency lower bound constraints.
     :since: 2.0
 
@@ -2014,8 +2014,9 @@ Most users generally won't need these.
     ``--cabal-lib-version=1.24.0.1``.
 
 .. cfg-field:: prefer-oldest: boolean
-               --prefer-oldest
-               --no-prefer-oldest
+    :cmdline-opts:
+        --prefer-oldest
+        --no-prefer-oldest
     :synopsis: Prefer the oldest versions of packages available.
     :since:    3.10
 
diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index bf756b4a03b..8777d12dbf8 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -593,14 +593,14 @@ class ConfigField(CabalField):
     section_key = 'cabal:cfg-section'
     indextemplate = '%s ; cabal project option'
     option_spec = dict(CabalField.option_spec,
-                       **{'command-line-options': lambda x: x})
+                       **{'cmdline-opts': lambda x: x})
 
     def get_signatures(self):
         signatures = super(ConfigField, self).get_signatures()
         long_options = []
         non_option_signatures = []
 
-        explicit_options = self.options.get('command-line-options')
+        explicit_options = self.options.get('cmdline-opts')
         if explicit_options:
             long_options.extend(self._extract_long_options(explicit_options))
 
@@ -670,7 +670,7 @@ def handle_signature(self, sig, signode):
         return name
 
     def _make_command_line_options_block(self, options):
-        block = nodes.container(classes=['cabal-command-line-options'])
+        block = nodes.container(classes=['cabal-cmdline-opts'])
 
         for label, target in options:
             line = nodes.paragraph(classes=['cabal-command-line-option'])

From 083f3ec9560e307f1f624395fde78a42eddf8a76 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 14:55:42 -0400
Subject: [PATCH 11/22] Avoid creating an implicit reference

---
 doc/cabaldomain.py | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 8777d12dbf8..e8038f789db 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -612,7 +612,7 @@ def get_signatures(self):
                 non_option_signatures.append(signature)
 
         # Keep only the primary cfg-field signature and render command-line
-        # variants as links to standard command-line options.
+        # variants as plain literals in the field body.
         if non_option_signatures:
             self.command_line_options = self._deduplicate_long_options(long_options)
             return [non_option_signatures[0]]
@@ -644,8 +644,7 @@ def _extract_long_options(self, signature):
 
             label = signature[start:j].rstrip(',;')
             if len(label) > 2:
-                target = label.split('[', 1)[0].split('=', 1)[0]
-                options.append((label, target))
+                options.append(label)
 
             i = j + 1
         return options
@@ -672,17 +671,11 @@ def handle_signature(self, sig, signode):
     def _make_command_line_options_block(self, options):
         block = nodes.container(classes=['cabal-cmdline-opts'])
 
-        for label, target in options:
+        for label in options:
             line = nodes.paragraph(classes=['cabal-command-line-option'])
             line += nodes.inline('$ ', '$ ', classes=['cabal-command-line-icon'])
 
-            refnode = addnodes.pending_xref('',
-                                            refdomain='std',
-                                            reftype='option',
-                                            reftarget=target,
-                                            refwarn=False)
-            refnode += nodes.literal(label, label)
-            line += refnode
+            line += nodes.literal(label, label)
             block += line
 
         return block

From c59dff780ab7d3d0fcce0a9daba3c5f32815a8e5 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 15:45:48 -0400
Subject: [PATCH 12/22] Revert "Avoid creating an implicit reference"

This reverts commit 083f3ec9560e307f1f624395fde78a42eddf8a76.
---
 doc/cabaldomain.py | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index e8038f789db..8777d12dbf8 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -612,7 +612,7 @@ def get_signatures(self):
                 non_option_signatures.append(signature)
 
         # Keep only the primary cfg-field signature and render command-line
-        # variants as plain literals in the field body.
+        # variants as links to standard command-line options.
         if non_option_signatures:
             self.command_line_options = self._deduplicate_long_options(long_options)
             return [non_option_signatures[0]]
@@ -644,7 +644,8 @@ def _extract_long_options(self, signature):
 
             label = signature[start:j].rstrip(',;')
             if len(label) > 2:
-                options.append(label)
+                target = label.split('[', 1)[0].split('=', 1)[0]
+                options.append((label, target))
 
             i = j + 1
         return options
@@ -671,11 +672,17 @@ def handle_signature(self, sig, signode):
     def _make_command_line_options_block(self, options):
         block = nodes.container(classes=['cabal-cmdline-opts'])
 
-        for label in options:
+        for label, target in options:
             line = nodes.paragraph(classes=['cabal-command-line-option'])
             line += nodes.inline('$ ', '$ ', classes=['cabal-command-line-icon'])
 
-            line += nodes.literal(label, label)
+            refnode = addnodes.pending_xref('',
+                                            refdomain='std',
+                                            reftype='option',
+                                            reftarget=target,
+                                            refwarn=False)
+            refnode += nodes.literal(label, label)
+            line += refnode
             block += line
 
         return block

From 4e2f3733e0184f941f3a2f569c0182cb51be8ba6 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 15:54:42 -0400
Subject: [PATCH 13/22] Undocumented command line options

---
 doc/cabal-commands.rst | 107 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index eb239a9285a..cac3990384b 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -1689,3 +1689,110 @@ cabal report
    Package repository to which the report is to be uploaded.
 
 .. include:: references.inc
+
+Undocumented command line options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. option::
+    --allow-boot-library-installs
+    --build-summary
+    --cabal-lib-version
+    --compiler
+    --configure-option
+    --constraint
+    --count-conflicts
+    --disable-coverage
+    --disable-debug-info
+    --disable-documentation
+    --disable-executable-dynamic
+    --disable-executable-profiling
+    --disable-executable-static
+    --disable-executable-stripping
+    --disable-library-bytecode
+    --disable-library-coverage
+    --disable-library-for-ghci
+    --disable-library-profiling
+    --disable-library-stripping
+    --disable-library-vanilla
+    --disable-optimization
+    --disable-profiling
+    --disable-shared
+    --disable-split-objs
+    --disable-split-sections
+    --disable-static
+    --doc-index-file
+    --enable-benchmarks
+    --enable-coverage
+    --enable-debug-info
+    --enable-documentation
+    --enable-executable-dynamic
+    --enable-executable-profiling
+    --enable-executable-static
+    --enable-executable-stripping
+    --enable-library-bytecode
+    --enable-library-coverage
+    --enable-library-for-ghci
+    --enable-library-profiling
+    --enable-library-stripping
+    --enable-library-vanilla
+    --enable-optimization
+    --enable-profiling
+    --enable-shared
+    --enable-split-objs
+    --enable-split-sections
+    --enable-static
+    --enable-tests
+    --extra-framework-dirs
+    --extra-include-dirs
+    --extra-lib-dirs
+    --extra-prog-path
+    --fine-grained-conflicts
+    --flags
+    --flags
+    --haddock-all
+    --haddock-benchmarks
+    --haddock-contents-location
+    --haddock-css
+    --haddock-executables
+    --haddock-hoogle
+    --haddock-hscolour-css
+    --haddock-html
+    --haddock-html-location
+    --haddock-hyperlink-source
+    --haddock-internal
+    --haddock-output-dir
+    --haddock-quickjump
+    --haddock-resources-dir
+    --haddock-tests
+    --haddock-use-unicode
+    --http-transport
+    --ignore-expiry
+    --jobs
+    --keep-going
+    --library-profiling-detail
+    --logs-dir
+    --max-backjumps
+    --minimize-conflict-set
+    --no-allow-boot-library-installs
+    --no-count-conflicts
+    --no-fine-grained-conflicts
+    --no-minimize-conflict-set
+    --no-prefer-oldest
+    --no-reorder-goals
+    --no-semaphore
+    --no-strong-flags
+    --open
+    --prefer-oldest
+    --prefer-oldest
+    --profiling-detail
+    --program-prefix
+    --program-suffix
+    --reject-unconstrained-dependencies
+    --relocatable
+    --remote-repo-cache
+    --reorder-goals
+    --run-tests
+    --semaphore
+    --solver
+    --strong-flags
+    --with-hc-pkg
+    --write-ghc-environment-files

From 0dfc8b6328932aadb308ba374adf1babe2f450ee Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 16:01:37 -0400
Subject: [PATCH 14/22] Reference the project file

---
 doc/cabal-commands.rst | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index cac3990384b..3127f17a0a7 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -1690,8 +1690,12 @@ cabal report
 
 .. include:: references.inc
 
-Undocumented command line options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Undocumented options
+--------------------
+
+For the most part, these options are the command line versions of :ref:`project
+configuration<cabal-project-file>` field options.
+
 .. option::
     --allow-boot-library-installs
     --build-summary

From 02507877b67be70327245de7ac3a35a1e1269415 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 16:38:17 -0400
Subject: [PATCH 15/22] Add subsections to undocumented options

---
 doc/cabal-commands.rst | 186 ++++++++++++++++++++++++-----------------
 1 file changed, 110 insertions(+), 76 deletions(-)

diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index 3127f17a0a7..52966bad449 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -1696,62 +1696,101 @@ Undocumented options
 For the most part, these options are the command line versions of :ref:`project
 configuration<cabal-project-file>` field options.
 
+Global configuration options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option::
+    --jobs
+    --keep-going
+    --semaphore, --no-semaphore
+
+Solver configuration options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option::
+    --constraint
+    --reject-unconstrained-dependencies
+
+Package configuration options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. option::
-    --allow-boot-library-installs
-    --build-summary
-    --cabal-lib-version
     --compiler
     --configure-option
-    --constraint
-    --count-conflicts
-    --disable-coverage
-    --disable-debug-info
-    --disable-documentation
-    --disable-executable-dynamic
-    --disable-executable-profiling
-    --disable-executable-static
-    --disable-executable-stripping
-    --disable-library-bytecode
-    --disable-library-coverage
-    --disable-library-for-ghci
-    --disable-library-profiling
-    --disable-library-stripping
-    --disable-library-vanilla
-    --disable-optimization
-    --disable-profiling
-    --disable-shared
-    --disable-split-objs
-    --disable-split-sections
-    --disable-static
-    --doc-index-file
     --enable-benchmarks
-    --enable-coverage
-    --enable-debug-info
-    --enable-documentation
-    --enable-executable-dynamic
-    --enable-executable-profiling
-    --enable-executable-static
-    --enable-executable-stripping
-    --enable-library-bytecode
-    --enable-library-coverage
-    --enable-library-for-ghci
-    --enable-library-profiling
-    --enable-library-stripping
-    --enable-library-vanilla
-    --enable-optimization
-    --enable-profiling
-    --enable-shared
-    --enable-split-objs
-    --enable-split-sections
-    --enable-static
     --enable-tests
-    --extra-framework-dirs
-    --extra-include-dirs
-    --extra-lib-dirs
     --extra-prog-path
-    --fine-grained-conflicts
-    --flags
     --flags
+    --run-tests
+    --with-hc-pkg
+
+Package object code options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option::
+    --enable-debug-info, --disable-debug-info
+    --enable-executable-stripping, --disable-executable-stripping
+    --enable-library-stripping, --disable-library-stripping
+    --enable-optimization, --disable-optimization
+    --enable-split-objs, --disable-split-objs
+    --enable-split-sections, --disable-split-sections
+
+Executable options
+^^^^^^^^^^^^^^^^^^
+
+.. option::
+    --program-prefix
+    --program-suffix
+
+Dynamic linking options
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option::
+    --enable-executable-dynamic, --disable-executable-dynamic
+    --enable-library-bytecode, --disable-library-bytecode
+    --enable-library-for-ghci, --disable-library-for-ghci
+    --enable-shared, --disable-shared
+    --relocatable
+
+Dynamic linking options
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option::
+    --enable-executable-static, --disable-executable-static
+    --enable-static, --disable-static
+
+Foreign function interface options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option::
+    --extra-include-dirs
+    --extra-lib-dirs
+    --extra-framework-dirs
+
+Profiling options
+^^^^^^^^^^^^^^^^^
+
+.. option::
+    --enable-executable-profiling, --disable-executable-profiling
+    --enable-library-profiling, --disable-library-profiling
+    --enable-library-vanilla, --disable-library-vanilla
+    --enable-profiling, --disable-profiling
+    --library-profiling-detail
+    --profiling-detail
+
+Coverage options
+^^^^^^^^^^^^^^^^
+
+.. option::
+    --enable-coverage, --disable-coverage
+    --enable-library-coverage, --disable-library-coverage
+
+Haddock options
+^^^^^^^^^^^^^^^
+
+.. option::
+    --doc-index-file
+    --enable-documentation, --disable-documentation
     --haddock-all
     --haddock-benchmarks
     --haddock-contents-location
@@ -1768,35 +1807,30 @@ configuration<cabal-project-file>` field options.
     --haddock-resources-dir
     --haddock-tests
     --haddock-use-unicode
+    --open
+
+Advanced configuration options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option::
+    --build-summary
     --http-transport
     --ignore-expiry
-    --jobs
-    --keep-going
-    --library-profiling-detail
     --logs-dir
-    --max-backjumps
-    --minimize-conflict-set
-    --no-allow-boot-library-installs
-    --no-count-conflicts
-    --no-fine-grained-conflicts
-    --no-minimize-conflict-set
-    --no-prefer-oldest
-    --no-reorder-goals
-    --no-semaphore
-    --no-strong-flags
-    --open
-    --prefer-oldest
-    --prefer-oldest
-    --profiling-detail
-    --program-prefix
-    --program-suffix
-    --reject-unconstrained-dependencies
-    --relocatable
     --remote-repo-cache
-    --reorder-goals
-    --run-tests
-    --semaphore
-    --solver
-    --strong-flags
-    --with-hc-pkg
     --write-ghc-environment-files
+
+Advanced solver options
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option::
+    --allow-boot-library-installs, --no-allow-boot-library-installs
+    --cabal-lib-version
+    --count-conflicts, --no-count-conflicts
+    --fine-grained-conflicts, --no-fine-grained-conflicts
+    --max-backjumps
+    --minimize-conflict-set, --no-minimize-conflict-set
+    --prefer-oldest, --no-prefer-oldest
+    --reorder-goals, --no-reorder-goals
+    --solver
+    --strong-flags, --no-strong-flags

From 344b863bea0cdeb7f00541fc404a1532368e7f6f Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 22 Jul 2026 16:54:42 -0400
Subject: [PATCH 16/22] Add back links to project fields

---
 doc/cabal-commands.rst | 372 +++++++++++++++++++++++++++++++----------
 1 file changed, 284 insertions(+), 88 deletions(-)

diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index 52966bad449..30e74891d0d 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -1697,140 +1697,336 @@ For the most part, these options are the command line versions of :ref:`project
 configuration<cabal-project-file>` field options.
 
 Global configuration options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --jobs
+
+    See :cfg-field:`jobs` for more information.
+
+.. option:: --keep-going
+
+    See :cfg-field:`keep-going` for more information.
 
-.. option::
-    --jobs
-    --keep-going
-    --semaphore, --no-semaphore
+.. option:: --semaphore, --no-semaphore
+
+    See :cfg-field:`semaphore` for more information.
 
 Solver configuration options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. option::
-    --constraint
-    --reject-unconstrained-dependencies
+.. option:: --constraint
+
+    See :cfg-field:`constraints` for more information.
+
+.. option:: --reject-unconstrained-dependencies
+
+    See :cfg-field:`reject-unconstrained-dependencies` for more information.
 
 Package configuration options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. option::
-    --compiler
-    --configure-option
-    --enable-benchmarks
-    --enable-tests
-    --extra-prog-path
-    --flags
-    --run-tests
-    --with-hc-pkg
+.. option:: --compiler
+
+    See :cfg-field:`compiler` for more information.
+
+.. option:: --configure-option
+
+    See :cfg-field:`configure-options` for more information.
+
+.. option:: --enable-benchmarks
+
+    See :cfg-field:`benchmarks` for more information.
+
+.. option:: --enable-tests
+
+    See :cfg-field:`tests` for more information.
+
+.. option:: --extra-prog-path
+
+    See :cfg-field:`extra-prog-path` for more information.
+
+.. option:: --flags
+
+    See :cfg-field:`flags` for more information.
+
+.. option:: --run-tests
+
+    See :cfg-field:`run-tests` for more information.
+
+.. option:: --with-hc-pkg
+
+    See :cfg-field:`with-hc-pkg` for more information.
 
 Package object code options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. option::
-    --enable-debug-info, --disable-debug-info
-    --enable-executable-stripping, --disable-executable-stripping
-    --enable-library-stripping, --disable-library-stripping
-    --enable-optimization, --disable-optimization
-    --enable-split-objs, --disable-split-objs
-    --enable-split-sections, --disable-split-sections
+.. option:: --enable-debug-info, --disable-debug-info
+
+    See :cfg-field:`debug-info` for more information.
+
+.. option:: --enable-executable-stripping, --disable-executable-stripping
+
+    See :cfg-field:`executable-stripping` for more information.
+
+.. option:: --enable-library-stripping, --disable-library-stripping
+
+    See :cfg-field:`library-stripping` for more information.
+
+.. option:: --enable-optimization, --disable-optimization
+
+    See :cfg-field:`optimization` for more information.
+
+.. option:: --enable-split-objs, --disable-split-objs
+
+    See :cfg-field:`split-objs` for more information.
+
+.. option:: --enable-split-sections, --disable-split-sections
+
+    See :cfg-field:`split-sections` for more information.
 
 Executable options
 ^^^^^^^^^^^^^^^^^^
 
-.. option::
-    --program-prefix
-    --program-suffix
+.. option:: --program-prefix
+
+    See :cfg-field:`program-prefix` for more information.
+
+.. option:: --program-suffix
+
+    See :cfg-field:`program-suffix` for more information.
 
 Dynamic linking options
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-.. option::
-    --enable-executable-dynamic, --disable-executable-dynamic
-    --enable-library-bytecode, --disable-library-bytecode
-    --enable-library-for-ghci, --disable-library-for-ghci
-    --enable-shared, --disable-shared
-    --relocatable
+.. option:: --enable-executable-dynamic, --disable-executable-dynamic
+
+    See :cfg-field:`executable-dynamic` for more information.
+
+.. option:: --enable-library-bytecode, --disable-library-bytecode
+
+    See :cfg-field:`library-bytecode` for more information.
+
+.. option:: --enable-library-for-ghci, --disable-library-for-ghci
+
+    See :cfg-field:`library-for-ghci` for more information.
+
+.. option:: --enable-shared, --disable-shared
+
+    See :cfg-field:`shared` for more information.
+
+.. option:: --relocatable
+
+    See :cfg-field:`relocatable` for more information.
 
 Dynamic linking options
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-.. option::
-    --enable-executable-static, --disable-executable-static
-    --enable-static, --disable-static
+.. option:: --enable-executable-static, --disable-executable-static
+
+    See :cfg-field:`executable-static` for more information.
+
+.. option:: --enable-static, --disable-static
+
+    See :cfg-field:`static` for more information.
 
 Foreign function interface options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. option::
-    --extra-include-dirs
-    --extra-lib-dirs
-    --extra-framework-dirs
+.. option:: --extra-include-dirs
+
+    See :cfg-field:`extra-include-dirs` for more information.
+
+.. option:: --extra-lib-dirs
+
+    See :cfg-field:`extra-lib-dirs` for more information.
+
+.. option:: --extra-framework-dirs
+
+    See :cfg-field:`extra-framework-dirs` for more information.
 
 Profiling options
 ^^^^^^^^^^^^^^^^^
 
-.. option::
-    --enable-executable-profiling, --disable-executable-profiling
-    --enable-library-profiling, --disable-library-profiling
-    --enable-library-vanilla, --disable-library-vanilla
-    --enable-profiling, --disable-profiling
-    --library-profiling-detail
-    --profiling-detail
+.. option:: --enable-executable-profiling, --disable-executable-profiling
+
+    See :cfg-field:`executable-profiling` for more information.
+
+.. option:: --enable-library-profiling, --disable-library-profiling
+
+    See :cfg-field:`library-profiling` for more information.
+
+.. option:: --enable-library-vanilla, --disable-library-vanilla
+
+    See :cfg-field:`library-vanilla` for more information.
+
+.. option:: --enable-profiling, --disable-profiling
+
+    See :cfg-field:`profiling` for more information.
+
+.. option:: --library-profiling-detail
+
+    See :cfg-field:`library-profiling-detail` for more information.
+
+.. option:: --profiling-detail
+
+    See :cfg-field:`profiling-detail` for more information.
 
 Coverage options
 ^^^^^^^^^^^^^^^^
 
-.. option::
-    --enable-coverage, --disable-coverage
-    --enable-library-coverage, --disable-library-coverage
+.. option:: --enable-coverage, --disable-coverage
+
+    See :cfg-field:`coverage` for more information.
+
+.. option:: --enable-library-coverage, --disable-library-coverage
+
+    See :cfg-field:`library-coverage` for more information.
 
 Haddock options
 ^^^^^^^^^^^^^^^
 
-.. option::
-    --doc-index-file
-    --enable-documentation, --disable-documentation
-    --haddock-all
-    --haddock-benchmarks
-    --haddock-contents-location
-    --haddock-css
-    --haddock-executables
-    --haddock-hoogle
-    --haddock-hscolour-css
-    --haddock-html
-    --haddock-html-location
-    --haddock-hyperlink-source
-    --haddock-internal
-    --haddock-output-dir
-    --haddock-quickjump
-    --haddock-resources-dir
-    --haddock-tests
-    --haddock-use-unicode
-    --open
+.. option:: --doc-index-file
+
+    See :cfg-field:`doc-index-file` for more information.
+
+.. option:: --enable-documentation, --disable-documentation
+
+    See :cfg-field:`documentation` for more information.
+
+.. option:: --haddock-all
+
+    See :cfg-field:`haddock-all` for more information.
+
+.. option:: --haddock-benchmarks
+
+    See :cfg-field:`haddock-benchmarks` for more information.
+
+.. option:: --haddock-contents-location
+
+    See :cfg-field:`haddock-contents-location` for more information.
+
+.. option:: --haddock-css
+
+    See :cfg-field:`haddock-css` for more information.
+
+.. option:: --haddock-executables
+
+    See :cfg-field:`haddock-executables` for more information.
+
+.. option:: --haddock-hoogle
+
+    See :cfg-field:`haddock-hoogle` for more information.
+
+.. option:: --haddock-hscolour-css
+
+    See :cfg-field:`haddock-hscolour-css` for more information.
+
+.. option:: --haddock-html
+
+    See :cfg-field:`haddock-html` for more information.
+
+.. option:: --haddock-html-location
+
+    See :cfg-field:`haddock-html-location` for more information.
+
+.. option:: --haddock-hyperlink-source
+
+    See :cfg-field:`haddock-hyperlink-source` for more information.
+
+.. option:: --haddock-internal
+
+    See :cfg-field:`haddock-internal` for more information.
+
+.. option:: --haddock-output-dir
+
+    See :cfg-field:`haddock-output-dir` for more information.
+
+.. option:: --haddock-quickjump
+
+    See :cfg-field:`haddock-quickjump` for more information.
+
+.. option:: --haddock-resources-dir
+
+    See :cfg-field:`haddock-resources-dir` for more information.
+
+.. option:: --haddock-tests
+
+    See :cfg-field:`haddock-tests` for more information.
+
+.. option:: --haddock-use-unicode
+
+    See :cfg-field:`haddock-use-unicode` for more information.
+
+.. option:: --open
+
+    See :cfg-field:`open` for more information.
 
 Advanced configuration options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. option::
-    --build-summary
-    --http-transport
-    --ignore-expiry
-    --logs-dir
-    --remote-repo-cache
-    --write-ghc-environment-files
+.. option:: --build-summary
+
+    See :cfg-field:`build-summary` for more information.
+
+.. option:: --http-transport
+
+    See :cfg-field:`http-transport` for more information.
+
+.. option:: --ignore-expiry
+
+    See :cfg-field:`ignore-expiry` for more information.
+
+.. option:: --logs-dir
+
+    See :cfg-field:`logs-dir` for more information.
+
+.. option:: --remote-repo-cache
+
+    See :cfg-field:`remote-repo-cache` for more information.
+
+.. option:: --write-ghc-environment-files
+
+    See :cfg-field:`write-ghc-environment-files` for more information.
 
 Advanced solver options
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-.. option::
-    --allow-boot-library-installs, --no-allow-boot-library-installs
-    --cabal-lib-version
-    --count-conflicts, --no-count-conflicts
-    --fine-grained-conflicts, --no-fine-grained-conflicts
-    --max-backjumps
-    --minimize-conflict-set, --no-minimize-conflict-set
-    --prefer-oldest, --no-prefer-oldest
-    --reorder-goals, --no-reorder-goals
-    --solver
-    --strong-flags, --no-strong-flags
+.. option:: --allow-boot-library-installs, --no-allow-boot-library-installs
+
+    See :cfg-field:`allow-boot-library-installs` for more information.
+
+.. option:: --cabal-lib-version
+
+    See :cfg-field:`cabal-lib-version` for more information.
+
+.. option:: --count-conflicts, --no-count-conflicts
+
+    See :cfg-field:`count-conflicts` for more information.
+
+.. option:: --fine-grained-conflicts, --no-fine-grained-conflicts
+
+    See :cfg-field:`fine-grained-conflicts` for more information.
+
+.. option:: --max-backjumps
+
+    See :cfg-field:`max-backjumps` for more information.
+
+.. option:: --minimize-conflict-set, --no-minimize-conflict-set
+
+    See :cfg-field:`minimize-conflict-set` for more information.
+
+.. option:: --prefer-oldest, --no-prefer-oldest
+
+    See :cfg-field:`prefer-oldest` for more information.
+
+.. option:: --reorder-goals, --no-reorder-goals
+
+    See :cfg-field:`reorder-goals` for more information.
+
+.. option:: --solver
+
+    See :cfg-field:`solver` for more information.
+
+.. option:: --strong-flags, --no-strong-flags
+
+    See :cfg-field:`strong-flags` for more information.

From b318cda3f2891cf78cccd222b6ec3f9eb685191f Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Thu, 23 Jul 2026 07:55:17 -0400
Subject: [PATCH 17/22] Rename CSS class to cmdline

---
 doc/_static/css/custom.css | 12 ++++++------
 doc/cabaldomain.py         |  4 ++--
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
index 063b0a677ce..3d96c70d1f8 100644
--- a/doc/_static/css/custom.css
+++ b/doc/_static/css/custom.css
@@ -3,22 +3,22 @@
   margin-bottom: 0.5rem;
 }
 
-.rst-content .cabal-cmdline-opts .cabal-command-line-option {
+.rst-content .cabal-cmdline-opts .cabal-cmdline-option {
   margin-top: 0;
   margin-bottom: 0.12rem;
 }
 
-.rst-content .cabal-cmdline-opts .cabal-command-line-option:last-child {
+.rst-content .cabal-cmdline-opts .cabal-cmdline-option:last-child {
   margin-bottom: 0;
 }
 
-.rst-content .cabal-cmdline-opts .cabal-command-line-icon {
+.rst-content .cabal-cmdline-opts .cabal-cmdline-icon {
   opacity: 0.65;
 }
 
-.rst-content .cabal-cmdline-opts .cabal-command-line-option code,
-.rst-content .cabal-cmdline-opts .cabal-command-line-option code.literal,
-.rst-content .cabal-cmdline-opts .cabal-command-line-option tt.literal {
+.rst-content .cabal-cmdline-opts .cabal-cmdline-option code,
+.rst-content .cabal-cmdline-opts .cabal-cmdline-option code.literal,
+.rst-content .cabal-cmdline-opts .cabal-cmdline-option tt.literal {
   border: 0;
   background: transparent;
   padding: 0;
diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 8777d12dbf8..0fdf2d96cd5 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -673,8 +673,8 @@ def _make_command_line_options_block(self, options):
         block = nodes.container(classes=['cabal-cmdline-opts'])
 
         for label, target in options:
-            line = nodes.paragraph(classes=['cabal-command-line-option'])
-            line += nodes.inline('$ ', '$ ', classes=['cabal-command-line-icon'])
+            line = nodes.paragraph(classes=['cabal-cmdline-option'])
+            line += nodes.inline('$ ', '$ ', classes=['cabal-cmdline-icon'])
 
             refnode = addnodes.pending_xref('',
                                             refdomain='std',

From fb9147c8dc390c5f312c8d5e241bd4ed72bd6b70 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Thu, 23 Jul 2026 08:14:48 -0400
Subject: [PATCH 18/22] Use regex parser for cmdline-opts

---
 doc/cabaldomain.py | 47 +++++++++-------------------------------------
 1 file changed, 9 insertions(+), 38 deletions(-)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 0fdf2d96cd5..e5a7b27021f 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -594,6 +594,7 @@ class ConfigField(CabalField):
     indextemplate = '%s ; cabal project option'
     option_spec = dict(CabalField.option_spec,
                        **{'cmdline-opts': lambda x: x})
+    long_option_pattern = re.compile(r'--\S+')
 
     def get_signatures(self):
         signatures = super(ConfigField, self).get_signatures()
@@ -614,51 +615,21 @@ def get_signatures(self):
         # Keep only the primary cfg-field signature and render command-line
         # variants as links to standard command-line options.
         if non_option_signatures:
-            self.command_line_options = self._deduplicate_long_options(long_options)
+            self.command_line_options = list(dict.fromkeys(long_options))
             return [non_option_signatures[0]]
 
         self.command_line_options = []
         return signatures
 
-    def _extract_long_options(self, signature):
+    def _extract_long_options(self, text):
         options = []
-        i = 0
-        n = len(signature)
-
-        while i < n:
-            start = signature.find('--', i)
-            if start < 0:
-                break
-
-            j = start + 2
-            bracket_depth = 0
-            while j < n:
-                ch = signature[j]
-                if ch == '[':
-                    bracket_depth += 1
-                elif ch == ']' and bracket_depth > 0:
-                    bracket_depth -= 1
-                elif bracket_depth == 0 and (ch == ',' or ch == ';' or ch.isspace()):
-                    break
-                j += 1
-
-            label = signature[start:j].rstrip(',;')
-            if len(label) > 2:
-                target = label.split('[', 1)[0].split('=', 1)[0]
-                options.append((label, target))
-
-            i = j + 1
-        return options
-
-    def _deduplicate_long_options(self, options):
-        unique = []
-        seen = set()
-        for option in options:
-            if option in seen:
+        for token in self.long_option_pattern.findall(text):
+            label = token.rstrip(',;')
+            if len(label) <= 2:
                 continue
-            seen.add(option)
-            unique.append(option)
-        return unique
+            target = label.split('[', 1)[0].split('=', 1)[0]
+            options.append((label, target))
+        return options
 
     def handle_signature(self, sig, signode):
         sig = sig.strip()

From 1b66e31277d4c8d6735c5edac7428f8e5031871e Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Thu, 23 Jul 2026 08:39:26 -0400
Subject: [PATCH 19/22] Use one item per line for cmdline-opts

- reject-unconstrained* was not indented at 4 spaces
---
 doc/cabal-project-description-file.rst | 337 ++++++++++++++++---------
 1 file changed, 216 insertions(+), 121 deletions(-)

diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst
index 8e260a0a3c9..9197c0ddcf6 100644
--- a/doc/cabal-project-description-file.rst
+++ b/doc/cabal-project-description-file.rst
@@ -331,7 +331,9 @@ package, and thus apply globally:
 
 
 .. cfg-field:: verbose: nat
-               -v[n], --verbose[=n]
+    :cmdline-opts:
+        -v[n]
+        --verbose[=n]
     :synopsis: Build verbosity level.
 
     :default: 1
@@ -343,7 +345,10 @@ package, and thus apply globally:
     form ``-v2`` is also supported.
 
 .. cfg-field:: jobs: nat or $ncpus
-               -j[NUM], --jobs[=NUM], --jobs=$ncpus
+    :cmdline-opts:
+        -j[NUM]
+        --jobs[=NUM]
+        --jobs=$ncpus
     :synopsis: Number of builds running in parallel.
 
     :default: 1
@@ -358,8 +363,9 @@ package, and thus apply globally:
     to ``--jobs=$ncpus``.
 
 .. cfg-field::  semaphore: boolean
-                --semaphore
-                --no-semaphore
+    :cmdline-opts:
+        --semaphore
+        --no-semaphore
     :synopsis: Use GHC's support for semaphore based parallelism.
 
     :default: False
@@ -374,7 +380,8 @@ package, and thus apply globally:
     The command line variant of this field is ``--semaphore``.
 
 .. cfg-field::  keep-going: boolean
-                --keep-going
+    :cmdline-opts:
+        --keep-going
     :synopsis: Try to continue building on failure.
 
     :default: False
@@ -452,7 +459,8 @@ package, and thus apply globally:
     Specifies the name of the directory of the global package store.
 
 .. cfg-field:: package-dbs: package DB stack (comma separated)
-               --package-db=[clear,global,user,PATH]
+    :cmdline-opts:
+        --package-db=[clear,global,user,PATH]
     :synopsis: PackageDB stack manipulation
     :since: 3.7
 
@@ -550,8 +558,12 @@ Solver configuration options
 The following settings control the behavior of the dependency solver:
 
 .. cfg-field:: constraints: CONSTRAINT (comma separated list)
-               -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT
-               --constraint="pkg >= 2.0", -c "pkg >= 2.0"
+    :cmdline-opts:
+        -c CONSTRAINT
+        -cCONSTRAINT
+        --constraint=CONSTRAINT
+        --constraint="pkg >= 2.0"
+        -c "pkg >= 2.0"
     :synopsis: Extra dependencies constraints.
 
     Add extra constraints to the version bounds, flag settings,
@@ -587,8 +599,9 @@ The following settings control the behavior of the dependency solver:
     command line option.
 
 .. cfg-field:: preferences: CONSTRAINT (comma separated list)
-               --preference=CONSTRAINT
-               --preference="pkg >= 2.0"
+    :cmdline-opts:
+        --preference=CONSTRAINT
+        --preference="pkg >= 2.0"
     :synopsis: Preferred dependency versions.
 
     Like :cfg-field:`constraints`, but the solver will attempt to satisfy
@@ -613,7 +626,9 @@ The following settings control the behavior of the dependency solver:
     the flag multiple times.
 
 .. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated)
-    :cmdline-opts: --allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
+    :cmdline-opts:
+        --allow-newer
+        --allow-newer=[none,all,[scope:][^]pkg]
     :synopsis: Lift dependencies upper bound constraints.
 
     :default: ``none``
@@ -706,7 +721,9 @@ The following settings control the behavior of the dependency solver:
     bare ``--allow-newer`` is equivalent to ``--allow-newer=all``.
 
 .. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated)
-    :cmdline-opts: --allow-older, --allow-older=[none,all,[scope:][^]pkg]
+    :cmdline-opts:
+        --allow-older
+        --allow-older=[none,all,[scope:][^]pkg]
     :synopsis: Lift dependency lower bound constraints.
     :since: 2.0
 
@@ -817,19 +834,20 @@ The following settings control the behavior of the dependency solver:
 
 
 .. cfg-field:: reject-unconstrained-dependencies: all, none
-               --reject-unconstrained-dependencies=[all|none]
-   :synopsis: Restrict the solver to packages that have constraints on them.
+    :cmdline-opts:
+        --reject-unconstrained-dependencies=[all|none]
+    :synopsis: Restrict the solver to packages that have constraints on them.
 
-   :default: none
-   :since: 2.6
+    :default: none
+    :since: 2.6
 
-   By default, the dependency solver can include any package that it's
-   aware of in a build plan. If you wish to restrict the build plan to
-   a closed set of packages (e.g., from a freeze file), use this flag.
+    By default, the dependency solver can include any package that it's
+    aware of in a build plan. If you wish to restrict the build plan to
+    a closed set of packages (e.g., from a freeze file), use this flag.
 
-   When set to `all`, all non-local packages that aren't goals must be
-   explicitly constrained. When set to `none`, the solver will
-   consider all packages.
+    When set to `all`, all non-local packages that aren't goals must be
+    explicitly constrained. When set to `none`, the solver will
+    consider all packages.
 
 .. _package-configuration-options:
 
@@ -891,8 +909,13 @@ feature was added.
 .. cfg-section:: None
 
 .. cfg-field:: flags: list of +flagname or -flagname (space separated)
-               -f FLAGS or -fFLAGS, --flags=FLAGS
-               --flags="+foo -bar", -ffoo, -f-bar
+    :cmdline-opts:
+        -f FLAGS
+        -fFLAGS
+        --flags=FLAGS
+        --flags="+foo -bar"
+        -ffoo
+        -f-bar
     :synopsis: Enable or disable package flags.
 
     Force all flags specified as ``+flagname`` to be true, and all flags
@@ -921,7 +944,10 @@ feature was added.
     package :cfg-field:`constraints`.
 
 .. cfg-field:: with-compiler: PATH
-               -w PATH or -wPATH, --with-compiler=PATH
+    :cmdline-opts:
+        -w PATH
+        -wPATH
+        --with-compiler=PATH
     :synopsis: Path to compiler executable.
 
     Specify the path to a particular compiler to be used. If not an
@@ -952,7 +978,8 @@ feature was added.
     ``-w ghc-7.8``.
 
 .. cfg-field:: with-hc-pkg: PATH
-               --with-hc-pkg=PATH
+    :cmdline-opts:
+        --with-hc-pkg=PATH
     :synopsis: Path to package tool.
 
     Specify the path to the package tool, e.g., ``ghc-pkg``. This
@@ -965,8 +992,10 @@ feature was added.
     ``--with-hc-pkg=ghc-pkg-7.8``.
 
 .. cfg-field:: optimization: nat
-               -O[n], --enable-optimization[=n]
-               --disable-optimization
+    :cmdline-opts:
+        -O[n]
+        --enable-optimization[=n]
+        --disable-optimization
     :synopsis: Build with optimization.
 
     :default: ``1``
@@ -998,7 +1027,8 @@ feature was added.
     ``--enable-optimization`` and ``--disable-optimization``.
 
 .. cfg-field:: configure-options: OPT (space separated list)
-               --configure-option=OPT
+    :cmdline-opts:
+        --configure-option=OPT
     :synopsis: Options to pass to configure script.
 
     A list of extra arguments to pass to the external ``./configure``
@@ -1010,7 +1040,8 @@ feature was added.
     which can be specified multiple times to pass multiple options.
 
 .. cfg-field:: compiler: ghc, ghcjs, jhc, lhc, or uhc
-               --compiler=compiler
+    :cmdline-opts:
+        --compiler=compiler
     :synopsis: Compiler to build with.
 
     :default: ``ghc``
@@ -1025,8 +1056,9 @@ feature was added.
     per-package basis.
 
 .. cfg-field:: tests: boolean
-               --enable-tests
-               --disable-tests
+    :cmdline-opts:
+        --enable-tests
+        --disable-tests
     :synopsis: Build tests.
 
     :default: ``False``
@@ -1040,8 +1072,9 @@ feature was added.
     ``--disable-tests``.
 
 .. cfg-field:: benchmarks: boolean
-               --enable-benchmarks
-               --disable-benchmarks
+    :cmdline-opts:
+        --enable-benchmarks
+        --disable-benchmarks
     :synopsis: Build benchmarks.
 
     :default: ``False``
@@ -1056,7 +1089,8 @@ feature was added.
 
 .. _cmdoption-extra-prog-path:
 .. cfg-field:: extra-prog-path: PATH (newline or comma separated list)
-               --extra-prog-path=PATH
+    :cmdline-opts:
+        --extra-prog-path=PATH
     :synopsis: Add directories to program search path.
     :since: 1.18
 
@@ -1074,7 +1108,8 @@ feature was added.
     program search path.
 
 .. cfg-field:: run-tests: boolean
-               --run-tests
+    :cmdline-opts:
+        --run-tests
     :synopsis: Run package test suite during installation.
 
     :default: ``False``
@@ -1097,8 +1132,9 @@ Object code options
 ^^^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: debug-info: integer
-               --enable-debug-info[=n]
-               --disable-debug-info
+    :cmdline-opts:
+        --enable-debug-info[=n]
+        --disable-debug-info
     :synopsis: Build with debug info enabled.
     :since: 1.22
 
@@ -1116,8 +1152,9 @@ Object code options
     ``--disable-debug-info``.
 
 .. cfg-field:: split-sections: boolean
-               --enable-split-sections
-               --disable-split-sections
+    :cmdline-opts:
+        --enable-split-sections
+        --disable-split-sections
     :synopsis: Use GHC's split sections feature.
     :since: 2.2
 
@@ -1135,8 +1172,9 @@ Object code options
     ``--disable-split-sections``.
 
 .. cfg-field:: split-objs: boolean
-               --enable-split-objs
-               --disable-split-objs
+    :cmdline-opts:
+        --enable-split-objs
+        --disable-split-objs
     :synopsis: Use GHC's split objects feature.
 
     :default: False
@@ -1154,8 +1192,9 @@ Object code options
     ``--disable-split-objs``.
 
 .. cfg-field:: executable-stripping: boolean
-               --enable-executable-stripping
-               --disable-executable-stripping
+    :cmdline-opts:
+        --enable-executable-stripping
+        --disable-executable-stripping
     :synopsis: Strip installed programs.
 
     :default: True
@@ -1176,8 +1215,9 @@ Object code options
     ``--disable-executable-stripping``.
 
 .. cfg-field:: library-stripping: boolean
-               --enable-library-stripping
-               --disable-library-stripping
+    :cmdline-opts:
+        --enable-library-stripping
+        --disable-library-stripping
     :synopsis: Strip installed libraries.
     :since: 1.20
 
@@ -1195,7 +1235,8 @@ Executable options
 ^^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: program-prefix: PREFIX
-               --program-prefix=PREFIX
+    :cmdline-opts:
+        --program-prefix=PREFIX
     :synopsis: Prepend prefix to program names.
 
     :strike:`Prepend *prefix* to installed program names.` (Currently
@@ -1209,7 +1250,8 @@ Executable options
     The command line variant of this flag is ``--program-prefix=foo-``.
 
 .. cfg-field:: program-suffix: SUFFIX
-               --program-suffix=SUFFIX
+    :cmdline-opts:
+        --program-suffix=SUFFIX
     :synopsis: Append refix to program names.
 
     :strike:`Append *suffix* to installed program names.` (Currently
@@ -1231,8 +1273,9 @@ Dynamic linking options
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: shared: boolean
-               --enable-shared
-               --disable-shared
+    :cmdline-opts:
+        --enable-shared
+        --disable-shared
     :synopsis: Build shared library.
 
     :default: False
@@ -1244,8 +1287,9 @@ Dynamic linking options
     ``--disable-shared``.
 
 .. cfg-field:: executable-dynamic: boolean
-               --enable-executable-dynamic
-               --disable-executable-dynamic
+    :cmdline-opts:
+        --enable-executable-dynamic
+        --disable-executable-dynamic
     :synopsis: Link executables dynamically.
 
     :default: False
@@ -1259,8 +1303,9 @@ Dynamic linking options
     ``--disable-executable-dynamic``.
 
 .. cfg-field:: library-for-ghci: boolean
-               --enable-library-for-ghci
-               --disable-library-for-ghci
+    :cmdline-opts:
+        --enable-library-for-ghci
+        --disable-library-for-ghci
     :synopsis: Build libraries suitable for use with GHCi.
 
     :default: True
@@ -1276,8 +1321,9 @@ Dynamic linking options
     ``--enable-library-for-ghci`` and ``--disable-library-for-ghci``.
 
 .. cfg-field:: library-bytecode: boolean
-               --enable-library-bytecode
-               --disable-library-bytecode
+    :cmdline-opts:
+        --enable-library-bytecode
+        --disable-library-bytecode
     :synopsis: Build bytecode libraries.
 
     :default: False
@@ -1295,7 +1341,8 @@ Dynamic linking options
     ``--enable-library-bytecode`` and ``--disable-library-bytecode``.
 
 .. cfg-field:: relocatable:
-               --relocatable
+    :cmdline-opts:
+        --relocatable
     :synopsis: Build relocatable package.
     :since: 1.22
 
@@ -1310,8 +1357,9 @@ Static linking options
 ^^^^^^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: static: boolean
-               --enable-static
-               --disable-static
+    :cmdline-opts:
+        --enable-static
+        --disable-static
     :synopsis: Build static library.
 
 
@@ -1322,8 +1370,9 @@ Static linking options
     GHC 8.4 and later for other platforms as well.
 
 .. cfg-field:: executable-static: boolean
-               --enable-executable-static
-               --disable-executable-static
+    :cmdline-opts:
+        --enable-executable-static
+        --disable-executable-static
     :synopsis: Build fully static executables.
 
 
@@ -1338,7 +1387,8 @@ Foreign function interface options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: extra-include-dirs: directories (comma or newline separated list)
-               --extra-include-dirs=DIR
+    :cmdline-opts:
+        --extra-include-dirs=DIR
     :synopsis: Adds C header search path.
 
     An extra directory to search for C header files. You can use this
@@ -1358,7 +1408,8 @@ Foreign function interface options
     ``--extra-include-dirs=DIR``, which can be specified multiple times.
 
 .. cfg-field:: extra-lib-dirs: directories (comma or newline separated list)
-               --extra-lib-dirs=DIR
+    :cmdline-opts:
+        --extra-lib-dirs=DIR
     :synopsis: Adds library search directory.
 
     An extra directory to search for system libraries files.
@@ -1367,7 +1418,8 @@ Foreign function interface options
     which can be specified multiple times.
 
 .. cfg-field:: extra-framework-dirs: directories (comma or newline separated list)
-               --extra-framework-dirs=DIR
+    :cmdline-opts:
+        --extra-framework-dirs=DIR
     :synopsis: Adds framework search directory (OS X only).
 
     An extra directory to search for frameworks (OS X only).
@@ -1392,8 +1444,9 @@ Profiling options
 ^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: profiling: boolean
-               --enable-profiling
-               --disable-profiling
+    :cmdline-opts:
+        --enable-profiling
+        --disable-profiling
     :synopsis: Enable profiling builds.
     :since: 1.22
 
@@ -1417,7 +1470,8 @@ Profiling options
 .. _profiling-detail:
 
 .. cfg-field:: profiling-detail: level
-               --profiling-detail=level
+    :cmdline-opts:
+        --profiling-detail=level
     :synopsis: Profiling detail level.
     :since: 1.24
 
@@ -1465,7 +1519,8 @@ Profiling options
     ``--profiling-detail=none``.
 
 .. cfg-field:: library-profiling-detail: level
-               --library-profiling-detail=level
+    :cmdline-opts:
+        --library-profiling-detail=level
     :synopsis: Libraries profiling detail level.
     :since: 1.24
 
@@ -1475,8 +1530,9 @@ Profiling options
     ``--library-profiling-detail=none``.
 
 .. cfg-field:: library-vanilla: boolean
-               --enable-library-vanilla
-               --disable-library-vanilla
+    :cmdline-opts:
+        --enable-library-vanilla
+        --disable-library-vanilla
     :synopsis: Build libraries without profiling.
 
     :default: True
@@ -1489,8 +1545,9 @@ Profiling options
     ``--enable-library-vanilla`` and ``--disable-library-vanilla``.
 
 .. cfg-field:: library-profiling: boolean
-               --enable-library-profiling
-               --disable-library-profiling
+    :cmdline-opts:
+        --enable-library-profiling
+        --disable-library-profiling
     :synopsis: Build libraries with profiling enabled.
     :since: 1.22
 
@@ -1503,8 +1560,9 @@ Profiling options
     ``--enable-library-profiling`` and ``--disable-library-profiling``.
 
 .. cfg-field:: executable-profiling: boolean
-               --enable-executable-profiling
-               --disable-executable-profiling
+    :cmdline-opts:
+        --enable-executable-profiling
+        --disable-executable-profiling
     :synopsis: Build executables with profiling enabled.
     :since: 1.22
 
@@ -1521,8 +1579,9 @@ Coverage options
 ^^^^^^^^^^^^^^^^
 
 .. cfg-field:: coverage: boolean
-               --enable-coverage
-               --disable-coverage
+    :cmdline-opts:
+        --enable-coverage
+        --disable-coverage
     :synopsis: Build with coverage enabled.
     :since: 1.22
 
@@ -1536,8 +1595,9 @@ Coverage options
     ``--disable-coverage``.
 
 .. cfg-field:: library-coverage: boolean
-               --enable-library-coverage
-               --disable-library-coverage
+    :cmdline-opts:
+        --enable-library-coverage
+        --disable-library-coverage
     :since: 1.22
     :deprecated:
 
@@ -1552,8 +1612,9 @@ Haddock options
 ^^^^^^^^^^^^^^^
 
 .. cfg-field:: documentation: boolean
-               --enable-documentation
-               --disable-documentation
+    :cmdline-opts:
+        --enable-documentation
+        --disable-documentation
     :synopsis: Enable building of documentation.
 
     :default: False
@@ -1573,7 +1634,8 @@ Haddock options
     These need to be enabled separately if desired.
 
 .. cfg-field:: doc-index-file: templated path
-               --doc-index-file=TEMPLATE
+    :cmdline-opts:
+        --doc-index-file=TEMPLATE
     :synopsis: Path to haddock templates.
 
     A central index of Haddock API documentation (template cannot use
@@ -1583,7 +1645,8 @@ The following commands are equivalent to ones that would be passed when
 running ``setup haddock``.
 
 .. cfg-field:: haddock-hoogle: boolean
-               --haddock-hoogle
+    :cmdline-opts:
+        --haddock-hoogle
     :synopsis: Generate Hoogle file.
 
     :default: False
@@ -1593,7 +1656,8 @@ running ``setup haddock``.
     This is equivalent to running ``haddock`` with the ``--hoogle`` flag.
 
 .. cfg-field:: haddock-html: boolean
-               --haddock-html
+    :cmdline-opts:
+        --haddock-html
     :synopsis: Build HTML documentation.
 
     :default: True
@@ -1601,7 +1665,8 @@ running ``setup haddock``.
     Build HTML documentation.
 
 .. cfg-field:: haddock-quickjump: boolean
-               --haddock-quickjump
+    :cmdline-opts:
+        --haddock-quickjump
     :synopsis: Generate Quickjump file.
 
     :default: False
@@ -1610,7 +1675,8 @@ running ``setup haddock``.
     This is equivalent to running ``haddock`` with the ``--quickjump`` flag.
 
 .. cfg-field:: haddock-html-location: URL (templated path)
-               --haddock-html-location=URL
+    :cmdline-opts:
+        --haddock-html-location=URL
     :synopsis: Location of HTML documentation for prerequisite packages.
 
     Specify a template for the location of HTML documentation for
@@ -1634,7 +1700,8 @@ running ``setup haddock``.
     using the package tool (e.g. ``ghc-pkg``).
 
 .. cfg-field:: haddock-executables: boolean
-               --haddock-executables
+    :cmdline-opts:
+        --haddock-executables
     :synopsis: Generate documentation for executables.
 
     :default: False
@@ -1642,7 +1709,8 @@ running ``setup haddock``.
     Run haddock on all executable programs.
 
 .. cfg-field:: haddock-tests: boolean
-               --haddock-tests
+    :cmdline-opts:
+        --haddock-tests
     :synopsis: Generate documentation for tests.
 
     :default: False
@@ -1650,7 +1718,8 @@ running ``setup haddock``.
     Run haddock on all test suites.
 
 .. cfg-field:: haddock-benchmarks: boolean
-               --haddock-benchmarks
+    :cmdline-opts:
+        --haddock-benchmarks
     :synopsis: Generate documentation for benchmarks.
 
     :default: False
@@ -1658,7 +1727,8 @@ running ``setup haddock``.
     Run haddock on all benchmarks.
 
 .. cfg-field:: haddock-internal: boolean
-               --haddock-internal
+    :cmdline-opts:
+        --haddock-internal
     :synopsis: Generate documentation for internal modules
 
     :default: False
@@ -1667,7 +1737,8 @@ running ``setup haddock``.
     symbols.
 
 .. cfg-field:: haddock-all: boolean
-               --haddock-all
+    :cmdline-opts:
+        --haddock-all
     :synopsis: Generate documentation for everything
 
     :default: False
@@ -1675,14 +1746,16 @@ running ``setup haddock``.
     Run haddock on all components.
 
 .. cfg-field:: haddock-css: PATH
-               --haddock-css=PATH
+    :cmdline-opts:
+        --haddock-css=PATH
     :synopsis: Location of Haddock CSS file.
 
     The CSS file that should be used to style the generated
     documentation (overriding haddock's default).
 
 .. cfg-field:: haddock-hyperlink-source: boolean
-               --haddock-hyperlink-source
+    :cmdline-opts:
+        --haddock-hyperlink-source
     :synopsis: Generate hyperlinked source code for documentation
 
     :default: False
@@ -1692,14 +1765,16 @@ running ``setup haddock``.
     This is equivalent to running ``haddock`` with the ``--hyperlinked-source`` flag.
 
 .. cfg-field:: haddock-hscolour-css: PATH
-               --haddock-hscolour-css=PATH
+    :cmdline-opts:
+        --haddock-hscolour-css=PATH
     :synopsis: Location of CSS file for HsColour
 
     The CSS file that should be used to style the generated hyperlinked
     source code (from `HsColour`_).
 
 .. cfg-field:: haddock-contents-location: URL
-               --haddock-contents-location=URL
+    :cmdline-opts:
+        --haddock-contents-location=URL
     :synopsis: URL for contents page.
 
     A baked-in URL to be used as the location for the contents page.
@@ -1712,7 +1787,8 @@ running ``setup haddock``.
     There is no command line variant of this flag.
 
 .. cfg-field:: haddock-output-dir: DIR
-               --haddock-output-dir=DIR
+    :cmdline-opts:
+        --haddock-output-dir=DIR
     :synopsis: Generate haddock documentation into this directory.
 
     Generate haddock documentation into this directory instead of the default
@@ -1722,13 +1798,15 @@ running ``setup haddock``.
     next releases.
 
 .. cfg-field:: haddock-use-unicode: boolean
-               --haddock-use-unicode
+    :cmdline-opts:
+        --haddock-use-unicode
     :synopsis: Pass --use-unicode option to haddock.
 
     Generate HTML documentation which contains unicode characters.
 
 .. cfg-field:: haddock-resources-dir: DIR
-               --haddock-resources-dir=DIR
+    :cmdline-opts:
+        --haddock-resources-dir=DIR
     :synopsis: Location of Haddock's static/auxiliary files.
 
     Location of Haddock's static/auxiliary files. For Haddock distributed with
@@ -1737,7 +1815,8 @@ running ``setup haddock``.
     should likely be explicitly set for every Haddock invocation.
 
 .. cfg-field:: open: boolean
-               --open
+    :cmdline-opts:
+        --open
     :synopsis: Open generated documentation in-browser.
 
     When generating HTML documentation, attempt to open it in a browser
@@ -1773,7 +1852,8 @@ Advanced global configuration options
 .. cfg-section:: None
 
 .. cfg-field:: write-ghc-environment-files: always, never, or ghc8.4.4+
-               --write-ghc-environment-files=always|never|ghc8.4.4+
+    :cmdline-opts:
+        --write-ghc-environment-files=always|never|ghc8.4.4+
     :synopsis: Whether a ``.ghc.environment`` should be created after a successful build.
 
     :default: ``never``
@@ -1789,8 +1869,9 @@ Advanced global configuration options
     environment files).
 
 .. cfg-field:: build-info: True, False
-               --enable-build-info
-               --disable-build-info
+    :cmdline-opts:
+        --enable-build-info
+        --disable-build-info
     :synopsis: Whether build information for each individual component should be
                written in a machine readable format.
 
@@ -1816,7 +1897,8 @@ Advanced global configuration options
 
 .. _cmdoption-http-transport:
 .. cfg-field:: http-transport: curl, wget, powershell, or plain-http
-               --http-transport=transport
+    :cmdline-opts:
+        --http-transport=transport
     :synopsis: Transport to use with http(s) requests.
 
     :default: ``curl``
@@ -1832,7 +1914,8 @@ Advanced global configuration options
     search path can only be influenced using :ref:`--extra-prog-path<cmdoption-extra-prog-path>`.
 
 .. cfg-field:: ignore-expiry: boolean
-               --ignore-expiry
+    :cmdline-opts:
+        --ignore-expiry
     :synopsis: Ignore Hackage expiration dates.
 
     :default: False
@@ -1848,7 +1931,8 @@ Advanced global configuration options
     The command line variant of this field is ``--ignore-expiry``.
 
 .. cfg-field:: remote-repo-cache: directory
-               --remote-repo-cache=DIR
+    :cmdline-opts:
+        --remote-repo-cache=DIR
     :synopsis: Location of packages cache.
 
     :default: ``~/.cabal/packages``
@@ -1860,7 +1944,8 @@ Advanced global configuration options
     ``--remote-repo-cache=DIR``.
 
 .. cfg-field:: logs-dir: directory
-               --logs-dir=DIR
+    :cmdline-opts:
+        --logs-dir=DIR
     :synopsis: Directory to store build logs.
 
     :default: ``~/.cabal/logs``
@@ -1871,7 +1956,8 @@ Advanced global configuration options
     The command line variant of this flag is ``--logs-dir=DIR``.
 
 .. cfg-field:: build-summary: template filepath
-               --build-summary=TEMPLATE
+    :cmdline-opts:
+        --build-summary=TEMPLATE
     :synopsis: Build summaries location.
 
     :default: ``~/.cabal/logs/build.log``
@@ -1893,7 +1979,8 @@ Advanced solver options
 Most users generally won't need these.
 
 .. cfg-field:: solver: SOLVER
-               --solver=SOLVER
+    :cmdline-opts:
+        --solver=SOLVER
     :synopsis: Which solver to use.
 
     This field is reserved to allow the specification of alternative
@@ -1903,7 +1990,8 @@ Most users generally won't need these.
     The command line variant of this field is ``--solver=modular``.
 
 .. cfg-field:: max-backjumps: nat
-               --max-backjumps=N
+    :cmdline-opts:
+        --max-backjumps=N
     :synopsis: Maximum number of solver backjumps.
 
     :default: 4000
@@ -1915,8 +2003,9 @@ Most users generally won't need these.
     The command line variant of this field is ``--max-backjumps=4000``.
 
 .. cfg-field:: reorder-goals: boolean
-               --reorder-goals
-               --no-reorder-goals
+    :cmdline-opts:
+        --reorder-goals
+        --no-reorder-goals
     :synopsis: Allow solver to reorder goals.
 
     :default: False
@@ -1930,8 +2019,9 @@ Most users generally won't need these.
     The command line variant of this field is ``--(no-)reorder-goals``.
 
 .. cfg-field:: count-conflicts: boolean
-               --count-conflicts
-               --no-count-conflicts
+    :cmdline-opts:
+        --count-conflicts
+        --no-count-conflicts
     :synopsis: Solver prefers versions with less conflicts.
 
     :default: True
@@ -1943,8 +2033,9 @@ Most users generally won't need these.
     ``--(no-)count-conflicts``.
 
 .. cfg-field:: fine-grained-conflicts: boolean
-               --fine-grained-conflicts
-               --no-fine-grained-conflicts
+    :cmdline-opts:
+        --fine-grained-conflicts
+        --no-fine-grained-conflicts
     :synopsis: Skip a version of a package if it does not resolve any conflicts
                encountered in the last version (solver optimization).
 
@@ -1960,8 +2051,9 @@ Most users generally won't need these.
     ``--(no-)fine-grained-conflicts``.
 
 .. cfg-field:: minimize-conflict-set: boolean
-               --minimize-conflict-set
-               --no-minimize-conflict-set
+    :cmdline-opts:
+        --minimize-conflict-set
+        --no-minimize-conflict-set
     :synopsis: Try to improve the solver error message when there is no
                solution.
 
@@ -1975,8 +2067,9 @@ Most users generally won't need these.
     ``--(no-)minimize-conflict-set``.
 
 .. cfg-field:: strong-flags: boolean
-               --strong-flags
-               --no-strong-flags
+    :cmdline-opts:
+        --strong-flags
+        --no-strong-flags
     :synopsis: Do not defer flag choices when solving.
 
     :default: False
@@ -1986,8 +2079,9 @@ Most users generally won't need these.
     The command line variant of this field is ``--(no-)strong-flags``.
 
 .. cfg-field:: allow-boot-library-installs: boolean
-               --allow-boot-library-installs
-               --no-allow-boot-library-installs
+    :cmdline-opts:
+        --allow-boot-library-installs
+        --no-allow-boot-library-installs
     :synopsis: Allow cabal to install or upgrade any package.
 
     :default: False
@@ -2001,7 +2095,8 @@ Most users generally won't need these.
     ``--(no-)allow-boot-library-installs``.
 
 .. cfg-field:: cabal-lib-version: VERSION
-               --cabal-lib-version=VERSION
+    :cmdline-opts:
+        --cabal-lib-version=VERSION
     :synopsis: Version of Cabal library used to build package.
 
     This field selects the version of the Cabal library which should be

From 21b97931aa0d6e6bd5fe55e6d71943680967cb0b Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Thu, 23 Jul 2026 08:42:14 -0400
Subject: [PATCH 20/22] Use indented list for cmdline-opts

---
 doc/cabaldomain.py | 48 ++++++++++++++++++++++++++--------------------
 1 file changed, 27 insertions(+), 21 deletions(-)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index e5a7b27021f..80d00cf42d5 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -594,41 +594,47 @@ class ConfigField(CabalField):
     indextemplate = '%s ; cabal project option'
     option_spec = dict(CabalField.option_spec,
                        **{'cmdline-opts': lambda x: x})
-    long_option_pattern = re.compile(r'--\S+')
 
     def get_signatures(self):
         signatures = super(ConfigField, self).get_signatures()
-        long_options = []
-        non_option_signatures = []
+        self.command_line_options = self._parse_cmdline_opts(self.options.get('cmdline-opts'))
 
-        explicit_options = self.options.get('cmdline-opts')
-        if explicit_options:
-            long_options.extend(self._extract_long_options(explicit_options))
-
-        for signature in signatures:
-            stripped = signature.strip()
-            if stripped.startswith('-'):
-                long_options.extend(self._extract_long_options(stripped))
-            elif stripped:
-                non_option_signatures.append(signature)
+        non_option_signatures = [
+            signature for signature in signatures
+            if signature.strip() and not signature.strip().startswith('-')
+        ]
 
         # Keep only the primary cfg-field signature and render command-line
         # variants as links to standard command-line options.
         if non_option_signatures:
-            self.command_line_options = list(dict.fromkeys(long_options))
             return [non_option_signatures[0]]
 
-        self.command_line_options = []
         return signatures
 
-    def _extract_long_options(self, text):
+    def _parse_cmdline_opts(self, text):
+        if not text:
+            return []
+
+        labels = [line.strip() for line in text.splitlines() if line.strip().startswith('-')]
+        if not labels:
+            return []
+
+        first_long_target = None
+        for label in labels:
+            if label.startswith('--'):
+                first_long_target = label.split('[', 1)[0].split('=', 1)[0]
+                break
+
         options = []
-        for token in self.long_option_pattern.findall(text):
-            label = token.rstrip(',;')
-            if len(label) <= 2:
-                continue
-            target = label.split('[', 1)[0].split('=', 1)[0]
+        last_long_target = None
+        for label in labels:
+            if label.startswith('--'):
+                target = label.split('[', 1)[0].split('=', 1)[0]
+                last_long_target = target
+            else:
+                target = last_long_target or first_long_target or label.split('[', 1)[0].split('=', 1)[0]
             options.append((label, target))
+
         return options
 
     def handle_signature(self, sig, signode):

From 32a7fdb3a7bd2426a82d74244f97131c48274ec0 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Thu, 23 Jul 2026 09:10:18 -0400
Subject: [PATCH 21/22] Remove unused cfg-flags

---
 doc/cabaldomain.py | 47 ++--------------------------------------------
 1 file changed, 2 insertions(+), 45 deletions(-)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 80d00cf42d5..340fdf739aa 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -135,29 +135,6 @@ def parse_deprecated(txt):
     except ValueError:
         return True
 
-def parse_flag(env, sig, signode):
-    import re
-    names = []
-    for i, flag in enumerate(sig.split(',')):
-        flag = flag.strip()
-        sep = '='
-        parts = flag.split('=')
-        if len(parts) == 1:
-            sep=' '
-            parts = flag.split()
-        if len(parts) == 0: continue
-
-        name = parts[0]
-        names.append(name)
-        sig = sep + ' '.join(parts[1:])
-        sig = re.sub(r'<([-a-zA-Z ]+)>', r'⟨\1⟩', sig)
-        if i > 0:
-            signode += addnodes.desc_name(', ', ', ')
-        signode += addnodes.desc_name(name, name)
-        if len(sig) > 0:
-            signode += addnodes.desc_addname(sig, sig)
-
-    return names[0]
 
 
 class Meta(object):
@@ -638,13 +615,7 @@ def _parse_cmdline_opts(self, text):
         return options
 
     def handle_signature(self, sig, signode):
-        sig = sig.strip()
-        if sig.startswith('-'):
-            name = parse_flag(self, sig, signode)
-        else:
-            name = super(ConfigField, self).handle_signature(sig, signode)
-
-        return name
+        return super(ConfigField, self).handle_signature(sig.strip(), signode)
 
     def _make_command_line_options_block(self, options):
         block = nodes.container(classes=['cabal-cmdline-opts'])
@@ -682,24 +653,10 @@ def run(self):
         return result
 
     def get_index_entry(self, env, name):
-        if name.startswith('-'):
-            section = self.env.ref_context.get(self.section_key)
-            if section is not None:
-                parts = ('cfg-flag', section, name)
-                indexname = section + ':' + name
-            else:
-                parts = ('cfg-flag', name)
-                indexname = name
-            indexentry = name + '; cabal project option'
-            targetname = '-'.join(parts)
-            return indexentry, targetname
-        else:
-            return super(ConfigField,self).get_index_entry(env, name)
+        return super(ConfigField,self).get_index_entry(env, name)
 
     def get_env_key(self, env, name):
         section = self.env.ref_context.get(self.section_key)
-        if name.startswith('-'):
-            return (section, name), 'cfg-flags'
         return (section, name), 'cfg-fields'
 
 class CabalConfigFieldXRef(CabalFieldXRef):

From 46922edc3b031ef6e9c6e7444c5da5cf27d0f300 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Thu, 23 Jul 2026 09:16:54 -0400
Subject: [PATCH 22/22] Remove cfg-flag

---
 doc/cabaldomain.py | 17 ++++-------------
 1 file changed, 4 insertions(+), 13 deletions(-)

diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 340fdf739aa..a3691429c1e 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -69,9 +69,6 @@
 
    References field added by `.. cfg-field`.
 
-.. rst::role:: cfg-flag
-
-   References flag added by `.. cfg-field`.
 
 
 All roles can be supplied with title as in standard sphinx references::
@@ -731,7 +728,6 @@ def generate(self, docnames=None):
 
         # (title, section store, fields store)
         entries = [('cabal.project fields', 'cfg-section', 'cfg-field'),
-                   ('cabal project flags', 'cfg-section', 'cfg-flag'),
                    ('package.cabal fields', 'pkg-section', 'pkg-field')]
 
         result = []
@@ -781,7 +777,7 @@ def make_data_keys(typ, target, node):
         section = node.get('cabal:pkg-section')
         return [(section, target),
                 (None, target)]
-    elif typ in ('cfg-field', 'cfg-flag'):
+    elif typ == 'cfg-field':
         section = node.get('cabal:cfg-section')
         return [(section, target), (None, target)]
     else:
@@ -847,9 +843,7 @@ def make_title(typ, key, meta):
         section, name = key
         return "cabal.project " + name + " field " + render_meta_title(meta)
 
-    elif typ == 'cfg-flag':
-        section, name = key
-        return "cabal flag " + name + " " + render_meta_title(meta)
+
 
     else:
         raise ValueError("Unknown type: " + typ)
@@ -902,7 +896,6 @@ class CabalDomain(Domain):
         'pkg-field'  : CabalPackageFieldXRef(warn_dangling=True),
         'cfg-section': XRefRole(warn_dangling=True),
         'cfg-field'  : CabalConfigFieldXRef(warn_dangling=True),
-        'cfg-flag'   : CabalConfigFieldXRef(warn_dangling=True),
     }
     initial_data = {
         'pkg-sections': {},
@@ -911,7 +904,6 @@ class CabalDomain(Domain):
         'index-num'   : {}, #per document number of objects
                             # used to order references page
         'cfg-fields'  : {},
-        'cfg-flags'   : {},
     }
     indices = [
         ConfigFieldIndex
@@ -921,11 +913,10 @@ class CabalDomain(Domain):
         'pkg-field'  : 'pkg-fields',
         'cfg-section': 'cfg-sections',
         'cfg-field'  : 'cfg-fields',
-        'cfg-flag'   : 'cfg-flags',
     }
     def clear_doc(self, docname):
         for k in ['pkg-sections', 'pkg-fields', 'cfg-sections',
-                  'cfg-fields', 'cfg-flags']:
+                  'cfg-fields']:
             to_del = []
             for name, (fn, _, _) in self.data[k].items():
                 if fn == docname:
@@ -955,7 +946,7 @@ def get_objects(self):
         Used for search functionality
         '''
         for typ in ['pkg-section', 'pkg-field',
-                    'cfg-section', 'cfg-field', 'cfg-flag']:
+                    'cfg-section', 'cfg-field']:
             key = self.types[typ]
             for name, (fn, target, meta) in self.data[key].items():
                 title = make_title(typ, name, meta)