Add a note and warning for language extensions

haskell · Jan 6, 2024 · 57cb850 · 57cb850
1 parent 585def8
commit 57cb850
Show file tree

Hide file tree

Showing 5 changed files with 120 additions and 100 deletions.
diff --git a/Cabal-syntax-docs/cabal-package/template.zinza b/Cabal-syntax-docs/cabal-package/template.zinza
@@ -3,17 +3,14 @@
 Cabal Package Syntax
 ====================
 
-Lanugage Extensions
+Language Extensions
 -------------------
 
 For control of the default language and language extensions for the whole
 package, see :ref:`ghc-syntax`.
 
-- :ref:`ghc-enable-extension`
-- :ref:`ghc-disable-extension`
-{% for field in ghcBuildInfoFields %}
-- :ref:`{{field.name}}<ghc-{{field.name}}>`
-{% endfor %}
+- :ref:`ghc-default-language`
+- :ref:`ghc-default-extensions`
 
 Notation
 --------
@@ -151,7 +148,7 @@ In the syntax definitions below the following non-terminal symbols are used:
 
 {% endfor %}
 
-Build info fields
+Build Info Fields
 -----------------
 
 {% for field in cabalBuildInfoFields %}
@@ -184,7 +181,7 @@ Build info fields
 
 {% endfor %}
 
-Package description fields
+Package Description Fields
 --------------------------
 
 {% for field in packageDescriptionFields %}
@@ -217,7 +214,7 @@ Package description fields
 
 {% endfor %}
 
-Test-suite fields
+Test-suite Fields
 -----------------
 
 {% for field in testSuiteFields %}

diff --git a/Cabal-syntax-docs/ghc/Main.hs b/Cabal-syntax-docs/ghc/Main.hs
@@ -71,7 +71,7 @@ main = do
                     , zproduction "bugs-extension" (reXs xGroupBugs)
                         "Language Extensions related to GHC bugs and infelicities."
                     , zproduction "ungrouped-extension" (reXs xUngrouped)
-                        "Language Extensions not belonging to other extension groups, includes undocumented extensions."
+                        "Language Extensions not belonging to other extension groups."
                     ]
                 , zSpaceList                = show $ regexDoc $
                     REMunch RESpaces1 (RENamed "element" RETodo)

diff --git a/Cabal-syntax-docs/ghc/template.zinza b/Cabal-syntax-docs/ghc/template.zinza
@@ -3,23 +3,7 @@
 Language Extensions
 ===================
 
