Make language extensions their own category in the documentationwip/D4112

I.e. instead of

    .. ghc-flag:: -XUnboxedTuples
        :shortdesc: Enable the use of unboxed tuple syntax.
        :type: dynamic
        :reverse: -XNoUnboxedTuples
        :category:

one simply writes

    .. extension:: UnboxedTuples
        :shortdesc: Enable the use of unboxed tuple syntax.

This allows language extensions to be referenced as

    If :extension:`UnboxedTuples` is enabled, then...

This directive still creates the entries for the `-XUnboxedTuples` flag,
so in particular,

    Set :ghc-flag:`-XUnboxedTuples` if you have to.

still works, and lists of flags in general (e.g. for the manpage)
include these.

I also removed lots of links from the shortdesc of the extensions, when
this link simply points to the section where the extension is defined.

I removed the list of `-X` flags from the flag reference table, but added a
table of extension under “10.1. Language options”

Lots of text in the manual now refers to “extension `Foo`” rather than
“flag `-XFoo`”.

I consider `-XFoo` a historic artifact that stems from when language
extensions were really just flags. These days, the use of `-XFoo` is
(IMHO) deprecated: You should be using `LANGUAGE Foo`, or maybe the
appropriate field in a `.cabal` file. See 9278994 which did this change
to error messages already.

1 files changed, 6 insertions, 15 deletions

diff --git a/docs/users_guide/ffi-chap.rst b/docs/users_guide/ffi-chap.rst
index 6d41fa15d1..9beb4be870 100644
--- a/docs/users_guide/ffi-chap.rst
+++ b/docs/users_guide/ffi-chap.rst
@@ -7,11 +7,8 @@ Foreign function interface (FFI)
    single: Foreign function interface
    single: interfacing with native code
 
-.. ghc-flag:: -XForeignFunctionInterface
-    :shortdesc: Enable :ref:`foreign function interface <ffi>`.
-    :type: dynamic
-    :reverse: -XNoForeignFunctionInterface
-    :category: language
+.. extension:: ForeignFunctionInterface
+    :shortdesc: Enable foreign function interface.
 
     :since: 6.8.1
 
@@ -22,7 +19,7 @@ definition is part of the Haskell Report on
 `http://www.haskell.org/ <http://www.haskell.org/>`__.
 
 FFI support is enabled by default, but can be enabled or disabled
-explicitly with the :ghc-flag:`-XForeignFunctionInterface` flag.
+explicitly with the :extension:`ForeignFunctionInterface` flag.
 
 GHC implements a number of GHC-specific extensions to the FFI Chapter of the
 Haskell 2010 Report. These extensions are described in :ref:`ffi-ghcexts`, but
@@ -124,11 +121,8 @@ come with GHC. For more details see the
 Interruptible foreign calls
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XInterruptibleFFI
+.. extension:: InterruptibleFFI
     :shortdesc: Enable interruptible FFI.
-    :type: dynamic
-    :reverse: -XNoInterruptibleFFI
-    :category: language
 
     :since: 7.2.1
 
@@ -181,11 +175,8 @@ it is not typically necessary to handle ``ERROR_OPERATION_ABORTED``.
 The CAPI calling convention
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XCApiFFI
-    :shortdesc: Enable :ref:`the CAPI calling convention <ffi-capi>`.
-    :type: dynamic
-    :reverse: -XNoCAPIFFI
-    :category: language
+.. extension:: CApiFFI
+    :shortdesc: Enable the CAPI calling convention.
 
     :since: 7.10.1