-Language extensions groups shown here correspond to subsections of the GHC
-users' guide on language extensions.  Those of the :ref:`ungrouped-extension
-<ghc-ungrouped-extension>` group are undocumented in the GHC users' guide.
-
-{% for production in productions %}
-.. _ghc-{{ production.name }}:
-
-{{ production.name }}
-    {{ production.description }}
-
-    .. math::
-
-        {{ production.syntax }}
-
-{% endfor %}
-
-Package language fields
+Package Language Fields
 -----------------------
 
 These are cabal package build info fields that control language.
@@ -56,3 +40,33 @@ These are cabal package build info fields that control language.
 
 {% endfor %}
 
+Langage Extension Groups
+------------------------
+
+Language extensions groups shown here correspond to subsections of the GHC
+users' guide on language extensions.
+
+.. Note::
+
+    The Cabal package grammar accepts any tokens for extension fields. The
+    extensions specified may be anything, something which a particular Cabal
+    version doesn't know about and this list of "known" extensions is not part
+    of the ``.cabal`` file specification and shown here only as a convenience.
+    The GHC users' guide is the place to look these up.
+
+{% for production in productions %}
+.. _ghc-{{ production.name }}:
+
+{{ production.name }}
+    {{ production.description }}
+
+    .. math::
+
+        {{ production.syntax }}
+
+{% endfor %}
+
+.. Warning::
+
+    Extensions of the :ref:`ungrouped-extension <ghc-ungrouped-extension>` group
+    are undocumented in the GHC users' guide.
diff --git a/doc/cabal-package-syntax.rst b/doc/cabal-package-syntax.rst
@@ -3,19 +3,14 @@
 Cabal Package Syntax
 ====================
 
-Lanugage Extensions
+Language Extensions
 -------------------
 
 For control of the default language and language extensions for the whole
 package, see :ref:`ghc-syntax`.
 
-- :ref:`ghc-enable-extension`
-- :ref:`ghc-disable-extension`
-- :ref:`default-extensions<ghc-default-extensions>`
-- :ref:`default-language<ghc-default-language>`
-- :ref:`extensions<ghc-extensions>`
-- :ref:`other-extensions<ghc-other-extensions>`
-- :ref:`other-languages<ghc-other-languages>`
+- :ref:`ghc-default-language`
+- :ref:`ghc-default-extensions`
 
 Notation
 --------
@@ -179,7 +174,7 @@ version-range
         \mathbf{fix}\;\mathop{\mathit{version\text{-}range}}\;\mathbf{in}\;\left\{ \begin{gathered}\mathop{\mathord{``}\mathtt{\text{=}\text{=}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{>}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{<}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{<}\text{=}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{>}\text{=}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{^}\text{>}\text{=}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{=}\text{=}}\mathord{"}}\circ{\left\{ \mathop{\mathord{``}\mathtt{0}\mathord{"}}\mid[\mathop{\mathord{``}\mathtt{1}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]{[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]}^{\in [0\ldots8]}_{} \right\}}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}\mathop{\mathord{``}\mathtt{\text{.}\text{*}}\mathord{"}}\\\mathop{\mathit{version\text{-}range}}\circ\mathop{\mathord{``}\mathtt{\text{|}\text{|}}\mathord{"}}\circ\mathop{\mathit{version\text{-}range}}\\\mathop{\mathit{version\text{-}range}}\circ\mathop{\mathord{``}\mathtt{\text{&}\text{&}}\mathord{"}}\circ\mathop{\mathit{version\text{-}range}}\\\mathop{\mathord{``}\mathtt{\text{(}}\mathord{"}}\circ\mathop{\mathit{version\text{-}range}}\circ\mathop{\mathord{``}\mathtt{\text{)}}\mathord{"}}\\\mathop{\mathord{``}\mathtt{\text{=}\text{=}}\mathord{"}}\circ\mathop{\mathord{``}\mathtt{\{}\mathord{"}}\circ{\mathop{\mathit{version}}}^+_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\}}\mathord{"}}\\\mathop{\mathord{``}\mathtt{\text{^}\text{>}\text{=}}\mathord{"}}\circ\mathop{\mathord{``}\mathtt{\{}\mathord{"}}\circ{\mathop{\mathit{version}}}^+_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\}}\mathord{"}}\end{gathered} \right\}
 
 
-Build info fields
+Build Info Fields
 -----------------
 
 asm-options
@@ -544,7 +539,7 @@ virtual-modules
         \mathrm{commalist}\left({\left(\mathop{\mathit{upper}}{\left\{ \mathop{\mathit{alpha\text{-}num}}\mid[\mathop{\mathord{``}\mathtt{\text{'}}\mathord{"}}\mathop{\mathord{``}\mathtt{\text{_}}\mathord{"}}] \right\}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}\right)
 
 
-Package description fields
+Package Description Fields
 --------------------------
 
 author
@@ -687,7 +682,7 @@ version
         {\left\{ \mathop{\mathord{``}\mathtt{0}\mathord{"}}\mid[\mathop{\mathord{``}\mathtt{1}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]{[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]}^{\in [0\ldots8]}_{} \right\}}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}
 
 
-Test-suite fields
+Test-suite Fields
 -----------------
 
 code-generators

diff --git a/doc/ghc-syntax.rst b/doc/ghc-syntax.rst
@@ -3,9 +3,79 @@
 Language Extensions
 ===================
 
+Package Language Fields
+-----------------------
+
+These are cabal package build info fields that control language.
+
+.. _ghc-default-extensions:
+
+default-extensions
+    * Monoidal field
+    * Available since ``cabal-version: 1.10``.
+    * Documentation of :pkg-field:`library:default-extensions`
+
+    .. math::
+
+        \mathrm{optcommalist}\left\{ \mathop{\mathit{enable\text{-}extension}}\mid\mathop{\mathit{disable\text{-}extension}} \right\}
+
+.. _ghc-default-language:
+
+default-language
+    * Optional field
+    * Available since ``cabal-version: 1.10``.
+    * Documentation of :pkg-field:`library:default-language`
+
+    .. math::
+
+        \left\{ \mathop{\mathord{``}\mathtt{GHC2021}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{Haskell2010}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{Haskell98}\mathord{"}} \right\}
+
+.. _ghc-extensions:
+
+extensions
+    * Monoidal field
+    * Deprecated since ``cabal-version: 1.12``: Please use 'default-extensions' or 'other-extensions' fields.
+    * Removed in ``cabal-version: 3.0``: Please use 'default-extensions' or 'other-extensions' fields.
+
+    .. math::
+
+        \mathrm{optcommalist}\left\{ \mathop{\mathit{enable\text{-}extension}}\mid\mathop{\mathit{disable\text{-}extension}} \right\}
+
+.. _ghc-other-extensions:
+
+other-extensions
+    * Monoidal field
+    * Documentation of :pkg-field:`library:other-extensions`
+
+    .. math::
+
+        \mathrm{optcommalist}\left\{ \mathop{\mathit{enable\text{-}extension}}\mid\mathop{\mathit{disable\text{-}extension}} \right\}
+
+.. _ghc-other-languages:
+
+other-languages
+    * Monoidal field
+    * Available since ``cabal-version: 1.10``.
+    * Documentation of :pkg-field:`library:other-languages`
+
+    .. math::
+
+        \mathrm{optcommalist}\left\{ \mathop{\mathord{``}\mathtt{GHC2021}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{Haskell2010}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{Haskell98}\mathord{"}} \right\}
+
+
+Langage Extension Groups
+------------------------
+
 Language extensions groups shown here correspond to subsections of the GHC
-users' guide on language extensions.  Those of the :ref:`ungrouped-extension
-<ghc-ungrouped-extension>` group are undocumented in the GHC users' guide.
+users' guide on language extensions.
+
+.. Note::
+
+    The Cabal package grammar accepts any tokens for extension fields. The
+    extensions specified may be anything, something which a particular Cabal
+    version doesn't know about and this list of "known" extensions is not part
+    of the ``.cabal`` file specification and shown here only as a convenience.
+    The GHC users' guide is the place to look these up.
 
 .. _ghc-disable-extension:
 
@@ -217,71 +287,15 @@ bugs-extension
 .. _ghc-ungrouped-extension:
 
 ungrouped-extension
-    Language Extensions not belonging to other extension groups, includes undocumented extensions.
+    Language Extensions not belonging to other extension groups.
 
     .. math::
 
         \left\{ \begin{gathered}\mathop{\mathord{``}\mathtt{DoRec}\mathord{"}}\\\mathop{\mathord{``}\mathtt{PolymorphicComponents}\mathord{"}}\\\mathop{\mathord{``}\mathtt{PatternSignatures}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Generics}\mathord{"}}\\\mathop{\mathord{``}\mathtt{ExtensibleRecords}\mathord{"}}\\\mathop{\mathord{``}\mathtt{RestrictedTypeSynonyms}\mathord{"}}\\\mathop{\mathord{``}\mathtt{HereDocuments}\mathord{"}}\\\mathop{\mathord{``}\mathtt{RecordPuns}\mathord{"}}\\\mathop{\mathord{``}\mathtt{MonoPatBinds}\mathord{"}}\\\mathop{\mathord{``}\mathtt{RelaxedPolyRec}\mathord{"}}\\\mathop{\mathord{``}\mathtt{NewQualifiedOperators}\mathord{"}}\\\mathop{\mathord{``}\mathtt{XmlSyntax}\mathord{"}}\\\mathop{\mathord{``}\mathtt{RegularPatterns}\mathord{"}}\\\mathop{\mathord{``}\mathtt{DoAndIfThenElse}\mathord{"}}\\\mathop{\mathord{``}\mathtt{SafeImports}\mathord{"}}\\\mathop{\mathord{``}\mathtt{ParallelArrays}\mathord{"}}\\\mathop{\mathord{``}\mathtt{AutoDeriveTypeable}\mathord{"}}\\\mathop{\mathord{``}\mathtt{JavaScriptFFI}\mathord{"}}\\\mathop{\mathord{``}\mathtt{MonadFailDesugaring}\mathord{"}}\\\mathop{\mathord{``}\mathtt{AlternativeLayoutRule}\mathord{"}}\\\mathop{\mathord{``}\mathtt{AlternativeLayoutRuleTransitional}\mathord{"}}\\\mathop{\mathord{``}\mathtt{RelaxedLayout}\mathord{"}}\end{gathered} \right\}
 
 
-Package language fields
------------------------
-
-These are cabal package build info fields that control language.
-
-.. _ghc-default-extensions:
-
-default-extensions
-    * Monoidal field
-    * Available since ``cabal-version: 1.10``.
-    * Documentation of :pkg-field:`library:default-extensions`
-
-    .. math::
-
-        \mathrm{optcommalist}\left\{ \mathop{\mathit{enable\text{-}extension}}\mid\mathop{\mathit{disable\text{-}extension}} \right\}
-
-.. _ghc-default-language:
-
-default-language
-    * Optional field
-    * Available since ``cabal-version: 1.10``.
-    * Documentation of :pkg-field:`library:default-language`
-
-    .. math::
-
-        \left\{ \mathop{\mathord{``}\mathtt{GHC2021}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{Haskell2010}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{Haskell98}\mathord{"}} \right\}
-
-.. _ghc-extensions:
-
-extensions
-    * Monoidal field
-    * Deprecated since ``cabal-version: 1.12``: Please use 'default-extensions' or 'other-extensions' fields.
-    * Removed in ``cabal-version: 3.0``: Please use 'default-extensions' or 'other-extensions' fields.
-
-    .. math::
-
-        \mathrm{optcommalist}\left\{ \mathop{\mathit{enable\text{-}extension}}\mid\mathop{\mathit{disable\text{-}extension}} \right\}
-
-.. _ghc-other-extensions:
-
-other-extensions
-    * Monoidal field
-    * Documentation of :pkg-field:`library:other-extensions`
-
-    .. math::
-
-        \mathrm{optcommalist}\left\{ \mathop{\mathit{enable\text{-}extension}}\mid\mathop{\mathit{disable\text{-}extension}} \right\}
-
-.. _ghc-other-languages:
-
-other-languages
-    * Monoidal field
-    * Available since ``cabal-version: 1.10``.
-    * Documentation of :pkg-field:`library:other-languages`
-
-    .. math::
-
-        \mathrm{optcommalist}\left\{ \mathop{\mathord{``}\mathtt{GHC2021}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{Haskell2010}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{Haskell98}\mathord{"}} \right\}
-
+.. Warning::
 
+    Extensions of the :ref:`ungrouped-extension <ghc-ungrouped-extension>` group
+    are undocumented in the GHC users' guide.