User's Guide: forall is a keyword nowadays
[ghc.git] / docs / users_guide / glasgow_exts.rst
index 65f8629..eae0283 100644 (file)
@@ -31,7 +31,7 @@ Language options
    single: options; language
    single: extensions; options controlling
 
-The language option flags control what variation of the language are
+The language extensions control what variation of the language are
 permitted.
 
 Language options can be controlled in two ways:
@@ -44,6 +44,10 @@ Language options can be controlled in two ways:
    ``LANGUAGE`` pragma, thus ``{-# LANGUAGE TemplateHaskell #-}`` (see
    :ref:`language-pragma`).
 
+GHC supports these language options:
+
+.. extension-print::
+    :type: table
 
 Although not recommended, the deprecated :ghc-flag:`-fglasgow-exts` flag enables
 a large swath of the extensions supported by GHC at once.
@@ -53,7 +57,7 @@ a large swath of the extensions supported by GHC at once.
         see :ref:`options-language` for exactly which ones.
     :type: dynamic
     :reverse: -fno-glasgow-exts
-    :category:
+    :category: misc
 
     The flag ``-fglasgow-exts`` is equivalent to enabling the following extensions:
 
@@ -84,7 +88,7 @@ documentation is generated from the file ``compiler/prelude/primops.txt.pp``.)
 If you want to mention any of the primitive data types or operations in
 your program, you must first import ``GHC.Prim`` to bring them into
 scope. Many of them have names ending in ``#``, and to mention such names
-you need the :ghc-flag:`-XMagicHash` extension (:ref:`magic-hash`).
+you need the :extension:`MagicHash` extension.
 
 The primops make extensive use of `unboxed types <#glasgow-unboxed>`__
 and `unboxed tuples <#unboxed-tuples>`__, which we briefly summarise
@@ -144,24 +148,25 @@ stores a pointer. GHC currently does not support this variety of ``Just``
 nodes (nor for any other datatype). Accordingly, the *kind* of an unboxed
 type is different from the kind of a boxed type.
 
-The Haskell Report describes that ``*`` is the kind of ordinary datatypes,
-such as ``Int``. Furthermore, type constructors can have kinds with arrows;
-for example, ``Maybe`` has kind ``* -> *``. Unboxed types have a kind that
-specifies their runtime representation. For example, the type ``Int#`` has
-kind ``TYPE 'IntRep`` and ``Double#`` has kind ``TYPE 'DoubleRep``. These
-kinds say that the runtime representation of an ``Int#`` is a machine integer,
-and the runtime representation of a ``Double#`` is a machine double-precision
-floating point. In contrast, the kind ``*`` is actually just a synonym
-for ``TYPE 'PtrRepLifted``. More details of the ``TYPE`` mechanisms appear in
-the `section on runtime representation polymorphism <#runtime-rep>`__.
-
-Given that ``Int#``'s kind is not ``*``, it then it follows that
-``Maybe Int#`` is disallowed. Similarly, because type variables tend
-to be of kind ``*`` (for example, in ``(.) :: (b -> c) -> (a -> b) -> a -> c``,
-all the type variables have kind ``*``), polymorphism tends not to work
-over primitive types. Stepping back, this makes some sense, because
-a polymorphic function needs to manipulate the pointers to its data,
-and most primitive types are unboxed.
+The Haskell Report describes that ``*`` (spelled ``Type`` and imported from
+``Data.Kind`` in the GHC dialect of Haskell) is the kind of ordinary datatypes,
+such as ``Int``. Furthermore, type constructors can have kinds with arrows; for
+example, ``Maybe`` has kind ``Type -> Type``. Unboxed types have a kind that
+specifies their runtime representation. For example, the type ``Int#`` has kind
+``TYPE 'IntRep`` and ``Double#`` has kind ``TYPE 'DoubleRep``. These kinds say
+that the runtime representation of an ``Int#`` is a machine integer, and the
+runtime representation of a ``Double#`` is a machine double-precision floating
+point. In contrast, the kind ``Type`` is actually just a synonym for ``TYPE
+'LiftedRep``. More details of the ``TYPE`` mechanisms appear in the `section
+on runtime representation polymorphism <#runtime-rep>`__.
+
+Given that ``Int#``'s kind is not ``Type``, it then it follows that ``Maybe
+Int#`` is disallowed. Similarly, because type variables tend to be of kind
+``Type`` (for example, in ``(.) :: (b -> c) -> (a -> b) -> a -> c``, all the
+type variables have kind ``Type``), polymorphism tends not to work over
+primitive types. Stepping back, this makes some sense, because a polymorphic
+function needs to manipulate the pointers to its data, and most primitive types
+are unboxed.
 
 There are some restrictions on the use of primitive types:
 
@@ -205,18 +210,14 @@ There are some restrictions on the use of primitive types:
 Unboxed tuples
 --------------
 
-.. ghc-flag:: -XUnboxedTuples
-    :shortdesc: Enable :ref:`unboxed tuples <unboxed-tuples>`.
-    :type: dynamic
-    :reverse: -XNoUnboxedTuples
-    :category:
+.. extension:: UnboxedTuples
+    :shortdesc: Enable the use of unboxed tuple syntax.
 
     :since: 6.8.1
 
-    Enable the use of unboxed tuple syntax.
 
 Unboxed tuples aren't really exported by ``GHC.Exts``; they are a
-syntactic extension enabled by the language flag :ghc-flag:`-XUnboxedTuples`. An
+syntactic extension (:extension:`UnboxedTuples`). An
 unboxed tuple looks like this: ::
 
     (# e_1, ..., e_n #)
@@ -272,11 +273,8 @@ There are some restrictions on the use of unboxed tuples:
 Unboxed sums
 ------------
 
-.. ghc-flag:: -XUnboxedSums
-    :shortdesc: Enable :ref: `unboxed sums <unboxed-sums>`.
-    :type: dynamic
-    :reverse: -XNoUnboxedSums
-    :category:
+.. extension:: UnboxedSums
+    :shortdesc: Enable unboxed sums.
 
     :since: 8.2.1
 
@@ -287,21 +285,21 @@ for an unboxed sum type with N alternatives is ::
 
     (# t_1 | t_2 | ... | t_N #)
 
-where `t_1` ... `t_N` are types (which can be unlifted, including unboxed tuple
-and sums).
+where ``t_1`` ... ``t_N`` are types (which can be unlifted, including unboxed
+tuples and sums).
 
 Unboxed tuples can be used for multi-arity alternatives. For example: ::
 
     (# (# Int, String #) | Bool #)
 
-Term level syntax is similar. Leading and preceding bars (`|`) indicate which
-alternative it is. Here is two terms of the type shown above: ::
+The term level syntax is similar. Leading and preceding bars (`|`) indicate which
+alternative it is. Here are two terms of the type shown above: ::
 
     (# (# 1, "foo" #) | #) -- first alternative
 
     (# | True #) -- second alternative
 
-Pattern syntax reflects the term syntax: ::
+The pattern syntax reflects the term syntax: ::
 
     case x of
       (# (# i, str #) | #) -> ...
@@ -310,45 +308,56 @@ Pattern syntax reflects the term syntax: ::
 Unboxed sums are "unboxed" in the sense that, instead of allocating sums in the
 heap and representing values as pointers, unboxed sums are represented as their
 components, just like unboxed tuples. These "components" depend on alternatives
-of a sum type. Code generator tries to generate as compact layout as possible.
-In the best case, size of an unboxed sum is size of its biggest alternative +
-one word (for tag). The algorithm for generating memory layout for a sum type
-works like this:
+of a sum type. Like unboxed tuples, unboxed sums are lazy in their lifted
+components.
+
+The code generator tries to generate as compact layout as possible for each
+unboxed sum. In the best case, size of an unboxed sum is size of its biggest
+alternative plus one word (for a tag). The algorithm for generating the memory
+layout for a sum type works like this:
 
 - All types are classified as one of these classes: 32bit word, 64bit word,
   32bit float, 64bit float, pointer.
 
 - For each alternative of the sum type, a layout that consists of these fields
-  is generated. For example, if an alternative has `Int`, `Float#` and `String`
-  fields, the layout will have an 32bit word, 32bit float and pointer fields.
+  is generated. For example, if an alternative has ``Int``, ``Float#`` and
+  ``String`` fields, the layout will have an 32bit word, 32bit float and
+  pointer fields.
 
 - Layout fields are then overlapped so that the final layout will be as compact
-  as possible. E.g. say two alternatives have these fields: ::
+  as possible. For example, suppose we have the unboxed sum: ::
 
-    Word32, String, Float#
-    Float#, Float#, Maybe Int
+    (# (# Word32#, String, Float# #)
+    |  (# Float#, Float#, Maybe Int #) #)
 
-  Final layout will be something like ::
+  The final layout will be something like ::
 
     Int32, Float32, Float32, Word32, Pointer
 
-  First `Int32` is for the tag. It has two `Float32` fields because floating
-  point types can't overlap with other types, because of limitations of the code
-  generator that we're hoping to overcome in the future, and second alternative
-  needs two `Float32` fields. `Word32` field is for the `Word32` in the first
-  alternative. `Pointer` field is shared between `String` and `Maybe Int` values
-  of the alternatives.
-
-  In the case of enumeration types (like `Bool`), the unboxed sum layout only
-  has an `Int32` field (i.e. the whole thing is represented by an integer).
+  The first ``Int32`` is for the tag. There are two ``Float32`` fields because
+  floating point types can't overlap with other types, because of limitations of
+  the code generator that we're hoping to overcome in the future. The second
+  alternative needs two ``Float32`` fields: The ``Word32`` field is for the
+  ``Word32#`` in the first alternative. The ``Pointer`` field is shared between
+  ``String`` and ``Maybe Int`` values of the alternatives.
 
-In the example above, a value of this type is thus represented as 5 values. As
-an another example, this is the layout for unboxed version of `Maybe a` type: ::
+  As another example, this is the layout for the unboxed version of ``Maybe a``
+  type, ``(# (# #) | a #)``: ::
 
     Int32, Pointer
 
-The `Pointer` field is not used when tag says that it's `Nothing`. Otherwise
-`Pointer` points to the value in `Just`.
+  The ``Pointer`` field is not used when tag says that it's ``Nothing``.
+  Otherwise ``Pointer`` points to the value in ``Just``. As mentioned
+  above, this type is lazy in its lifted field. Therefore, the type ::
+
+    data Maybe' a = Maybe' (# (# #) | a #)
+
+  is *precisely* isomorphic to the type ``Maybe a``, although its memory
+  representation is different.
+
+  In the degenerate case where all the alternatives have zero width, such
+  as the ``Bool``-like ``(# (# #) | (# #) #)``, the unboxed sum layout only
+  has an ``Int32`` tag field (i.e., the whole thing is represented by an integer).
 
 .. _syntax-extns:
 
@@ -360,18 +369,15 @@ Syntactic extensions
 Unicode syntax
 --------------
 
-.. ghc-flag:: -XUnicodeSyntax
-    :shortdesc: Enable :ref:`unicode syntax <unicode-syntax>`.
-    :type: dynamic
-    :reverse: -XNoUnicodeSyntax
-    :category:
+.. extension:: UnicodeSyntax
+    :shortdesc: Enable unicode syntax.
 
     :since: 6.8.1
 
     Enable the use of Unicode characters in place of their equivalent ASCII
     sequences.
 
-The language extension :ghc-flag:`-XUnicodeSyntax` enables
+The language extension :extension:`UnicodeSyntax` enables
 Unicode characters to be used to stand for certain ASCII character
 sequences. The following alternatives are provided:
 
@@ -413,32 +419,29 @@ sequences. The following alternatives are provided:
 The magic hash
 --------------
 
-.. ghc-flag:: -XMagicHash
-    :shortdesc: Allow ``#`` as a :ref:`postfix modifier on identifiers <magic-hash>`.
-    :type: dynamic
-    :reverse: -XNoMagicHash
-    :category:
+.. extension:: MagicHash
+    :shortdesc: Allow ``#`` as a postfix modifier on identifiers.
 
     :since: 6.8.1
 
-    Enable the use of the hash character (``#``) as an identifier suffix.
+    Enables the use of the hash character (``#``) as an identifier suffix.
 
-The language extension :ghc-flag:`-XMagicHash` allows ``#`` as a postfix modifier
+The language extension :extension:`MagicHash` allows ``#`` as a postfix modifier
 to identifiers. Thus, ``x#`` is a valid variable, and ``T#`` is a valid type
 constructor or data constructor.
 
 The hash sign does not change semantics at all. We tend to use variable
 names ending in "#" for unboxed values or types (e.g. ``Int#``), but
 there is no requirement to do so; they are just plain ordinary
-variables. Nor does the :ghc-flag:`-XMagicHash` extension bring anything into
+variables. Nor does the :extension:`MagicHash` extension bring anything into
 scope. For example, to bring ``Int#`` into scope you must import
-``GHC.Prim`` (see :ref:`primitives`); the :ghc-flag:`-XMagicHash` extension then
+``GHC.Prim`` (see :ref:`primitives`); the :extension:`MagicHash` extension then
 allows you to *refer* to the ``Int#`` that is now in scope. Note that
 with this option, the meaning of ``x#y = 0`` is changed: it defines a
 function ``x#`` taking a single argument ``y``; to define the operator
 ``#``, put a space: ``x # y = 0``.
 
-The :ghc-flag:`-XMagicHash` also enables some new forms of literals (see
+The :extension:`MagicHash` also enables some new forms of literals (see
 :ref:`glasgow-unboxed`):
 
 -  ``'x'#`` has type ``Char#``
@@ -461,11 +464,8 @@ The :ghc-flag:`-XMagicHash` also enables some new forms of literals (see
 Negative literals
 -----------------
 
-.. ghc-flag:: -XNegativeLiterals
-    :shortdesc: Enable support for :ref:`negative literals <negative-literals>`.
-    :type: dynamic
-    :reverse: -XNoNegativeLiterals
-    :category:
+.. extension:: NegativeLiterals
+    :shortdesc: Enable support for negative literals.
 
     :since: 7.8.1
 
@@ -473,7 +473,7 @@ Negative literals
 
 The literal ``-123`` is, according to Haskell98 and Haskell 2010,
 desugared as ``negate (fromInteger 123)``. The language extension
-:ghc-flag:`-XNegativeLiterals` means that it is instead desugared as
+:extension:`NegativeLiterals` means that it is instead desugared as
 ``fromInteger (-123)``.
 
 This can make a difference when the positive and negative range of a
@@ -486,11 +486,8 @@ elicit an unexpected integer-literal-overflow message.
 Fractional looking integer literals
 -----------------------------------
 
-.. ghc-flag:: -XNumDecimals
+.. extension:: NumDecimals
     :shortdesc: Enable support for 'fractional' integer literals.
-    :type: dynamic
-    :reverse: -XNoNumDecimals
-    :category:
 
     :since: 7.8.1
 
@@ -499,7 +496,7 @@ Fractional looking integer literals
 Haskell 2010 and Haskell 98 define floating literals with the syntax
 ``1.2e6``. These literals have the type ``Fractional a => a``.
 
-The language extension :ghc-flag:`-XNumDecimals` allows you to also use the
+The language extension :extension:`NumDecimals` allows you to also use the
 floating literal syntax for instances of ``Integral``, and have values
 like ``(1.2e6 :: Num a => a)``
 
@@ -508,11 +505,8 @@ like ``(1.2e6 :: Num a => a)``
 Binary integer literals
 -----------------------
 
-.. ghc-flag:: -XBinaryLiterals
-    :shortdesc: Enable support for :ref:`binary literals <binary-literals>`.
-    :type: dynamic
-    :reverse: -XNoBinaryLiterals
-    :category:
+.. extension:: BinaryLiterals
+    :shortdesc: Enable support for binary literals.
 
     :since: 7.10.1
 
@@ -522,24 +516,150 @@ Haskell 2010 and Haskell 98 allows for integer literals to be given in
 decimal, octal (prefixed by ``0o`` or ``0O``), or hexadecimal notation
 (prefixed by ``0x`` or ``0X``).
 
-The language extension :ghc-flag:`-XBinaryLiterals` adds support for expressing
+The language extension :extension:`BinaryLiterals` adds support for expressing
 integer literals in binary notation with the prefix ``0b`` or ``0B``. For
 instance, the binary integer literal ``0b11001001`` will be desugared into
-``fromInteger 201`` when :ghc-flag:`-XBinaryLiterals` is enabled.
+``fromInteger 201`` when :extension:`BinaryLiterals` is enabled.
+
+.. _hex-float-literals:
+
+Hexadecimal floating point literals
+-----------------------------------
+
+.. extension:: HexFloatLiterals
+    :shortdesc: Enable support for :ref:`hexadecimal floating point literals <hex-float-literals>`.
+
+    :since: 8.4.1
+
+    Allow writing floating point literals using hexadecimal notation.
+
+The hexadecimal notation for floating point literals is useful when you
+need to specify floating point constants precisely, as the literal notation
+corresponds closely to the underlying bit-encoding of the number.
+
+In this notation floating point numbers are written using hexadecimal digits,
+and so the digits are interpreted using base 16, rather then the usual 10.
+This means that digits left of the decimal point correspond to positive
+powers of 16, while the ones to the right correspond to negative ones.
+
+You may also write an explicit exponent, which is similar to the exponent
+in decimal notation with the following differences:
+- the exponent begins with ``p`` instead of ``e``
+- the exponent is written in base ``10`` (**not** 16)
+- the base of the exponent is ``2`` (**not** 16).
+
+In terms of the underlying bit encoding, each hexadecimal digit corresponds
+to 4 bits, and you may think of the exponent as "moving" the floating point
+by one bit left (negative) or right (positive).  Here are some examples:
+
+-  ``0x0.1``     is the same as ``1/16``
+-  ``0x0.01``    is the same as ``1/256``
+-  ``0xF.FF``    is the same as ``15 + 15/16 + 15/256``
+-  ``0x0.1p4``   is the same as ``1``
+-  ``0x0.1p-4``  is the same as ``1/256``
+-  ``0x0.1p12``  is the same as ``256``
+
+
+
+
+.. _numeric-underscores:
+
+Numeric underscores
+-------------------
+
+.. extension:: NumericUnderscores
+    :shortdesc: Enable support for :ref:`numeric underscores <numeric-underscores>`.
+
+    :since: 8.6.1
+
+    Allow the use of underscores in numeric literals.
+
+GHC allows for numeric literals to be given in decimal, octal, hexadecimal,
+binary, or float notation.
+
+The language extension :extension:`NumericUnderscores` adds support for expressing
+underscores in numeric literals.
+For instance, the numeric literal ``1_000_000`` will be parsed into
+``1000000`` when :extension:`NumericUnderscores` is enabled.
+That is, underscores in numeric literals are ignored when
+:extension:`NumericUnderscores` is enabled.
+See also :ghc-ticket:`14473`.
+
+For example:
+
+.. code-block:: none
+
+    -- decimal
+    million    = 1_000_000
+    billion    = 1_000_000_000
+    lightspeed = 299_792_458
+    version    = 8_04_1
+    date       = 2017_12_31
+
+    -- hexadecimal
+    red_mask = 0xff_00_00
+    size1G   = 0x3fff_ffff
+
+    -- binary
+    bit8th   = 0b01_0000_0000
+    packbits = 0b1_11_01_0000_0_111
+    bigbits  = 0b1100_1011__1110_1111__0101_0011
+
+    -- float
+    pi       = 3.141_592_653_589_793
+    faraday  = 96_485.332_89
+    avogadro = 6.022_140_857e+23
+
+    -- function
+    isUnderMillion = (< 1_000_000)
+
+    clip64M x
+        | x > 0x3ff_ffff = 0x3ff_ffff
+        | otherwise = x
+
+    test8bit x = (0b01_0000_0000 .&. x) /= 0
+
+About validity:
+
+.. code-block:: none
+
+    x0 = 1_000_000   -- valid
+    x1 = 1__000000   -- valid
+    x2 = 1000000_    -- invalid
+    x3 = _1000000    -- invalid
+
+    e0 = 0.0001      -- valid
+    e1 = 0.000_1     -- valid
+    e2 = 0_.0001     -- invalid
+    e3 = _0.0001     -- invalid
+    e4 = 0._0001     -- invalid
+    e5 = 0.0001_     -- invalid
+
+    f0 = 1e+23       -- valid
+    f1 = 1_e+23      -- valid
+    f2 = 1__e+23     -- valid
+    f3 = 1e_+23      -- invalid
+
+    g0 = 1e+23       -- valid
+    g1 = 1e+_23      -- invalid
+    g2 = 1e+23_      -- invalid
+
+    h0 = 0xffff      -- valid
+    h1 = 0xff_ff     -- valid
+    h2 = 0x_ffff     -- valid
+    h3 = 0x__ffff    -- valid
+    h4 = _0xffff     -- invalid
 
 .. _pattern-guards:
 
 Pattern guards
 --------------
 
-.. ghc-flag:: -XNoPatternGuards
-    :shortdesc: Disable :ref:`pattern guards <pattern-guards>`.
-        Implied by :ghc-flag:`-XHaskell98`.
-    :type: dynamic
-    :reverse: -XPatternGuards
-    :category:
+.. extension:: NoPatternGuards
+    :shortdesc: Disable pattern guards.
+        Implied by :extension:`Haskell98`.
 
-    :implied by: :ghc-flag:`-XHaskell98`
+    :implied by: :extension:`Haskell98`
     :since: 6.8.1
 
 Disable `pattern guards
@@ -550,17 +670,14 @@ Disable `pattern guards
 View patterns
 -------------
 
-.. ghc-flag:: -XViewPatterns
-    :shortdesc: Enable :ref:`view patterns <view-patterns>`.
-    :type: dynamic
-    :reverse: -XNoViewPatterns
-    :category:
+.. extension:: ViewPatterns
+    :shortdesc: Enable view patterns.
 
     :since: 6.10.1
 
     Allow use of view pattern syntax.
 
-View patterns are enabled by the flag :ghc-flag:`-XViewPatterns`. More
+View patterns are enabled by the language extension :extension:`ViewPatterns`. More
 information and examples of view patterns can be found on the
 :ghc-wiki:`Wiki page <ViewPatterns>`.
 
@@ -626,7 +743,7 @@ follows:
       view pattern expression are in scope. For example: ::
 
           example :: Maybe ((String -> Integer,Integer), String) -> Bool
-          example Just ((f,_), f -> 4) = True
+          example (Just ((f,_), f -> 4)) = True
 
       Additionally, in function definitions, variables bound by matching
       earlier curried arguments may be used in view pattern expressions
@@ -694,14 +811,11 @@ follows:
 n+k patterns
 ------------
 
-.. ghc-flag:: -XNPlusKPatterns
+.. extension:: NPlusKPatterns
     :shortdesc: Enable support for ``n+k`` patterns.
-        Implied by :ghc-flag:`-XHaskell98`.
-    :type: dynamic
-    :reverse: -XNoNPlusKPatterns
-    :category:
+        Implied by :extension:`Haskell98`.
 
-    :implied by: :ghc-flag:`-XHaskell98`
+    :implied by: :extension:`Haskell98`
     :since: 6.12.1
 
     Enable use of ``n+k`` patterns.
@@ -711,11 +825,8 @@ n+k patterns
 The recursive do-notation
 -------------------------
 
-.. ghc-flag:: -XRecursiveDo
-    :shortdesc: Enable :ref:`recursive do (mdo) notation <recursive-do-notation>`.
-    :type: dynamic
-    :reverse: -XNoRecursiveDo
-    :category:
+.. extension:: RecursiveDo
+    :shortdesc: Enable recursive do (mdo) notation.
 
     :since: 6.8.1
 
@@ -742,7 +853,7 @@ the negative side, the continuation monad, with the signature
 
 For monads that do belong to the ``MonadFix`` class, GHC provides an
 extended version of the do-notation that allows recursive bindings. The
-:ghc-flag:`-XRecursiveDo` (language pragma: ``RecursiveDo``) provides the
+:extension:`RecursiveDo` (language pragma: ``RecursiveDo``) provides the
 necessary syntactic support, introducing the keywords ``mdo`` and
 ``rec`` for higher and lower levels of the notation respectively. Unlike
 bindings in a ``do`` expression, those introduced by ``mdo`` and ``rec``
@@ -778,7 +889,7 @@ lower level syntax flagged by the ``rec`` keyword, as we describe next.
 Recursive binding groups
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-The flag :ghc-flag:`-XRecursiveDo` also introduces a new keyword ``rec``, which
+The extension :extension:`RecursiveDo` also introduces a new keyword ``rec``, which
 wraps a mutually-recursive group of monadic statements inside a ``do``
 expression, producing a single statement. Similar to a ``let`` statement
 inside a ``do``, variables bound in the ``rec`` are visible throughout
@@ -897,8 +1008,8 @@ version would do so.
 
 Here are some other important points in using the recursive-do notation:
 
--  It is enabled with the flag :ghc-flag:`-XRecursiveDo`, or the
-   ``LANGUAGE RecursiveDo`` pragma. (The same flag enables both
+-  It is enabled with the extension :extension:`RecursiveDo`, or the
+   ``LANGUAGE RecursiveDo`` pragma. (The same extension enables both
    ``mdo``-notation, and the use of ``rec`` blocks inside ``do``
    expressions.)
 
@@ -929,17 +1040,14 @@ Applicative do-notation
    single: Applicative do-notation
    single: do-notation; Applicative
 
-.. ghc-flag:: -XApplicativeDo
-    :shortdesc: Enable :ref:`Applicative do-notation desugaring <applicative-do>`
-    :type: dynamic
-    :reverse: -XNoApplicativeDo
-    :category:
+.. extension:: ApplicativeDo
+    :shortdesc: Enable Applicative do-notation desugaring
 
     :since: 8.0.1
 
     Allow use of ``Applicative`` ``do`` notation.
 
-The language option :ghc-flag:`-XApplicativeDo` enables an alternative translation for
+The language option :extension:`ApplicativeDo` enables an alternative translation for
 the do-notation, which uses the operators ``<$>``, ``<*>``, along with ``join``
 as far as possible. There are two main reasons for wanting to do this:
 
@@ -951,10 +1059,10 @@ as far as possible. There are two main reasons for wanting to do this:
 Applicative do-notation desugaring preserves the original semantics, provided
 that the ``Applicative`` instance satisfies ``<*> = ap`` and ``pure = return``
 (these are true of all the common monadic types). Thus, you can normally turn on
-:ghc-flag:`-XApplicativeDo` without fear of breaking your program. There is one pitfall
+:extension:`ApplicativeDo` without fear of breaking your program. There is one pitfall
 to watch out for; see :ref:`applicative-do-pitfall`.
 
-There are no syntactic changes with :ghc-flag:`-XApplicativeDo`. The only way it shows
+There are no syntactic changes with :extension:`ApplicativeDo`. The only way it shows
 up at the source level is that you can have a ``do`` expression that doesn't
 require a ``Monad`` constraint. For example, in GHCi: ::
 
@@ -1074,52 +1182,12 @@ will always be connected with ``>>=``, to retain the same strictness
 semantics as the standard do-notation.  If you don't want this, simply
 put a ``~`` on the pattern match to make it lazy.
 
-.. _applicative-do-existential:
-
-Existential patterns and GADTs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When the pattern in a statement matches a constructor with
-existential type variables and/or constraints, the transformation that
-``ApplicativeDo`` performs may mean that the pattern does not scope
-over the statements that follow it.  This is because the rearrangement
-happens before the expression is typechecked.  For example, this
-program does not typecheck::
-
-    {-# LANGUAGE RankNTypes, GADTs, ApplicativeDo #-}
-
-    data T where A :: forall a . Eq a => a -> T
-
-    test = do
-      A x <- undefined
-      _ <- return 'a'
-      _ <- return 'b'
-      return (x == x)
-
-The reason is that the ``Eq`` constraint that would be brought into
-scope from the pattern match ``A x`` is not available when
-typechecking the expression ``x == x``, because ``ApplicativeDo`` has
-rearranged the expression to look like this::
-
-    test =
-      (\x _ -> x == x)
-        <$> do A x <- undefined; _ <- return 'a'; return x
-        <*> return 'b'
-
-(Note that the ``return 'a'`` and ``return 'b'`` statements are needed
-to make ``ApplicativeDo`` apply despite the restriction noted in
-:ref:`applicative-do-strict`, because ``A x`` is a strict pattern match.)
-
-Turning off ``ApplicativeDo`` lets the program typecheck.  This is
-something to bear in mind when using ``ApplicativeDo`` in combination
-with :ref:`existential-quantification` or :ref:`gadt`.
-
 .. _applicative-do-pitfall:
 
 Things to watch out for
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Your code should just work as before when :ghc-flag:`-XApplicativeDo` is enabled,
+Your code should just work as before when :extension:`ApplicativeDo` is enabled,
 provided you use conventional ``Applicative`` instances. However, if you define
 a ``Functor`` or ``Applicative`` instance using do-notation, then it will likely
 get turned into an infinite loop by GHC. For example, if you do this: ::
@@ -1163,13 +1231,8 @@ Parallel List Comprehensions
    single: list comprehensions; parallel
    single: parallel list comprehensions
 
-.. ghc-flag:: -XParallelListComp
-    :shortdesc: Enable :ref:`parallel list comprehensions
-        <parallel-list-comprehensions>`.
-        Implied by :ghc-flag:`-XParallelArrays`.
-    :type: dynamic
-    :reverse: -XNoParallelListComp
-    :category:
+.. extension:: ParallelListComp
+    :shortdesc: Enable parallel list comprehensions.
 
     :since: 6.8.1
 
@@ -1220,12 +1283,8 @@ Generalised (SQL-like) List Comprehensions
    single: group
    single: SQL
 
-.. ghc-flag:: -XTransformListComp
-    :shortdesc: Enable :ref:`generalised list comprehensions
-        <generalised-list-comprehensions>`.
-    :type: dynamic
-    :reverse: -XNoTransformListComp
-    :category:
+.. extension:: TransformListComp
+    :shortdesc: Enable generalised list comprehensions.
 
     :since: 6.10.1
 
@@ -1239,7 +1298,7 @@ paper `Comprehensive comprehensions: comprehensions with "order by" and
 "group by" <https://www.microsoft.com/en-us/research/wp-content/uploads/2007/09/list-comp.pdf>`__,
 except that the syntax we use differs slightly from the paper.
 
-The extension is enabled with the flag :ghc-flag:`-XTransformListComp`.
+The extension is enabled with the extension :extension:`TransformListComp`.
 
 Here is an example:
 
@@ -1365,11 +1424,8 @@ Monad comprehensions
 .. index::
    single: monad comprehensions
 
-.. ghc-flag:: -XMonadComprehensions
-    :shortdesc: Enable :ref:`monad comprehensions <monad-comprehensions>`.
-    :type: dynamic
-    :reverse: -XNoMonadComprehensions
-    :category:
+.. extension:: MonadComprehensions
+    :shortdesc: Enable monad comprehensions.
 
     :since: 7.2.1
 
@@ -1404,7 +1460,7 @@ Monad comprehensions support:
           guard (x <= 5)
           return x
 
--  Transform statements (as with :ghc-flag:`-XTransformListComp`): ::
+-  Transform statements (as with :extension:`TransformListComp`): ::
 
        [ x+y | x <- [1..10], y <- [1..x], then take 2 ]
 
@@ -1415,14 +1471,14 @@ Monad comprehensions support:
                               return (x,y))
           return (x+y)
 
--  Group statements (as with :ghc-flag:`-XTransformListComp`):
+-  Group statements (as with :extension:`TransformListComp`):
 
    ::
 
        [ x | x <- [1,1,2,2,3], then group by x using GHC.Exts.groupWith ]
        [ x | x <- [1,1,2,2,3], then group using myGroup ]
 
--  Parallel statements (as with :ghc-flag:`-XParallelListComp`):
+-  Parallel statements (as with :extension:`ParallelListComp`):
 
    ::
 
@@ -1442,7 +1498,7 @@ Monad comprehensions support:
                             return y)
           return (x+y)
 
-All these features are enabled by default if the :ghc-flag:`-XMonadComprehensions`
+All these features are enabled by default if the :extension:`MonadComprehensions`
 extension is enabled. The types and more detailed examples on how to use
 comprehensions are explained in the previous chapters
 :ref:`generalised-list-comprehensions` and
@@ -1453,7 +1509,7 @@ comprehensions.
 .. note::
     Even though most of these examples are using the list monad, monad
     comprehensions work for any monad. The ``base`` package offers all
-    necessary instances for lists, which make :ghc-flag:`-XMonadComprehensions`
+    necessary instances for lists, which make :extension:`MonadComprehensions`
     backward compatible to built-in, transform and parallel list
     comprehensions.
 
@@ -1531,11 +1587,8 @@ parameterised over some arbitrary type ``n`` (provided it has an
 New monadic failure desugaring mechanism
 ----------------------------------------
 
-.. ghc-flag:: -XMonadFailDesugaring
-    :shortdesc: Enable :ref:`monadfail desugaring <monadfail-desugaring>`.
-    :type: dynamic
-    :reverse: -XNoMonadFailDesugaring
-    :category:
+.. extension:: MonadFailDesugaring
+    :shortdesc: Enable monadfail desugaring.
 
     :since: 8.0.1
 
@@ -1543,26 +1596,22 @@ New monadic failure desugaring mechanism
     when desugaring refutable patterns in ``do`` blocks.
 
 The ``-XMonadFailDesugaring`` extension switches the desugaring of
-``do``-blocks to use ``MonadFail.fail`` instead of ``Monad.fail``. This will
-eventually be the default behaviour in a future GHC release, under the
+``do``-blocks to use ``MonadFail.fail`` instead of ``Monad.fail``.
+
+This extension is enabled by default since GHC 8.6.1, under the
 `MonadFail Proposal (MFP)
 <https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
 
-This extension is temporary, and will be deprecated in a future release. It is
-included so that library authors have a hard check for whether their code
-will work with future GHC versions.
+This extension is temporary, and will be deprecated in a future release.
 
 .. _rebindable-syntax:
 
 Rebindable syntax and the implicit Prelude import
 -------------------------------------------------
 
-.. ghc-flag:: -XNoImplicitPrelude
+.. extension:: NoImplicitPrelude
     :shortdesc: Don't implicitly ``import Prelude``.
-        Implied by :ghc-flag:`-XRebindableSyntax`.
-    :type: dynamic
-    :reverse: -XImplicitPrelude
-    :category:
+        Implied by :extension:`RebindableSyntax`.
 
     :since: 6.8.1
 
@@ -1574,14 +1623,11 @@ option. The idea is that you can then import a Prelude of your own. (But
 don't call it ``Prelude``; the Haskell module namespace is flat, and you
 must not conflict with any Prelude module.)
 
-.. ghc-flag:: -XRebindableSyntax
-    :shortdesc: Employ :ref:`rebindable syntax <rebindable-syntax>`.
-        Implies :ghc-flag:`-XNoImplicitPrelude`.
-    :type: dynamic
-    :reverse: -XNoRebindableSyntax
-    :category:
+.. extension:: RebindableSyntax
+    :shortdesc: Employ rebindable syntax.
+        Implies :extension:`NoImplicitPrelude`.
 
-    :implies: :ghc-flag:`-XNoImplicitPrelude`
+    :implies: :extension:`NoImplicitPrelude`
     :since: 7.0.1
 
     Enable rebinding of a variety of usually-built-in operations.
@@ -1589,16 +1635,19 @@ must not conflict with any Prelude module.)
 Suppose you are importing a Prelude of your own in order to define your
 own numeric class hierarchy. It completely defeats that purpose if the
 literal "1" means "``Prelude.fromInteger 1``", which is what the Haskell
-Report specifies. So the :ghc-flag:`-XRebindableSyntax` flag causes the
+Report specifies. So the :extension:`RebindableSyntax` extension causes the
 following pieces of built-in syntax to refer to *whatever is in scope*,
 not the Prelude versions:
 
 -  An integer literal ``368`` means "``fromInteger (368::Integer)``",
    rather than "``Prelude.fromInteger (368::Integer)``".
 
--  Fractional literals are handed in just the same way, except that the
+-  Fractional literals are handled in just the same way, except that the
    translation is ``fromRational (3.68::Rational)``.
 
+-  String literals are also handled the same way, except that the
+   translation is ``fromString ("368"::String)``.
+
 -  The equality test in an overloaded numeric pattern uses whatever
    ``(==)`` is in scope.
 
@@ -1630,7 +1679,7 @@ not the Prelude versions:
 -  An overloaded label "``#foo``" means "``fromLabel @"foo"``", rather than
    "``GHC.OverloadedLabels.fromLabel @"foo"``" (see :ref:`overloaded-labels`).
 
-:ghc-flag:`-XRebindableSyntax` implies :ghc-flag:`-XNoImplicitPrelude`.
+:extension:`RebindableSyntax` implies :extension:`NoImplicitPrelude`.
 
 In all cases (apart from arrow notation), the static semantics should be
 that of the desugared form, even if that is a little unexpected. For
@@ -1647,10 +1696,10 @@ Be warned: this is an experimental facility, with fewer checks than
 usual. Use ``-dcore-lint`` to typecheck the desugared program. If Core
 Lint is happy you should be all right.
 
-Things unaffected by :ghc-flag:`-XRebindableSyntax`
+Things unaffected by :extension:`RebindableSyntax`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:ghc-flag:`-XRebindableSyntax` does not apply to any code generated from a
+:extension:`RebindableSyntax` does not apply to any code generated from a
 ``deriving`` clause or declaration. To see why, consider the following code: ::
 
     {-# LANGUAGE RebindableSyntax, OverloadedStrings #-}
@@ -1666,12 +1715,12 @@ This will generate code to the effect of: ::
     instance Show Foo where
       showsPrec _ Foo = showString "Foo"
 
-But because :ghc-flag:`-XRebindableSyntax` and :ghc-flag:`-XOverloadedStrings`
+But because :extension:`RebindableSyntax` and :extension:`OverloadedStrings`
 are enabled, the ``"Foo"`` string literal would now be of type ``Text``, not
 ``String``, which ``showString`` doesn't accept! This causes the generated
 ``Show`` instance to fail to typecheck. It's hard to imagine any scenario where
-it would be desirable have :ghc-flag:`-XRebindableSyntax` behavior within
-derived code, so GHC simply ignores :ghc-flag:`-XRebindableSyntax` entirely
+it would be desirable have :extension:`RebindableSyntax` behavior within
+derived code, so GHC simply ignores :extension:`RebindableSyntax` entirely
 when checking derived code.
 
 .. _postfix-operators:
@@ -1679,17 +1728,14 @@ when checking derived code.
 Postfix operators
 -----------------
 
-.. ghc-flag:: -XPostfixOperators
-    :shortdesc: Enable :ref:`postfix operators <postfix-operators>`.
-    :type: dynamic
-    :reverse: -XNoPostfixOperators
-    :category:
+.. extension:: PostfixOperators
+    :shortdesc: Enable postfix operators.
 
     :since: 7.10.1
 
     Allow the use of post-fix operators
 
-The :ghc-flag:`-XPostfixOperators` flag enables a small extension to the syntax
+The :extension:`PostfixOperators` extension enables a small extension to the syntax
 of left operator sections, which allows you to define postfix operators.
 The extension is this: the left section ::
 
@@ -1717,17 +1763,14 @@ definitions; you must define such a function in prefix form.
 Tuple sections
 --------------
 
-.. ghc-flag:: -XTupleSections
-    :shortdesc: Enable :ref:`tuple sections <tuple-sections>`.
-    :type: dynamic
-    :reverse: -XNoTupleSections
-    :category:
+.. extension:: TupleSections
+    :shortdesc: Enable tuple sections.
 
     :since: 6.12
 
     Allow the use of tuple section syntax
 
-The :ghc-flag:`-XTupleSections` flag enables partially applied
+The :extension:`TupleSections` extension enables partially applied
 tuple constructors. For example, the following program ::
 
       (, True)
@@ -1762,17 +1805,14 @@ continues to stand for the unboxed singleton tuple data constructor.
 Lambda-case
 -----------
 
-.. ghc-flag:: -XLambdaCase
-    :shortdesc: Enable :ref:`lambda-case expressions <lambda-case>`.
-    :type: dynamic
-    :reverse: -XNoLambdaCase
-    :category:
+.. extension:: LambdaCase
+    :shortdesc: Enable lambda-case expressions.
 
     :since: 7.6.1
 
     Allow the use of lambda-case syntax.
 
-The :ghc-flag:`-XLambdaCase` flag enables expressions of the form ::
+The :extension:`LambdaCase` extension enables expressions of the form ::
 
       \case { p1 -> e1; ...; pN -> eN }
 
@@ -1792,17 +1832,14 @@ Note that ``\case`` starts a layout, so you can write ::
 Empty case alternatives
 -----------------------
 
-.. ghc-flag:: -XEmptyCase
-    :shortdesc: Allow :ref:`empty case alternatives <empty-case>`.
-    :type: dynamic
-    :reverse: -XNoEmptyCase
-    :category:
+.. extension:: EmptyCase
+    :shortdesc: Allow empty case alternatives.
 
     :since: 7.8.1
 
     Allow empty case expressions.
 
-The :ghc-flag:`-XEmptyCase` flag enables case expressions, or lambda-case
+The :extension:`EmptyCase` extension enables case expressions, or lambda-case
 expressions, that have no alternatives, thus: ::
 
     case e of { }   -- No alternatives
@@ -1843,17 +1880,14 @@ check to make sure that, in fact, the function can never get called.
 Multi-way if-expressions
 ------------------------
 
-.. ghc-flag:: -XMultiWayIf
-    :shortdesc: Enable :ref:`multi-way if-expressions <multi-way-if>`.
-    :type: dynamic
-    :reverse: -XNoMultiWayIf
-    :category:
+.. extension:: MultiWayIf
+    :shortdesc: Enable multi-way if-expressions.
 
     :since: 7.6.1
 
     Allow the use of multi-way-``if`` syntax.
 
-With :ghc-flag:`-XMultiWayIf` flag GHC accepts conditional expressions with
+With :extension:`MultiWayIf` extension GHC accepts conditional expressions with
 multiple branches: ::
 
       if | guard1 -> expr1
@@ -1926,7 +1960,7 @@ elsewhere, as in ::
 
     let infixr 9 $ in ...
 
-Because local fixity declarations are technically Haskell 98, no flag is
+Because local fixity declarations are technically Haskell 98, no extension is
 necessary to enable them.
 
 .. _package-imports:
@@ -1963,17 +1997,14 @@ not export.
 Package-qualified imports
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XPackageImports
-    :shortdesc: Enable :ref:`package-qualified imports <package-imports>`.
-    :type: dynamic
-    :reverse: -XNoPackageImports
-    :category:
+.. extension:: PackageImports
+    :shortdesc: Enable package-qualified imports.
 
     :since: 6.10.1
 
     Allow the use of package-qualified ``import`` syntax.
 
-With the :ghc-flag:`-XPackageImports` flag, GHC allows import declarations to be
+With the :extension:`PackageImports` extension, GHC allows import declarations to be
 qualified by the package name that the module is intended to be imported
 from. For example: ::
 
@@ -2000,37 +2031,31 @@ package being built.
 Safe imports
 ~~~~~~~~~~~~
 
-.. ghc-flag:: -XSafe
+.. extension:: Safe
     :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Safe mode.
-    :type: dynamic
-    :category:
     :noindex:
 
     :since: 7.2.1
 
     Declare the Safe Haskell state of the current module.
 
-.. ghc-flag:: -XTrustworthy
+.. extension:: Trustworthy
     :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Trustworthy mode.
-    :type: dynamic
-    :category:
     :noindex:
 
     :since: 7.2.1
 
     Declare the Safe Haskell state of the current module.
 
-.. ghc-flag:: -XUnsafe
-    :shortdesc: Enable :ref:`Safe Haskell <safe-haskell>` Unsafe mode.
-    :type: dynamic
-    :category:
+.. extension:: Unsafe
+    :shortdesc: Enable Safe Haskell Unsafe mode.
     :noindex:
 
     :since: 7.4.1
 
     Declare the Safe Haskell state of the current module.
 
-With the :ghc-flag:`-XSafe`, :ghc-flag:`-XTrustworthy` and :ghc-flag:`-XUnsafe`
+With the :extension:`Safe`, :extension:`Trustworthy` and :extension:`Unsafe`
 language flags, GHC extends the import declaration syntax to take an optional
 ``safe`` keyword after the ``import`` keyword. This feature is part of the Safe
 Haskell GHC extension. For example: ::
@@ -2046,13 +2071,10 @@ when a import is considered safe see :ref:`safe-haskell`.
 Explicit namespaces in import/export
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XExplicitNamespaces
+.. extension:: ExplicitNamespaces
     :shortdesc: Enable using the keyword ``type`` to specify the namespace of
         entries in imports and exports (:ref:`explicit-namespaces`).
-        Implied by :ghc-flag:`-XTypeOperators` and :ghc-flag:`-XTypeFamilies`.
-    :type: dynamic
-    :reverse: -XNoExplicitNamespaces
-    :category:
+        Implied by :extension:`TypeOperators` and :extension:`TypeFamilies`.
 
     :since: 7.6.1
 
@@ -2069,7 +2091,7 @@ operators (:ref:`type-operators`) it becomes possible to declare
 ``(++)`` as a *type constructor*. In that case, how would you export or
 import it?
 
-The :ghc-flag:`-XExplicitNamespaces` extension allows you to prefix the name of
+The :extension:`ExplicitNamespaces` extension allows you to prefix the name of
 a type constructor in an import or export list with "``type``" to
 disambiguate this case, thus: ::
 
@@ -2079,14 +2101,112 @@ disambiguate this case, thus: ::
       module N( f, type (++) ) where
         data family a ++ b = L a | R b
 
-The extension :ghc-flag:`-XExplicitNamespaces` is implied by
-:ghc-flag:`-XTypeOperators` and (for some reason) by :ghc-flag:`-XTypeFamilies`.
+The extension :extension:`ExplicitNamespaces` is implied by
+:extension:`TypeOperators` and (for some reason) by :extension:`TypeFamilies`.
 
-In addition, with :ghc-flag:`-XPatternSynonyms` you can prefix the name of a
+In addition, with :extension:`PatternSynonyms` you can prefix the name of a
 data constructor in an import or export list with the keyword
 ``pattern``, to allow the import or export of a data constructor without
 its parent type constructor (see :ref:`patsyn-impexp`).
 
+.. _block-arguments:
+
+More liberal syntax for function arguments
+------------------------------------------
+
+.. extension:: BlockArguments
+    :shortdesc: Allow ``do`` blocks and other constructs as function arguments.
+
+    :since: 8.6.1
+
+    Allow ``do`` expressions, lambda expressions, etc. to be directly used as
+    a function argument.
+
+In Haskell 2010, certain kinds of expressions can be used without parentheses
+as an argument to an operator, but not as an argument to a function.
+They include ``do``, lambda, ``if``, ``case``, and ``let``
+expressions. Some GHC extensions also define language constructs of this type:
+``mdo`` (:ref:`recursive-do-notation`), ``\case`` (:ref:`lambda-case`), and
+``proc`` (:ref:`arrow-notation`).
+
+The :extension:`BlockArguments` extension allows these constructs to be directly
+used as a function argument. For example::
+
+    when (x > 0) do
+      print x
+      exitFailure
+
+will be parsed as::
+
+    when (x > 0) (do
+      print x
+      exitFailure)
+
+and
+
+::
+
+    withForeignPtr fptr \ptr -> c_memcpy buf ptr size
+
+will be parsed as::
+
+    withForeignPtr fptr (\ptr -> c_memcpy buf ptr size)
+
+Changes to the grammar
+~~~~~~~~~~~~~~~~~~~~~~
+
+The Haskell report `defines
+<https://www.haskell.org/onlinereport/haskell2010/haskellch3.html#x8-220003>`_
+the ``lexp`` nonterminal thus (``*`` indicates a rule of interest)::
+
+    lexp  →  \ apat1 … apatn -> exp            (lambda abstraction, n ≥ 1)  *
+          |  let decls in exp                  (let expression)             *
+          |  if exp [;] then exp [;] else exp  (conditional)                *
+          |  case exp of { alts }              (case expression)            *
+          |  do { stmts }                      (do expression)              *
+          |  fexp
+
+    fexp  →  [fexp] aexp                       (function application)
+
+    aexp  →  qvar                              (variable)
+          |  gcon                              (general constructor)
+          |  literal
+          |  ( exp )                           (parenthesized expression)
+          |  qcon { fbind1 … fbindn }          (labeled construction)
+          |  aexp { fbind1 … fbindn }          (labelled update)
+          |  …
+
+The :extension:`BlockArguments` extension moves these production rules under
+``aexp``::
+
+    lexp  →  fexp
+
+    fexp  →  [fexp] aexp                       (function application)
+
+    aexp  →  qvar                              (variable)
+          |  gcon                              (general constructor)
+          |  literal
+          |  ( exp )                           (parenthesized expression)
+          |  qcon { fbind1 … fbindn }          (labeled construction)
+          |  aexp { fbind1 … fbindn }          (labelled update)
+          |  \ apat1 … apatn -> exp            (lambda abstraction, n ≥ 1)  *
+          |  let decls in exp                  (let expression)             *
+          |  if exp [;] then exp [;] else exp  (conditional)                *
+          |  case exp of { alts }              (case expression)            *
+          |  do { stmts }                      (do expression)              *
+          |  …
+
+Now the ``lexp`` nonterminal is redundant and can be dropped from the grammar.
+
+Note that this change relies on an existing meta-rule to resolve ambiguities:
+
+    The grammar is ambiguous regarding the extent of lambda abstractions, let
+    expressions, and conditionals. The ambiguity is resolved by the meta-rule
+    that each of these constructs extends as far to the right as possible.
+
+For example, ``f \a -> a b`` will be parsed as ``f (\a -> a b)``, not as ``f
+(\a -> a) b``.
+
 .. _syntax-stolen:
 
 Summary of stolen syntax
@@ -2116,39 +2236,40 @@ The following syntax is stolen:
     .. index::
        single: forall
 
-    Stolen (in types) by: :ghc-flag:`-XExplicitForAll`, and hence by
-    :ghc-flag:`-XScopedTypeVariables`, :ghc-flag:`-XLiberalTypeSynonyms`,
-    :ghc-flag:`-XRankNTypes`, :ghc-flag:`-XExistentialQuantification`
+    Stolen (in types) by default (see :ref:`infelicities-lexical`). ``forall`` is
+    a reserved keyword and never a type variable, in accordance with `GHC Proposal #43
+    <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0043-forall-keyword.rst>`__.
+
 
 ``mdo``
     .. index::
        single: mdo
 
-    Stolen by: :ghc-flag:`-XRecursiveDo`
+    Stolen by: :extension:`RecursiveDo`
 
 ``foreign``
     .. index::
        single: foreign
 
-    Stolen by: :ghc-flag:`-XForeignFunctionInterface`
+    Stolen by: :extension:`ForeignFunctionInterface`
 
 ``rec``, ``proc``, ``-<``, ``>-``, ``-<<``, ``>>-``, ``(|``, ``|)``
     .. index::
        single: proc
 
-    Stolen by: :ghc-flag:`-XArrows`
+    Stolen by: :extension:`Arrows`
 
 ``?varid``
     .. index::
        single: implicit parameters
 
-    Stolen by: :ghc-flag:`-XImplicitParams`
+    Stolen by: :extension:`ImplicitParams`
 
 ``[|``, ``[e|``, ``[p|``, ``[d|``, ``[t|``, ``[||``, ``[e||``
     .. index::
        single: Quasi-quotes
 
-    Stolen by: :ghc-flag:`-XQuasiQuotes`. Moreover, this introduces an ambiguity
+    Stolen by: :extension:`QuasiQuotes`. Moreover, this introduces an ambiguity
     with list comprehension syntax. See the
     :ref:`discussion on quasi-quoting <quasi-quotes-list-comprehension-ambiguity>`
     for details.
@@ -2157,25 +2278,28 @@ The following syntax is stolen:
     .. index::
        single: Template Haskell
 
-    Stolen by: :ghc-flag:`-XTemplateHaskell`
+    Stolen by: :extension:`TemplateHaskell`
 
 ``[varid|``
     .. index::
        single: quasi-quotation
 
-    Stolen by: :ghc-flag:`-XQuasiQuotes`
+    Stolen by: :extension:`QuasiQuotes`
 
 ⟨varid⟩, ``#``\ ⟨char⟩, ``#``, ⟨string⟩, ``#``, ⟨integer⟩, ``#``, ⟨float⟩, ``#``, ⟨float⟩, ``##``
-    Stolen by: :ghc-flag:`-XMagicHash`
+    Stolen by: :extension:`MagicHash`
 
 ``(#``, ``#)``
-    Stolen by: :ghc-flag:`-XUnboxedTuples`
+    Stolen by: :extension:`UnboxedTuples`
 
 ⟨varid⟩, ``!``, ⟨varid⟩
-    Stolen by: :ghc-flag:`-XBangPatterns`
+    Stolen by: :extension:`BangPatterns`
 
 ``pattern``
-    Stolen by: :ghc-flag:`-XPatternSynonyms`
+    Stolen by: :extension:`PatternSynonyms`
+
+``static``
+    Stolen by: :extension:`StaticPointers`
 
 .. _data-type-extensions:
 
@@ -2187,39 +2311,45 @@ Extensions to data types and type synonyms
 Data types with no constructors
 -------------------------------
 
-.. ghc-flag:: -XEmptyDataDecls
+.. extension:: EmptyDataDecls
     :shortdesc: Allow definition of empty ``data`` types.
-    :type: dynamic
-    :reverse: -XNoEmptyDataDecls
-    :category:
 
     :since: 6.8.1
 
     Allow definition of empty ``data`` types.
 
-With the :ghc-flag:`-XEmptyDataDecls` flag (or equivalent ``LANGUAGE`` pragma), GHC
-lets you declare a data type with no constructors. For example: ::
+With the :extension:`EmptyDataDecls` extension, GHC lets you declare a
+data type with no constructors.
+
+You only need to enable this extension if the language you're using
+is Haskell 98, in which a data type must have at least one constructor.
+Haskell 2010 relaxed this rule to allow data types with no constructors,
+and thus :extension:`EmptyDataDecls` is enabled by default when the
+language is Haskell 2010.
+
+For example: ::
 
-      data S      -- S :: *
-      data T a    -- T :: * -> *
+      data S      -- S :: Type
+      data T a    -- T :: Type -> Type
 
-Syntactically, the declaration lacks the "= constrs" part. The type can
-be parameterised over types of any kind, but if the kind is not ``*``
-then an explicit kind annotation must be used (see :ref:`kinding`).
+Syntactically, the declaration lacks the "= constrs" part. The type can be
+parameterised over types of any kind, but if the kind is not ``Type`` then an
+explicit kind annotation must be used (see :ref:`kinding`).
 
 Such data types have only one value, namely bottom. Nevertheless, they
 can be useful when defining "phantom types".
 
+In conjunction with the :ghc-flag:`-XEmptyDataDeriving` extension, empty data
+declarations can also derive instances of standard type classes
+(see :ref:`empty-data-deriving`).
+
 .. _datatype-contexts:
 
 Data type contexts
 ------------------
 
-.. ghc-flag:: -XDatatypeContexts
+.. extension:: DatatypeContexts
     :shortdesc: Allow contexts on ``data`` types.
-    :type: dynamic
-    :reverse: -XNoEmptyDataDecls
-    :category:
 
     :since: 7.0.1
 
@@ -2283,22 +2413,18 @@ specifically:
    sets the fixity for both type constructor ``T`` and data constructor
    ``T``, and similarly for ``:*:``. ``Int `a` Bool``.
 
--  Function arrow is ``infixr`` with fixity 0 (this might change; it's
-   not clear what it should be).
+-  The function arrow ``->`` is ``infixr`` with fixity -1.
 
 .. _type-operators:
 
 Type operators
 --------------
 
-.. ghc-flag:: -XTypeOperators
-    :shortdesc: Enable :ref:`type operators <type-operators>`.
-        Implies :ghc-flag:`-XExplicitNamespaces`.
-    :type: dynamic
-    :reverse: -XNoTypeOperators
-    :category:
+.. extension:: TypeOperators
+    :shortdesc: Enable type operators.
+        Implies :extension:`ExplicitNamespaces`.
 
-    :implies: :ghc-flag:`-XExplicitNamespaces`
+    :implies: :extension:`ExplicitNamespaces`
     :since: 6.8.1
 
     Allow the use and definition of types with operator names.
@@ -2317,7 +2443,7 @@ In types, an operator symbol like ``(+)`` is normally treated as a type
 As you can see, using operators in this way is not very useful, and
 Haskell 98 does not even allow you to write them infix.
 
-The language :ghc-flag:`-XTypeOperators` changes this behaviour:
+The language :extension:`TypeOperators` changes this behaviour:
 
 -  Operator symbols become type *constructors* rather than type
    *variables*.
@@ -2331,8 +2457,8 @@ The language :ghc-flag:`-XTypeOperators` changes this behaviour:
 -  There is now some potential ambiguity in import and export lists; for
    example if you write ``import M( (+) )`` do you mean the *function*
    ``(+)`` or the *type constructor* ``(+)``? The default is the former,
-   but with :ghc-flag:`-XExplicitNamespaces` (which is implied by
-   :ghc-flag:`-XTypeOperators`) GHC allows you to specify the latter by
+   but with :extension:`ExplicitNamespaces` (which is implied by
+   :extension:`TypeOperators`) GHC allows you to specify the latter by
    preceding it with the keyword ``type``, thus: ::
 
        import M( type (+) )
@@ -2348,20 +2474,17 @@ The language :ghc-flag:`-XTypeOperators` changes this behaviour:
 Liberalised type synonyms
 -------------------------
 
-.. ghc-flag:: -XLiberalTypeSynonyms
-    :shortdesc: Enable :ref:`liberalised type synonyms <type-synonyms>`.
-    :type: dynamic
-    :reverse: -XNoLiberalTypeSynonyms
-    :category:
+.. extension:: LiberalTypeSynonyms
+    :shortdesc: Enable liberalised type synonyms.
 
-    :implies: :ghc-flag:`-XExplicitForAll`
+    :implies: :extension:`ExplicitForAll`
     :since: 6.8.1
 
     Relax many of the Haskell 98 rules on type synonym definitions.
 
 Type synonyms are like macros at the type level, but Haskell 98 imposes
 many rules on individual synonym declarations. With the
-:ghc-flag:`-XLiberalTypeSynonyms` extension, GHC does validity checking on types
+:extension:`LiberalTypeSynonyms` extension, GHC does validity checking on types
 *only after expanding type synonyms*. That means that GHC can be very
 much more liberal about type synonyms than Haskell 98.
 
@@ -2376,7 +2499,7 @@ much more liberal about type synonyms than Haskell 98.
          g :: Discard Int -> (Int,String)    -- A rank-2 type
          g f = f 3 True
 
--  If you also use :ghc-flag:`-XUnboxedTuples`, you can write an unboxed tuple
+-  If you also use :extension:`UnboxedTuples`, you can write an unboxed tuple
    in a type synonym: ::
 
          type Pr = (# Int, Int #)
@@ -2413,7 +2536,7 @@ looking for the following malformedness which isn't detected simply by
 kind checking:
 
 -  Type constructor applied to a type involving for-alls (if
-   :ghc-flag:`-XImpredicativeTypes` is off)
+   :extension:`ImpredicativeTypes` is off)
 
 -  Partially-applied type synonym.
 
@@ -2431,13 +2554,10 @@ because GHC does not allow type constructors applied to for-all types.
 Existentially quantified data constructors
 ------------------------------------------
 
-.. ghc-flag:: -XExistentialQuantification
-    :shortdesc: Enable :ref:`liberalised type synonyms <type-synonyms>`.
-    :type: dynamic
-    :reverse: -XNoLiberalTypeSynonyms
-    :category:
+.. extension:: ExistentialQuantification
+    :shortdesc: Enable liberalised type synonyms.
 
-    :implies: :ghc-flag:`-XExplicitForAll`
+    :implies: :extension:`ExplicitForAll`
     :since: 6.8.1
 
     Allow existentially quantified type variables in types.
@@ -2692,16 +2812,13 @@ constructors can be used.
 Declaring data types with explicit constructor signatures
 ---------------------------------------------------------
 
-.. ghc-flag:: -XGADTSyntax
-    :shortdesc: Enable :ref:`generalised algebraic data type syntax <gadt-style>`.
-    :type: dynamic
-    :reverse: -XNoGADTSyntax
-    :category:
+.. extension:: GADTSyntax
+    :shortdesc: Enable generalised algebraic data type syntax.
 
     :since: 7.2.1
 
     Allow the use of GADT syntax in data type definitions (but not GADTs
-    themselves; for this see :ghc-flag:`-XGADTs`)
+    themselves; for this see :extension:`GADTs`)
 
 When the ``GADTSyntax`` extension is enabled, GHC allows you to declare
 an algebraic data type by giving the type signatures of constructors
@@ -2845,16 +2962,16 @@ type declarations.
    in the "``data Set a where``" header have no scope. Indeed, one can
    write a kind signature instead: ::
 
-         data Set :: * -> * where ...
+         data Set :: Type -> Type where ...
 
    or even a mixture of the two: ::
 
-         data Bar a :: (* -> *) -> * where ...
+         data Bar a :: (Type -> Type) -> Type where ...
 
    The type variables (if given) may be explicitly kinded, so we could
    also write the header for ``Foo`` like this: ::
 
-         data Bar a (b :: * -> *) where ...
+         data Bar a (b :: Type -> Type) where ...
 
 -  You can use strictness annotations, in the obvious places in the
    constructor type: ::
@@ -2948,14 +3065,11 @@ type declarations.
 Generalised Algebraic Data Types (GADTs)
 ----------------------------------------
 
-.. ghc-flag:: -XGADTs
-    :shortdesc: Enable :ref:`generalised algebraic data types <gadt>`.
-        Implies :ghc-flag:`-XGADTSyntax` and :ghc-flag:`-XMonoLocalBinds`.
-    :type: dynamic
-    :reverse: -XNoGADTs
-    :category:
+.. extension:: GADTs
+    :shortdesc: Enable generalised algebraic data types.
+        Implies :extension:`GADTSyntax` and :extension:`MonoLocalBinds`.
 
-    :implies: :ghc-flag:`-XMonoLocalBinds`, :ghc-flag:`-XGADTSyntax`
+    :implies: :extension:`MonoLocalBinds`, :extension:`GADTSyntax`
     :since: 6.8.1
 
     Allow use of Generalised Algebraic Data Types (GADTs).
@@ -3016,8 +3130,8 @@ has a number of examples. Note that papers may use different notation to
 that implemented in GHC.
 
 The rest of this section outlines the extensions to GHC that support
-GADTs. The extension is enabled with :ghc-flag:`-XGADTs`. The :ghc-flag:`-XGADTs` flag
-also sets :ghc-flag:`-XGADTSyntax` and :ghc-flag:`-XMonoLocalBinds`.
+GADTs. The extension is enabled with :extension:`GADTs`. The :extension:`GADTs` extension
+also sets :extension:`GADTSyntax` and :extension:`MonoLocalBinds`.
 
 -  A GADT can only be declared using GADT-style syntax
    (:ref:`gadt-style`); the old Haskell 98 syntax for data declarations
@@ -3093,33 +3207,25 @@ Extensions to the record system
 Traditional record syntax
 -------------------------
 
-.. ghc-flag:: -XNoTraditionalRecordSyntax
+.. extension:: NoTraditionalRecordSyntax
     :shortdesc: Disable support for traditional record syntax
         (as supported by Haskell 98) ``C {f = x}``
-    :type: dynamic
-    :reverse: -XTraditionalRecordSyntax
-    :category:
 
     :since: 7.4.1
 
     Disallow use of record syntax.
 
 Traditional record syntax, such as ``C {f = x}``, is enabled by default.
-To disable it, you can use the :ghc-flag:`-XNoTraditionalRecordSyntax` flag.
+To disable it, you can use the :extension:`NoTraditionalRecordSyntax` extension.
 
 .. _disambiguate-fields:
 
 Record field disambiguation
 ---------------------------
 
-.. ghc-flag:: -XDisambiguateRecordFields
-    :shortdesc: Enable :ref:`record field disambiguation <disambiguate-fields>`.
-        Implied by :ghc-flag:`-XRecordWildCards`.
-    :type: dynamic
-    :reverse: -XNoDisambiguateRecordFields
-    :category:
-
-    :since: 6.8.1
+.. extension:: DisambiguateRecordFields
+    :shortdesc: Enable record field disambiguation.
+        Implied by :extension:`RecordWildCards`.
 
     :since: 6.8.1
 
@@ -3153,7 +3259,7 @@ the record update in ``bad1`` and the record selection in ``bad2`` it is
 not clear which of the two types is intended.
 
 Haskell 98 regards all four as ambiguous, but with the
-:ghc-flag:`-XDisambiguateRecordFields` flag, GHC will accept the former two. The
+:extension:`DisambiguateRecordFields` extension, GHC will accept the former two. The
 rules are precisely the same as those for instance declarations in
 Haskell 98, where the method names on the left-hand side of the method
 bindings in an instance declaration refer unambiguously to the method of
@@ -3172,7 +3278,7 @@ Some details:
          x=True
          ok3 (MkS { x }) = x+1   -- Uses both disambiguation and punning
 
--  With :ghc-flag:`-XDisambiguateRecordFields` you can use *unqualified* field
+-  With :extension:`DisambiguateRecordFields` you can use *unqualified* field
    names even if the corresponding selector is only in scope *qualified*
    For example, assuming the same module ``M`` as in our earlier
    example, this is legal: ::
@@ -3192,19 +3298,16 @@ Some details:
 Duplicate record fields
 -----------------------
 
-.. ghc-flag:: -XDuplicateRecordFields
+.. extension:: DuplicateRecordFields
     :shortdesc: Allow definition of record types with identically-named fields.
-    :type: dynamic
-    :reverse: -XNoDuplicateRecordFields
-    :category:
 
-    :implies: :ghc-flag:`-XDisambiguateRecordFields`
+    :implies: :extension:`DisambiguateRecordFields`
     :since: 8.0.1
 
     Allow definition of record types with identically-named fields.
 
-Going beyond :ghc-flag:`-XDisambiguateRecordFields` (see :ref:`disambiguate-fields`),
-the :ghc-flag:`-XDuplicateRecordFields` extension allows multiple datatypes to be
+Going beyond :extension:`DisambiguateRecordFields` (see :ref:`disambiguate-fields`),
+the :extension:`DuplicateRecordFields` extension allows multiple datatypes to be
 declared using the same field names in a single module. For example, it allows
 this: ::
 
@@ -3215,7 +3318,7 @@ this: ::
 Uses of fields that are always unambiguous because they mention the constructor,
 including construction and pattern-matching, may freely use duplicated field
 names. For example, the following are permitted (just as with
-:ghc-flag:`-XDisambiguateRecordFields`): ::
+:extension:`DisambiguateRecordFields`): ::
 
     s = MkS { x = 3 }
 
@@ -3272,7 +3375,7 @@ definitions: ::
     data T = MkT { foo :: Int, bar :: Int }
     data U = MkU { bar :: Int, baz :: Int }
 
-Without :ghc-flag:`-XDuplicateRecordFields`, an update mentioning ``foo`` will always be
+Without :extension:`DuplicateRecordFields`, an update mentioning ``foo`` will always be
 ambiguous if all these definitions were in scope. When the extension is enabled,
 there are several options for disambiguating updates:
 
@@ -3311,7 +3414,7 @@ ambiguous: ::
 Import and export of record fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When :ghc-flag:`-XDuplicateRecordFields` is enabled, an ambiguous field must be exported
+When :extension:`DuplicateRecordFields` is enabled, an ambiguous field must be exported
 as part of its datatype, rather than at the top level. For example, the
 following is legal: ::
 
@@ -3330,17 +3433,14 @@ Similar restrictions apply on import.
 Record puns
 -----------
 
-.. ghc-flag:: -XNamedFieldPuns
-    :shortdesc: Enable :ref:`record puns <record-puns>`.
-    :type: dynamic
-    :reverse: -XNoNamedFieldPuns
-    :category:
+.. extension:: NamedFieldPuns
+    :shortdesc: Enable record puns.
 
     :since: 6.10.1
 
     Allow use of record puns.
 
-Record puns are enabled by the flag :ghc-flag:`-XNamedFieldPuns`.
+Record puns are enabled by the language extension :extension:`NamedFieldPuns`.
 
 When using records, it is common to write a pattern that binds a
 variable with the same name as a record field, such as: ::
@@ -3397,20 +3497,17 @@ Note that:
 Record wildcards
 ----------------
 
-.. ghc-flag:: -XRecordWildCards
-    :shortdesc: Enable :ref:`record wildcards <record-wildcards>`.
-        Implies :ghc-flag:`-XDisambiguateRecordFields`.
-    :type: dynamic
-    :reverse: -XNoRecordWildCards
-    :category:
+.. extension:: RecordWildCards
+    :shortdesc: Enable record wildcards.
+        Implies :extension:`DisambiguateRecordFields`.
 
-    :implies: :ghc-flag:`-XDisambiguateRecordFields`.
+    :implies: :extension:`DisambiguateRecordFields`.
     :since: 6.8.1
 
     Allow the use of wildcards in record construction and pattern matching.
 
-Record wildcards are enabled by the flag :ghc-flag:`-XRecordWildCards`. This
-flag implies :ghc-flag:`-XDisambiguateRecordFields`.
+Record wildcards are enabled by the language extension :extension:`RecordWildCards`. This
+exension implies :extension:`DisambiguateRecordFields`.
 
 For records with many fields, it can be tiresome to write out each field
 individually in a record pattern, as in ::
@@ -3449,11 +3546,6 @@ More details:
    refers to the nearest enclosing variables that are spelled the same
    as the omitted field names.
 
--  Record wildcards may *not* be used in record *updates*. For example
-   this is illegal: ::
-
-       f r = r { x = 3, .. }
-
 -  For both pattern and expression wildcards, the "``..``" expands to
    the missing *in-scope* record fields. Specifically the expansion of
    "``C {..}``" includes ``f`` if and only if:
@@ -3463,26 +3555,42 @@ More details:
    -  The record field ``f`` is in scope somehow (either qualified or
       unqualified).
 
-   -  In the case of expressions (but not patterns), the variable ``f``
-      is in scope unqualified, and is not imported or bound at top level.
-      For example, ``f`` can be bound by an enclosing pattern match or
-      let/where-binding.  (The motivation here is that it should be
-      easy for the reader to figure out what the "``..``" expands to.)
-
    These rules restrict record wildcards to the situations in which the
    user could have written the expanded version. For example ::
 
        module M where
          data R = R { a,b,c :: Int }
        module X where
-         import M( R(a,c) )
-         f b = R { .. }
+         import M( R(R,a,c) )
+         f b = R { .. }
 
-   The ``R{..}`` expands to ``R{M.a=a}``, omitting ``b`` since the
+   The ``R{..}`` expands to ``R{a=a}``, omitting ``b`` since the
    record field is not in scope, and omitting ``c`` since the variable
    ``c`` is not in scope (apart from the binding of the record selector
    ``c``, of course).
 
+-  When record wildcards are use in record construction, a field ``f``
+   is initialised only if ``f`` is in scope,
+   and is not imported or bound at top level.
+   For example, ``f`` can be bound by an enclosing pattern match or
+   let/where-binding. For example ::
+
+        module M where
+          import A( a )
+
+          data R = R { a,b,c,d :: Int }
+
+          c = 3 :: Int
+
+          f b = R { .. }  -- Expands to R { b = b, d = d }
+            where
+              d = b+1
+
+   Here, ``a`` is imported, and ``c`` is bound at top level, so neither
+   contribute to the expansion of the "``..``".
+   The motivation here is that it should be
+   easy for the reader to figure out what the "``..``" expands to.
+
 -  Record wildcards cannot be used (a) in a record update construct, and
    (b) for data constructors that are not declared with record fields.
    For example: ::
@@ -3675,6 +3783,79 @@ prohibited, to avoid conflicts in downstream modules.
 Extensions to the "deriving" mechanism
 ======================================
 
+Haskell 98 allows the programmer to add a deriving clause to a data type
+declaration, to generate a standard instance declaration for specified class.
+GHC extends this mechanism along several axes:
+
+* The derivation mechanism can be used separtely from the data type
+  declaration, using the `standalone deriving mechanism
+  <#stand-alone-deriving>`__.
+
+* In Haskell 98, the only derivable classes are ``Eq``,
+  ``Ord``, ``Enum``, ``Ix``, ``Bounded``, ``Read``, and ``Show``. `Various
+  language extensions <#deriving-extra>`__ extend this list.
+
+* Besides the stock approach to deriving instances by generating all method
+  definitions, GHC supports two additional deriving strategies, which can
+  derive arbitrary classes:
+
+  * `Generalised newtype deriving <#newtype-deriving>`__ for newtypes and
+  * `deriving any class <#derive-any-class>`__ using an empty instance
+    declaration.
+
+  The user can optionally declare the desired `deriving strategy
+  <#deriving-stragies>`__, especially if the compiler chooses the wrong
+  one `by default <#default-deriving-strategy>`__.
+
+.. _empty-data-deriving:
+
+Deriving instances for empty data types
+---------------------------------------
+
+.. ghc-flag:: -XEmptyDataDeriving
+    :shortdesc: Allow deriving instances of standard type classes for
+                empty data types.
+    :type: dynamic
+    :reverse: -XNoEmptyDataDeriving
+    :category:
+
+    :since: 8.4.1
+
+    Allow deriving instances of standard type classes for empty data types.
+
+One can write data types with no constructors using the
+:ghc-flag:`-XEmptyDataDecls` flag (see :ref:`nullary-types`), which is on by
+default in Haskell 2010. What is not on by default is the ability to derive
+type class instances for these types. This ability is enabled through use of
+the :ghc-flag:`-XEmptyDataDeriving` flag. For instance, this lets one write: ::
+
+    data Empty deriving (Eq, Ord, Read, Show)
+
+This would generate the following instances: ::
+
+    instance Eq Empty where
+      _ == _ = True
+
+    instance Ord Empty where
+      compare _ _ = EQ
+
+    instance Read Empty where
+      readPrec = pfail
+
+    instance Show Empty where
+      showsPrec _ x = case x of {}
+
+The :ghc-flag:`-XEmptyDataDeriving` flag is only required to enable deriving
+of these four "standard" type classes (which are mentioned in the Haskell
+Report). Other extensions to the ``deriving`` mechanism, which are explained
+below in greater detail, do not require :ghc-flag:`-XEmptyDataDeriving` to be
+used in conjunction with empty data types. These include:
+
+* :ghc-flag:`-XStandaloneDeriving` (see :ref:`stand-alone-deriving`)
+* Type classes which require their own extensions to be enabled to be derived,
+  such as :ghc-flag:`-XDeriveFunctor` (see :ref:`deriving-extra`)
+* :ghc-flag:`-XDeriveAnyClass` (see :ref:`derive-any-class`)
+
 .. _deriving-inferred:
 
 Inferred context for deriving clauses
@@ -3711,18 +3892,15 @@ mechanism <#stand-alone-deriving>`__.
 Stand-alone deriving declarations
 ---------------------------------
 
-.. ghc-flag:: -XStandaloneDeriving
-    :shortdesc: Enable :ref:`standalone deriving <stand-alone-deriving>`.
-    :type: dynamic
-    :reverse: -XNoStandaloneDeriving
-    :category:
+.. extension:: StandaloneDeriving
+    :shortdesc: Enable standalone deriving.
 
     :since: 6.8.1
 
     Allow the use of stand-alone ``deriving`` declarations.
 
 GHC allows stand-alone ``deriving`` declarations, enabled by
-:ghc-flag:`-XStandaloneDeriving`: ::
+:extension:`StandaloneDeriving`: ::
 
       data Foo a = Bar a | Baz String
 
@@ -3739,14 +3917,24 @@ number of important ways:
    module as the data type declaration. (But be aware of the dangers of
    orphan instances (:ref:`orphan-modules`).
 
--  You must supply an explicit context (in the example the context is
-   ``(Eq a)``), exactly as you would in an ordinary instance
+-  In most cases, you must supply an explicit context (in the example the
+   context is ``(Eq a)``), exactly as you would in an ordinary instance
    declaration. (In contrast, in a ``deriving`` clause attached to a
    data type declaration, the context is inferred.)
 
+   The exception to this rule is that the context of a standalone deriving
+   declaration can infer its context when a single, extra-wildcards constraint
+   is used as the context, such as in: ::
+
+         deriving instance _ => Eq (Foo a)
+
+   This is essentially the same as if you had written ``deriving Foo`` after
+   the declaration for ``data Foo a``. Using this feature requires the use of
+   :extension:`PartialTypeSignatures` (:ref:`partial-type-signatures`).
+
 -  Unlike a ``deriving`` declaration attached to a ``data`` declaration,
    the instance can be more specific than the data type (assuming you
-   also use :ghc-flag:`-XFlexibleInstances`, :ref:`instance-rules`). Consider
+   also use :extension:`FlexibleInstances`, :ref:`instance-rules`). Consider
    for example ::
 
          data Foo a = Bar a | Baz String
@@ -3789,8 +3977,8 @@ number of important ways:
    because the derived instance would generate code that uses the constructors
    behind the scenes, which would break abstraction.
 
-   The one exception to this rule is :ghc-flag:`-XDeriveAnyClass`, since
-   deriving an instance via :ghc-flag:`-XDeriveAnyClass` simply generates
+   The one exception to this rule is :extension:`DeriveAnyClass`, since
+   deriving an instance via :extension:`DeriveAnyClass` simply generates
    an empty instance declaration, which does not require the use of any
    constructors. See the `deriving any class <#derive-any-class>`__ section
    for more details.
@@ -3818,50 +4006,6 @@ ordinary deriving:
 Deriving instances of extra classes (``Data``, etc.)
 ----------------------------------------------------
 
-.. ghc-flag:: -XDeriveGeneric
-    :shortdesc: Enable :ref:`deriving for the Generic class <deriving-typeable>`.
-    :type: dynamic
-    :reverse: -XNoDeriveGeneric
-    :category:
-
-    :since: 7.2.1
-
-    Allow automatic deriving of instances for the ``Generic`` typeclass.
-
-.. ghc-flag:: -XDeriveFunctor
-    :shortdesc: Enable :ref:`deriving for the Functor class <deriving-extra>`.
-        Implied by :ghc-flag:`-XDeriveTraversable`.
-    :type: dynamic
-    :reverse: -XNoDeriveFunctor
-    :category:
-
-    :since: 7.10.1
-
-    Allow automatic deriving of instances for the ``Functor`` typeclass.
-
-.. ghc-flag:: -XDeriveFoldable
-    :shortdesc: Enable :ref:`deriving for the Foldable class <deriving-extra>`.
-        Implied by :ghc-flag:`-XDeriveTraversable`.
-    :type: dynamic
-    :reverse: -XNoDeriveFoldable
-    :category:
-
-    :since: 7.10.1
-
-    Allow automatic deriving of instances for the ``Foldable`` typeclass.
-
-.. ghc-flag:: -XDeriveTraversable
-    :shortdesc: Enable :ref:`deriving for the Traversable class <deriving-extra>`.
-        Implies :ghc-flag:`-XDeriveFunctor` and :ghc-flag:`-XDeriveFoldable`.
-    :type: dynamic
-    :reverse: -XNoDeriveTraversable
-    :category:
-
-    :implies: :ghc-flag:`-XDeriveFoldable`, :ghc-flag:`-XDeriveFunctor`
-    :since: 7.10.1
-
-    Allow automatic deriving of instances for the ``Traversable`` typeclass.
-
 Haskell 98 allows the programmer to add "``deriving( Eq, Ord )``" to a
 data type declaration, to generate a standard instance declaration for
 classes specified in the ``deriving`` clause. In Haskell 98, the only
@@ -3872,31 +4016,30 @@ classes ``Eq``, ``Ord``, ``Enum``, ``Ix``, ``Bounded``, ``Read``, and
 GHC extends this list with several more classes that may be
 automatically derived:
 
--  With :ghc-flag:`-XDeriveGeneric`, you can derive instances of the classes
+-  With :extension:`DeriveGeneric`, you can derive instances of the classes
    ``Generic`` and ``Generic1``, defined in ``GHC.Generics``. You can
    use these to define generic functions, as described in
    :ref:`generic-programming`.
 
--  With :ghc-flag:`-XDeriveFunctor`, you can derive instances of the class
-   ``Functor``, defined in ``GHC.Base``. See :ref:`deriving-functor`.
+-  With :extension:`DeriveFunctor`, you can derive instances of the class
+   ``Functor``, defined in ``GHC.Base``.
 
--  With :ghc-flag:`-XDeriveDataTypeable`, you can derive instances of the class
-   ``Data``, defined in ``Data.Data``. See :ref:`deriving-data`.
+-  With :extension:`DeriveDataTypeable`, you can derive instances of the class
+   ``Data``, defined in ``Data.Data``.
 
--  With :ghc-flag:`-XDeriveFoldable`, you can derive instances of the class
-   ``Foldable``, defined in ``Data.Foldable``. See
-   :ref:`deriving-foldable`.
+-  With :extension:`DeriveFoldable`, you can derive instances of the class
+   ``Foldable``, defined in ``Data.Foldable``.
 
--  With :ghc-flag:`-XDeriveTraversable`, you can derive instances of the class
+-  With :extension:`DeriveTraversable`, you can derive instances of the class
    ``Traversable``, defined in ``Data.Traversable``. Since the
    ``Traversable`` instance dictates the instances of ``Functor`` and
    ``Foldable``, you'll probably want to derive them too, so
-   :ghc-flag:`-XDeriveTraversable` implies :ghc-flag:`-XDeriveFunctor` and
-   :ghc-flag:`-XDeriveFoldable`. See :ref:`deriving-traversable`.
+   :extension:`DeriveTraversable` implies :extension:`DeriveFunctor` and
+   :extension:`DeriveFoldable`.
 
--  With :ghc-flag:`-XDeriveLift`, you can derive instances of the class ``Lift``,
+-  With :extension:`DeriveLift`, you can derive instances of the class ``Lift``,
    defined in the ``Language.Haskell.TH.Syntax`` module of the
-   ``template-haskell`` package. See :ref:`deriving-lift`.
+   ``template-haskell`` package.
 
 You can also use a standalone deriving declaration instead (see
 :ref:`stand-alone-deriving`).
@@ -3907,10 +4050,19 @@ mentioned in the ``deriving`` clause.
 .. _deriving-functor:
 
 Deriving ``Functor`` instances
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. extension:: DeriveFunctor
+    :shortdesc: Enable deriving for the Functor class.
+        Implied by :extension:`DeriveTraversable`.
+
+    :since: 7.10.1
+
+    Allow automatic deriving of instances for the ``Functor`` typeclass.
+
 
-With :ghc-flag:`-XDeriveFunctor`, one can derive ``Functor`` instances for data types
-of kind ``* -> *``. For example, this declaration::
+With :extension:`DeriveFunctor`, one can derive ``Functor`` instances for data types
+of kind ``Type -> Type``. For example, this declaration::
 
     data Example a = Ex a Char (Example a) (Example Char)
       deriving Functor
@@ -3920,7 +4072,7 @@ would generate the following instance: ::
     instance Functor Example where
       fmap f (Ex a1 a2 a3 a4) = Ex (f a1) a2 (fmap f a3) a4
 
-The basic algorithm for :ghc-flag:`-XDeriveFunctor` walks the arguments of each
+The basic algorithm for :extension:`DeriveFunctor` walks the arguments of each
 constructor of a data type, applying a mapping function depending on the type
 of each argument. If a plain type variable is found that is syntactically
 equivalent to the last type parameter of the data type (``a`` in the above
@@ -3945,7 +4097,7 @@ The difference involves the placement of the last type parameter, ``a``. In the
 appears as the last type argument of ``Either``. In the ``Wrong`` case,
 however, ``a`` is not the last type argument to ``Either``; rather, ``Int`` is.
 
-This distinction is important because of the way :ghc-flag:`-XDeriveFunctor` works. The
+This distinction is important because of the way :extension:`DeriveFunctor` works. The
 derived ``Functor Right`` instance would be::
 
     instance Functor Right where
@@ -3966,13 +4118,13 @@ causes the generated code to be ill-typed.
 
 As a general rule, if a data type has a derived ``Functor`` instance and its
 last type parameter occurs on the right-hand side of the data declaration, then
-either it must (1) occur bare (e.g., ``newtype Id a = a``), or (2) occur as the
+either it must (1) occur bare (e.g., ``newtype Id a = Id a``), or (2) occur as the
 last argument of a type constructor (as in ``Right`` above).
 
 There are two exceptions to this rule:
 
 #. Tuple types. When a non-unit tuple is used on the right-hand side of a data
-   declaration, :ghc-flag:`-XDeriveFunctor` treats it as a product of distinct types.
+   declaration, :extension:`DeriveFunctor` treats it as a product of distinct types.
    In other words, the following code::
 
        newtype Triple a = Triple (a, Int, [a]) deriving Functor
@@ -3984,9 +4136,9 @@ There are two exceptions to this rule:
            Triple (case a of
                         (a1, a2, a3) -> (f a1, a2, fmap f a3))
 
-   That is, :ghc-flag:`-XDeriveFunctor` pattern-matches its way into tuples and maps
+   That is, :extension:`DeriveFunctor` pattern-matches its way into tuples and maps
    over each type that constitutes the tuple. The generated code is
-   reminiscient of what would be generated from
+   reminiscent of what would be generated from
    ``data Triple a = Triple a Int [a]``, except with extra machinery to handle
    the tuple.
 
@@ -4050,11 +4202,11 @@ fail to compile:
 
 #. A data type has no type parameters (e.g., ``data Nothing = Nothing``).
 
-#. A data type's last type variable is used in a :ghc-flag:`-XDatatypeContexts`
+#. A data type's last type variable is used in a :extension:`DatatypeContexts`
    constraint (e.g., ``data Ord a => O a = O a``).
 
 #. A data type's last type variable is used in an
-   :ghc-flag:`-XExistentialQuantification` constraint, or is refined in a GADT. For
+   :extension:`ExistentialQuantification` constraint, or is refined in a GADT. For
    example, ::
 
        data T a b where
@@ -4079,7 +4231,7 @@ will produce the following instance: ::
 
 When a type has no constructors, the derived ``Functor`` instance will
 simply force the (bottom) value of the argument using
-:ghc-flag:`-XEmptyCase`. ::
+:extension:`EmptyCase`. ::
 
     data V a deriving Functor
     type role V nominal
@@ -4092,10 +4244,18 @@ will produce
 .. _deriving-foldable:
 
 Deriving ``Foldable`` instances
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. extension:: DeriveFoldable
+    :shortdesc: Enable deriving for the Foldable class.
+        Implied by :extension:`DeriveTraversable`.
+
+    :since: 7.10.1
 
-With :ghc-flag:`-XDeriveFoldable`, one can derive ``Foldable`` instances for data types
-of kind ``* -> *``. For example, this declaration::
+    Allow automatic deriving of instances for the ``Foldable`` typeclass.
+
+With :extension:`DeriveFoldable`, one can derive ``Foldable`` instances for data types
+of kind ``Type -> Type``. For example, this declaration::
 
     data Example a = Ex a Char (Example a) (Example Char)
       deriving Foldable
@@ -4106,15 +4266,15 @@ would generate the following instance::
       foldr f z (Ex a1 a2 a3 a4) = f a1 (foldr f z a3)
       foldMap f (Ex a1 a2 a3 a4) = mappend (f a1) (foldMap f a3)
 
-The algorithm for :ghc-flag:`-XDeriveFoldable` is adapted from the
-:ghc-flag:`-XDeriveFunctor` algorithm, but it generates definitions for
+The algorithm for :extension:`DeriveFoldable` is adapted from the
+:extension:`DeriveFunctor` algorithm, but it generates definitions for
 ``foldMap``, ``foldr``, and ``null`` instead of ``fmap``. In addition,
-:ghc-flag:`-XDeriveFoldable` filters out all constructor arguments on the RHS
+:extension:`DeriveFoldable` filters out all constructor arguments on the RHS
 expression whose types do not mention the last type parameter, since those
 arguments do not need to be folded over.
 
 When the type parameter has a phantom role (see :ref:`roles`),
-:ghc-flag:`-XDeriveFoldable` derives a trivial instance. For example, this
+:extension:`DeriveFoldable` derives a trivial instance. For example, this
 declaration: ::
 
     data Phantom a = Z | S (Phantom a)
@@ -4124,7 +4284,7 @@ will generate the following instance. ::
     instance Foldable Phantom where
       foldMap _ _ = mempty
 
-Similarly, when the type has no constructors, :ghc-flag:`-XDeriveFoldable` will
+Similarly, when the type has no constructors, :extension:`DeriveFoldable` will
 derive a trivial instance: ::
 
     data V a deriving Foldable
@@ -4138,14 +4298,14 @@ will generate the following. ::
 Here are the differences between the generated code for ``Functor`` and
 ``Foldable``:
 
-#. When a bare type variable ``a`` is encountered, :ghc-flag:`-XDeriveFunctor`
-would generate ``f a`` for an ``fmap`` definition. :ghc-flag:`-XDeriveFoldable`
+#. When a bare type variable ``a`` is encountered, :extension:`DeriveFunctor`
+would generate ``f a`` for an ``fmap`` definition. :extension:`DeriveFoldable`
 would generate ``f a z`` for ``foldr``, ``f a`` for ``foldMap``, and ``False``
 for ``null``.
 
 #. When a type that is not syntactically equivalent to ``a``, but which does
-   contain ``a``, is encountered, :ghc-flag:`-XDeriveFunctor` recursively calls
-   ``fmap`` on it. Similarly, :ghc-flag:`-XDeriveFoldable` would recursively call
+   contain ``a``, is encountered, :extension:`DeriveFunctor` recursively calls
+   ``fmap`` on it. Similarly, :extension:`DeriveFoldable` would recursively call
    ``foldr`` and ``foldMap``. Depending on the context, ``null`` may recursively
    call ``null`` or ``all null``. For example, given ::
 
@@ -4159,8 +4319,8 @@ for ``null``.
        null (G x) = null x
        null (H x) = all null x
 
-#. :ghc-flag:`-XDeriveFunctor` puts everything back together again at the end by
-   invoking the constructor. :ghc-flag:`-XDeriveFoldable`, however, builds up a value
+#. :extension:`DeriveFunctor` puts everything back together again at the end by
+   invoking the constructor. :extension:`DeriveFoldable`, however, builds up a value
    of some type. For ``foldr``, this is accomplished by chaining applications
    of ``f`` and recursive ``foldr`` calls on the state value ``z``. For
    ``foldMap``, this happens by combining all values with ``mappend``. For ``null``,
@@ -4214,7 +4374,7 @@ There are some other differences regarding what data types can have derived
    polymorphic types that are syntactically equivalent to the last type
    parameter. In particular:
 
-  -  We don't fold over the arguments of ``E1`` or ``E4`` beacause even though
+  -  We don't fold over the arguments of ``E1`` or ``E4`` because even though
      ``(a ~ Int)``, ``Int`` is not syntactically equivalent to ``a``.
 
   -  We don't fold over the argument of ``E3`` because ``a`` is not universally
@@ -4224,10 +4384,20 @@ There are some other differences regarding what data types can have derived
 .. _deriving-traversable:
 
 Deriving ``Traversable`` instances
-----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-With :ghc-flag:`-XDeriveTraversable`, one can derive ``Traversable`` instances for data
-types of kind ``* -> *``. For example, this declaration::
+
+.. extension:: DeriveTraversable
+    :shortdesc: Enable deriving for the Traversable class.
+        Implies :extension:`DeriveFunctor` and :extension:`DeriveFoldable`.
+
+    :implies: :extension:`DeriveFoldable`, :extension:`DeriveFunctor`
+    :since: 7.10.1
+
+    Allow automatic deriving of instances for the ``Traversable`` typeclass.
+
+With :extension:`DeriveTraversable`, one can derive ``Traversable`` instances for data
+types of kind ``Type -> Type``. For example, this declaration::
 
     data Example a = Ex a Char (Example a) (Example Char)
       deriving (Functor, Foldable, Traversable)
@@ -4238,15 +4408,15 @@ would generate the following ``Traversable`` instance::
       traverse f (Ex a1 a2 a3 a4)
         = fmap (\b1 b3 -> Ex b1 a2 b3 a4) (f a1) <*> traverse f a3
 
-The algorithm for :ghc-flag:`-XDeriveTraversable` is adapted from the
-:ghc-flag:`-XDeriveFunctor` algorithm, but it generates a definition for ``traverse``
-instead of ``fmap``. In addition, :ghc-flag:`-XDeriveTraversable` filters out
+The algorithm for :extension:`DeriveTraversable` is adapted from the
+:extension:`DeriveFunctor` algorithm, but it generates a definition for ``traverse``
+instead of ``fmap``. In addition, :extension:`DeriveTraversable` filters out
 all constructor arguments on the RHS expression whose types do not mention the
 last type parameter, since those arguments do not produce any effects in a
 traversal.
 
 When the type parameter has a phantom role (see :ref:`roles`),
-:ghc-flag:`-XDeriveTraversable` coerces its argument. For example, this
+:extension:`DeriveTraversable` coerces its argument. For example, this
 declaration::
 
     data Phantom a = Z | S (Phantom a) deriving Traversable
@@ -4256,13 +4426,13 @@ will generate the following instance::
     instance Traversable Phantom where
       traverse _ z = pure (coerce z)
 
-When the type has no constructors, :ghc-flag:`-XDeriveTraversable` will
+When the type has no constructors, :extension:`DeriveTraversable` will
 derive the laziest instance it can. ::
 
     data V a deriving Traversable
     type role V nominal
 
-will generate the following, using :ghc-flag:`-XEmptyCase`: ::
+will generate the following, using :extension:`EmptyCase`: ::
 
     instance Traversable V where
       traverse _ z = pure (case z of)
@@ -4270,38 +4440,35 @@ will generate the following, using :ghc-flag:`-XEmptyCase`: ::
 Here are the differences between the generated code in each
 extension:
 
-#. When a bare type variable ``a`` is encountered, both :ghc-flag:`-XDeriveFunctor` and
-   :ghc-flag:`-XDeriveTraversable` would generate ``f a`` for an ``fmap`` and
+#. When a bare type variable ``a`` is encountered, both :extension:`DeriveFunctor` and
+   :extension:`DeriveTraversable` would generate ``f a`` for an ``fmap`` and
    ``traverse`` definition, respectively.
 
 #. When a type that is not syntactically equivalent to ``a``, but which does
-   contain ``a``, is encountered, :ghc-flag:`-XDeriveFunctor` recursively calls
-   ``fmap`` on it. Similarly, :ghc-flag:`-XDeriveTraversable` would recursively call
+   contain ``a``, is encountered, :extension:`DeriveFunctor` recursively calls
+   ``fmap`` on it. Similarly, :extension:`DeriveTraversable` would recursively call
    ``traverse``.
 
-#. :ghc-flag:`-XDeriveFunctor` puts everything back together again at the end by
-   invoking the constructor. :ghc-flag:`-XDeriveTraversable` does something similar,
+#. :extension:`DeriveFunctor` puts everything back together again at the end by
+   invoking the constructor. :extension:`DeriveTraversable` does something similar,
    but it works in an ``Applicative`` context by chaining everything together
    with ``(<*>)``.
 
-Unlike :ghc-flag:`-XDeriveFunctor`, :ghc-flag:`-XDeriveTraversable` cannot be used on data
+Unlike :extension:`DeriveFunctor`, :extension:`DeriveTraversable` cannot be used on data
 types containing a function type on the right-hand side.
 
-For a full specification of the algorithms used in :ghc-flag:`-XDeriveFunctor`,
-:ghc-flag:`-XDeriveFoldable`, and :ghc-flag:`-XDeriveTraversable`, see
+For a full specification of the algorithms used in :extension:`DeriveFunctor`,
+:extension:`DeriveFoldable`, and :extension:`DeriveTraversable`, see
 :ghc-wiki:`this wiki page <Commentary/Compiler/DeriveFunctor>`.
 
 .. _deriving-data:
 
 Deriving ``Data`` instances
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XDeriveDataTypeable
-    :shortdesc: Enable ``deriving`` for the :ref:`Data class
-        <deriving-typeable>`. Implied by :ghc-flag:`-XAutoDeriveTypeable`.
-    :type: dynamic
-    :reverse: -XNoDeriveDataTypeable
-    :category:
+.. extension:: DeriveDataTypeable
+    :shortdesc: Enable deriving for the Data class.
+       Implied by (deprecated) :extension:`AutoDeriveTypeable`.
 
     :since: 6.8.1
 
@@ -4310,7 +4477,7 @@ Deriving ``Data`` instances
 .. _deriving-typeable:
 
 Deriving ``Typeable`` instances
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The class ``Typeable`` is very special:
 
@@ -4322,7 +4489,7 @@ The class ``Typeable`` is very special:
    bogus instances.
 
 -  Derived instances of ``Typeable`` may be declared if the
-   :ghc-flag:`-XDeriveDataTypeable` extension is enabled, but they are ignored,
+   :extension:`DeriveDataTypeable` extension is enabled, but they are ignored,
    and they may be reported as an error in a later version of the compiler.
 
 -  The rules for solving \`Typeable\` constraints are as follows:
@@ -4338,30 +4505,25 @@ The class ``Typeable`` is very special:
       applied to all of its kinds parameters, and these kinds need to be
       concrete (i.e., they cannot mention kind variables).
 
-   -  ::
+   -  A type variable applied to some types::
 
-          A type variable applied to some types.
           instance (Typeable f, Typeable t1, .., Typeable t_n) =>
             Typeable (f t1 .. t_n)
 
-   -  ::
+   -  A concrete type literal.::
 
-          A concrete type literal.
           instance Typeable 0       -- Type natural literals
           instance Typeable "Hello" -- Type-level symbols
 
 .. _deriving-lift:
 
 Deriving ``Lift`` instances
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XDeriveLift
-    :shortdesc: Enable :ref:`deriving for the Lift class <deriving-lift>`
-    :type: dynamic
-    :reverse: -XNoDeriveLift
-    :category:
+.. extension:: DeriveLift
+    :shortdesc: Enable deriving for the Lift class
 
-    :since: 7.2.1
+    :since: 8.0.1
 
     Enable automatic deriving of instances for the ``Lift`` typeclass for
     Template Haskell.
@@ -4410,7 +4572,7 @@ Here is an example of how one can derive ``Lift``:
     fooExp :: Lift a => Foo a -> Q Exp
     fooExp f = [| f |]
 
-:ghc-flag:`-XDeriveLift` also works for certain unboxed types (``Addr#``, ``Char#``,
+:extension:`DeriveLift` also works for certain unboxed types (``Addr#``, ``Char#``,
 ``Double#``, ``Float#``, ``Int#``, and ``Word#``):
 
 ::
@@ -4439,14 +4601,11 @@ Here is an example of how one can derive ``Lift``:
 Generalised derived instances for newtypes
 ------------------------------------------
 
-.. ghc-flag:: -XGeneralisedNewtypeDeriving
-              -XGeneralizedNewtypeDeriving
-    :shortdesc: Enable :ref:`newtype deriving <newtype-deriving>`.
-    :type: dynamic
-    :reverse: -XNoGeneralizedNewtypeDeriving
-    :category:
+.. extension:: GeneralisedNewtypeDeriving
+               GeneralizedNewtypeDeriving
+    :shortdesc: Enable newtype deriving.
 
-    :since: 6.8.1
+    :since: 6.8.1. British spelling since 8.6.1.
 
     Enable GHC's cunning generalised deriving mechanism for ``newtype``\s
 
@@ -4470,13 +4629,16 @@ It is particularly galling that, since the constructor doesn't appear at
 run-time, this instance declaration defines a dictionary which is
 *wholly equivalent* to the ``Int`` dictionary, only slower!
 
+:extension:`DerivingVia` (see :ref:`deriving-via`) is a generalization of
+this idea.
+
 .. _generalized-newtype-deriving:
 
 Generalising the deriving clause
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-GHC now permits such instances to be derived instead, using the flag
-:ghc-flag:`-XGeneralizedNewtypeDeriving`, so one can write ::
+GHC now permits such instances to be derived instead, using the extension
+:extension:`GeneralizedNewtypeDeriving`, so one can write ::
 
       newtype Dollars = Dollars { getDollars :: Int } deriving (Eq,Show,Num)
 
@@ -4522,7 +4684,7 @@ In this case the derived instance declaration is of the form ::
       instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)
 
 Notice that, since ``Monad`` is a constructor class, the instance is a
-*partial application* of the new type, not the entire left hand side. We
+*partial application* of the newtype, not the entire left hand side. We
 can imagine that the type declaration is "eta-converted" to generate the
 context of the instance declaration.
 
@@ -4550,6 +4712,43 @@ declarations are treated uniformly (and implemented just by reusing the
 dictionary for the representation type), *except* ``Show`` and ``Read``,
 which really behave differently for the newtype and its representation.
 
+.. note::
+
+    It is sometimes necessary to enable additional language extensions when
+    deriving instances via :extension:`GeneralizedNewtypeDeriving`. For instance,
+    consider a simple class and instance using :extension:`UnboxedTuples`
+    syntax: ::
+
+        {-# LANGUAGE UnboxedTuples #-}
+
+        module Lib where
+
+        class AClass a where
+          aMethod :: a -> (# Int, a #)
+
+        instance AClass Int where
+          aMethod x = (# x, x #)
+
+    The following will fail with an "Illegal unboxed tuple" error, since the
+    derived instance produced by the compiler makes use of unboxed tuple syntax,
+    ::
+
+        {-# LANGUAGE GeneralizedNewtypeDeriving #-}
+
+        import Lib
+
+        newtype Int' = Int' Int
+                     deriving (AClass)
+
+    However, enabling the :extension:`UnboxedTuples` extension allows the module
+    to compile. Similar errors may occur with a variety of extensions,
+    including:
+
+      * :extension:`UnboxedTuples`
+      * :extension:`PolyKinds`
+      * :extension:`MultiParamTypeClasses`
+      * :extension:`FlexibleContexts`
+
 .. _precise-gnd-specification:
 
 A more precise specification
@@ -4582,7 +4781,8 @@ where
 -  ``C`` is not ``Read``, ``Show``, ``Typeable``, or ``Data``. These
    classes should not "look through" the type or its constructor. You
    can still derive these classes for a newtype, but it happens in the
-   usual way, not via this new mechanism.
+   usual way, not via this new mechanism. Confer with
+   :ref:`default-deriving-strategy`.
 
 -  It is safe to coerce each of the methods of ``C``. That is, the
    missing last argument to ``C`` is not used at a nominal role in any
@@ -4637,7 +4837,7 @@ whether the stock method is used or the one described here.)
 Associated type families
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-:ghc-flag:`-XGeneralizedNewtypeDeriving` also works for some type classes with
+:extension:`GeneralizedNewtypeDeriving` also works for some type classes with
 associated type families. Here is an example: ::
 
       class HasRing a where
@@ -4686,7 +4886,7 @@ then you can derive a ``C c_1 c_2 ... c_(m-1)`` instance for
 
   Now we're stuck, since we have no way to refer to ``a`` on the right-hand
   side of the ``B`` family instance, so this instance doesn't really make sense
-  in a :ghc-flag:`-XGeneralizedNewtypeDeriving` setting.
+  in a :extension:`GeneralizedNewtypeDeriving` setting.
 
 - ``C`` does not have any associated data families (only type families). To
   see why data families are forbidden, imagine the following scenario: ::
@@ -4723,7 +4923,7 @@ redundant, so GHC will instead generate
 ``instance C c_1 c_2 ... c_(m-1) (N n_1 n_2 ... n_q)``.
 
 Beware that in some cases, you may need to enable the
-:ghc-flag:`-XUndecidableInstances` extension in order to use this feature.
+:extension:`UndecidableInstances` extension in order to use this feature.
 Here's a pathological case that illustrates why this might happen: ::
 
       class C a where
@@ -4739,7 +4939,7 @@ This will generate the derived instance: ::
 
 Here, it is evident that attempting to use the type ``T Loop`` will throw the
 typechecker into an infinite loop, as its definition recurses endlessly. In
-other cases, you might need to enable :ghc-flag:`-XUndecidableInstances` even
+other cases, you might need to enable :extension:`UndecidableInstances` even
 if the generated code won't put the typechecker into a loop. For example: ::
 
       instance C Int where
@@ -4755,26 +4955,28 @@ This will generate the derived instance: ::
 
 Although typechecking ``T MyInt`` will terminate, GHC's termination checker
 isn't sophisticated enough to determine this, so you'll need to enable
-:ghc-flag:`-XUndecidableInstances` in order to use this derived instance. If
+:extension:`UndecidableInstances` in order to use this derived instance. If
 you do go down this route, make sure you can convince yourself that all of
 the type family instances you're deriving will eventually terminate if used!
 
+Note that :extension:`DerivingVia` (see :ref:`deriving-via`) uses essentially
+the same specification to derive instances of associated type families as well
+(except that it uses the ``via`` type instead of the underlying ``rep-type``
+of a newtype).
+
 .. _derive-any-class:
 
 Deriving any other class
 ------------------------
 
-.. ghc-flag:: -XDeriveAnyClass
-    :shortdesc: Enable :ref:`deriving for any class <derive-any-class>`.
-    :type: dynamic
-    :reverse: -XNoDeriveAnyClass
-    :category:
+.. extension:: DeriveAnyClass
+    :shortdesc: Enable deriving for any class.
 
     :since: 7.10.1
 
     Allow use of any typeclass in ``deriving`` clauses.
 
-With :ghc-flag:`-XDeriveAnyClass` you can derive any other class. The compiler
+With :extension:`DeriveAnyClass` you can derive any other class. The compiler
 will simply generate an instance declaration with no explicitly-defined
 methods.
 This is
@@ -4793,7 +4995,7 @@ pretty strings: ::
       sPpr = show
 
 If a user does not provide a manual implementation for ``sPpr``, then it will
-default to ``show``. Now we can leverage the :ghc-flag:`-XDeriveAnyClass` extension to
+default to ``show``. Now we can leverage the :extension:`DeriveAnyClass` extension to
 easily implement a ``SPretty`` instance for a new data type: ::
 
     data Foo = Foo deriving (Show, SPretty)
@@ -4804,14 +5006,14 @@ The above code is equivalent to: ::
     instance SPretty Foo
 
 That is, an ``SPretty Foo`` instance will be created with empty implementations
-for all methods. Since we are using :ghc-flag:`-XDefaultSignatures` in this example, a
+for all methods. Since we are using :extension:`DefaultSignatures` in this example, a
 default implementation of ``sPpr`` is filled in automatically.
 
 Note the following details
 
 - In case you try to derive some
-  class on a newtype, and :ghc-flag:`-XGeneralizedNewtypeDeriving` is also on,
-  :ghc-flag:`-XDeriveAnyClass` takes precedence.
+  class on a newtype, and :extension:`GeneralizedNewtypeDeriving` is also on,
+  :extension:`DeriveAnyClass` takes precedence.
 
 - The instance context is determined by the type signatures of the derived
   class's methods. For instance, if the class is: ::
@@ -4825,7 +5027,7 @@ Note the following details
       default baz :: Ord a => a -> a -> Bool
       baz x y = compare x y == EQ
 
-  And you attempt to derive it using :ghc-flag:`-XDeriveAnyClass`: ::
+  And you attempt to derive it using :extension:`DeriveAnyClass`: ::
 
     instance Eq   a => Eq   (Option a) where ...
     instance Ord  a => Ord  (Option a) where ...
@@ -4879,7 +5081,7 @@ Note the following details
 
     instance HigherEq Option
 
-- :ghc-flag:`-XDeriveAnyClass` can be used with partially applied classes,
+- :extension:`DeriveAnyClass` can be used with partially applied classes,
   such as ::
 
     data T a = MKT a deriving( D Int )
@@ -4888,7 +5090,7 @@ Note the following details
 
     instance D Int a => D Int (T a) where {}
 
-- :ghc-flag:`-XDeriveAnyClass` can be used to fill in default instances for
+- :extension:`DeriveAnyClass` can be used to fill in default instances for
   associated type families: ::
 
     {-# LANGUAGE DeriveAnyClass, TypeFamilies #-}
@@ -4914,11 +5116,8 @@ Note the following details
 Deriving strategies
 -------------------
 
-.. ghc-flag:: -XDerivingStrategies
-    :shortdesc: Enables :ref:`deriving strategies <deriving-strategies>`.
-    :type: dynamic
-    :reverse: -XNoDerivingStrategies
-    :category:
+.. extension:: DerivingStrategies
+    :shortdesc: Enables deriving strategies.
 
     :since: 8.2.1
 
@@ -4926,8 +5125,8 @@ Deriving strategies
 
 In most scenarios, every ``deriving`` statement generates a typeclass instance
 in an unambiguous fashion. There is a corner case, however, where
-simultaneously enabling both the :ghc-flag:`-XGeneralizedNewtypeDeriving` and
-:ghc-flag:`-XDeriveAnyClass` extensions can make deriving become ambiguous.
+simultaneously enabling both the :extension:`GeneralizedNewtypeDeriving` and
+:extension:`DeriveAnyClass` extensions can make deriving become ambiguous.
 Consider the following example ::
 
     {-# LANGUAGE DeriveAnyClass, GeneralizedNewtypeDeriving #-}
@@ -4941,7 +5140,7 @@ to use both language extensions in a single module.
 
 To make this more robust, GHC has a notion of deriving strategies, which allow
 the user to explicitly request which approach to use when deriving an instance.
-To enable this feature, one must enable the :ghc-flag:`-XDerivingStrategies`
+To enable this feature, one must enable the :extension:`DerivingStrategies`
 language extension. A deriving strategy can be specified in a deriving
 clause ::
 
@@ -4952,7 +5151,7 @@ Or in a standalone deriving declaration ::
 
     deriving anyclass instance C Foo
 
-:ghc-flag:`-XDerivingStrategies` also allows the use of multiple deriving
+:extension:`DerivingStrategies` also allows the use of multiple deriving
 clauses per data declaration so that a user can derive some instance with
 one deriving strategy and other instances with another deriving strategy.
 For example ::
@@ -4968,33 +5167,173 @@ Currently, the deriving strategies are:
 - ``stock``: Have GHC implement a "standard" instance for a data type,
   if possible (e.g., ``Eq``, ``Ord``, ``Generic``, ``Data``, ``Functor``, etc.)
 
-- ``anyclass``: Use :ghc-flag:`-XDeriveAnyClass`
+- ``anyclass``: Use :extension:`DeriveAnyClass` (see :ref:`derive-any-class`)
+
+- ``newtype``: Use :extension:`GeneralizedNewtypeDeriving`
+               (see :ref:`newtype-deriving`)
+
+- ``via``: Use :extension:`DerivingVia` (see :ref:`deriving-via`)
+
+.. _default-deriving-strategy:
+
+Default deriving strategy
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If an explicit deriving strategy is not given, multiple strategies may apply.
+In that case, GHC chooses the strategy as follows:
+
+1. Stock type classes, i.e. those specified in the report and those enabled by
+   `language extensions <#deriving-extra>`__, are derived using the ``stock``
+   strategy, with the following exception:
+
+   * For newtypes, ``Eq``, ``Ord``, ``Ix`` and ``Bounded`` are always derived
+     using the ``newtype`` strategy, even without
+     ``GeneralizedNewtypeDeriving`` enabled. (There should be no observable
+     difference to instances derived using the stock strategy.)
+
+   * Also for newtypes, ``Functor``, ``Foldable`` and ``Enum`` are derived
+     using the ``newtype`` strategy if ``GeneralizedNewtypeDeriving`` is
+     enabled and the derivation succeeds.
+
+2. For other any type class:
+
+   1. When ``DeriveAnyClass`` is enabled, use ``anyclass``.
 
-- ``newtype``: Use :ghc-flag:`-XGeneralizedNewtypeDeriving`
+   2. When ``GeneralizedNewtypeDeriving`` is enabled and we are deriving for a
+      newtype, then use ``newytype``.
 
-If an explicit deriving strategy is not given, GHC has an algorithm for
-determining how it will actually derive an instance. For brevity, the algorithm
-is omitted here. You can read the full algorithm on the
-:ghc-wiki:`GHC Wiki <Commentary/Compiler/DerivingStrategies>`.
+   If both rules apply to a deriving clause, then ``anyclass`` is used and the
+   user is warned about the ambiguity. The warning can be avoided by explicitly
+   stating the desired deriving strategy.
+
+.. _deriving-via:
+
+Deriving via
+------------
+
+.. extension:: DerivingVia
+    :shortdesc: Enable deriving instances ``via`` types of the same runtime
+        representation.
+        Implies :extension:`DerivingStrategies`.
+
+    :implies: :extension:`DerivingStrategies`
+
+    :since: 8.6.1
+
+This allows ``deriving`` a class instance for a type by specifying
+another type of equal runtime representation (such that there exists a
+``Coercible`` instance between the two: see :ref:`coercible`) that is
+already an instance of the that class.
+
+:extension:`DerivingVia` is indicated by the use of the ``via``
+deriving strategy. ``via`` requires specifying another type (the ``via`` type)
+to ``coerce`` through. For example, this code: ::
+
+    {-# LANGUAGE DerivingVia #-}
+
+    import Numeric
+
+    newtype Hex a = Hex a
+
+    instance (Integral a, Show a) => Show (Hex a) where
+      show (Hex a) = "0x" ++ showHex a ""
+
+    newtype Unicode = U Int
+      deriving Show
+        via (Hex Int)
+
+    -- >>> euroSign
+    -- 0x20ac
+    euroSign :: Unicode
+    euroSign = U 0x20ac
+
+Generates the following instance ::
+
+    instance Show Unicode where
+      show :: Unicode -> String
+      show = Data.Coerce.coerce
+        @(Hex Int -> String)
+        @(Unicode -> String)
+        show
+
+This extension generalizes :extension:`GeneralizedNewtypeDeriving`. To
+derive ``Num Unicode`` with GND (``deriving newtype Num``) it must
+reuse the ``Num Int`` instance. With ``DerivingVia``, we can explicitly
+specify the representation type ``Int``: ::
+
+    newtype Unicode = U Int
+      deriving Num
+        via Int
+
+      deriving Show
+        via (Hex Int)
+
+    euroSign :: Unicode
+    euroSign = 0x20ac
+
+Code duplication is common in instance declarations. A familiar
+pattern is lifting operations over an ``Applicative`` functor.
+Instead of having catch-all instances for ``f a`` which overlap
+with all other such instances, like so: ::
+
+    instance (Applicative f, Semigroup a) => Semigroup (f a) ..
+    instance (Applicative f, Monoid    a) => Monoid    (f a) ..
+
+We can instead create a newtype ``App``
+(where ``App f a`` and ``f a`` are represented the same in memory)
+and use :extension:`DerivingVia` to explicitly enable uses of this
+pattern: ::
+
+    {-# LANGUAGE DerivingVia, DeriveFunctor, GeneralizedNewtypeDeriving #-}
+
+    import Control.Applicative
+
+    newtype App f a = App (f a) deriving newtype (Functor, Applicative)
+
+    instance (Applicative f, Semigroup a) => Semigroup (App f a) where
+      (<>) = liftA2 (<>)
+
+    instance (Applicative f, Monoid a) => Monoid (App f a) where
+      mempty = pure mempty
+
+    data Pair a = MkPair a a
+      deriving stock
+        Functor
+
+      deriving (Semigroup, Monoid)
+        via (App Pair a)
+
+    instance Applicative Pair where
+      pure a = MkPair a a
+
+      MkPair f g <*> MkPair a b = MkPair (f a) (g b)
+
+Note that the ``via`` type does not have to be a ``newtype``.
+The only restriction is that it is coercible with the
+original data type. This means there can be arbitrary nesting of newtypes,
+as in the following example: ::
+
+    newtype Kleisli m a b = (a -> m b)
+      deriving (Semigroup, Monoid)
+        via (a -> App m b)
+
+Here we make use of the ``Monoid ((->) a)`` instance.
 
 .. _pattern-synonyms:
 
 Pattern synonyms
 ================
 
-.. ghc-flag:: -XPatternSynonyms
-    :shortdesc: Enable :ref:`pattern synonyms <pattern-synonyms>`.
-    :type: dynamic
-    :reverse: -XNoPatternSynonyms
-    :category:
+.. extension:: PatternSynonyms
+    :shortdesc: Enable pattern synonyms.
 
     :since: 7.8.1
 
     Allow the definition of pattern synonyms.
 
-Pattern synonyms are enabled by the flag :ghc-flag:`-XPatternSynonyms`, which is
+Pattern synonyms are enabled by the language extension :extension:`PatternSynonyms`, which is
 required for defining them, but *not* for using them. More information and
-examples of view patterns can be found on the `Wiki page <PatternSynonyms>`.
+examples of pattern synonyms can be found on the :ghc-wiki:`Wiki page <PatternSynonyms>`.
 
 Pattern synonyms enable giving names to parametrized pattern schemes.
 They can also be thought of as abstract constructors that don't have a
@@ -5103,7 +5442,7 @@ synonym: ::
 
       pattern StrictJust a = Just !a
 
-This is illegal because the use of :ghc-flag:`-XBangPatterns` on the right-hand
+This is illegal because the use of :extension:`BangPatterns` on the right-hand
 sides prevents it from being a well formed expression. However, constructing a
 strict pattern synonym is quite possible with an explicitly bidirectional
 pattern synonym: ::
@@ -5111,6 +5450,37 @@ pattern synonym: ::
       pattern StrictJust a <- Just !a where
         StrictJust !a = Just a
 
+Constructing an explicitly bidirectional pattern synonym also:
+
+- can create different data constructors from the underlying data type,
+  not just the one appearing in the pattern match;
+
+- can call any functions or conditional logic, especially validation,
+  of course providing it constructs a result of the right type;
+
+- can use guards on the lhs of the ``=``;
+
+- can have multiple equations.
+
+For example: ::
+
+      data PosNeg = Pos Int | Neg Int
+      pattern Smarter{ nonneg } <- Pos nonneg  where
+        Smarter x = if x >= 0 then (Pos x) else (Neg x)
+
+Or using guards: ::
+
+      pattern Smarter{ nonneg } <- Pos nonneg  where
+        Smarter x | x >= 0    = (Pos x)
+                  | otherwise = (Neg x)
+
+There is an extensive Haskell folk art of `smart constructors
+<https://wiki.haskell.org/Smart_constructor>`_,
+essentially functions that wrap validation around a constructor,
+and avoid exposing its representation.
+The downside is that the underlying constructor can't be used as a matcher.
+Pattern synonyms can be used as genuinely smart constructors, for both validation and matching.
+
 The table below summarises where each kind of pattern synonym can be used.
 
 +---------------+----------------+---------------+---------------------------+
@@ -5184,7 +5554,7 @@ the syntax for bidirectional pattern synonyms is: ::
 and the syntax for explicitly bidirectional pattern synonyms is: ::
 
       pattern pat_lhs <- pat where
-        pat_lhs = expr
+        pat_lhs = expr                      -- lhs restricted, see below
 
 We can define either prefix, infix or record pattern synonyms by modifying
 the form of `pat_lhs`. The syntax for these is as follows:
@@ -5198,6 +5568,9 @@ Infix   ``arg1 `Name` arg2``
 Record  ``Name{arg1,arg2,...,argn}``
 ======= ============================
 
+The `pat_lhs` for explicitly bidirectional construction cannot use Record syntax.
+(Because the rhs *expr* might be constructing different data constructors.)
+It can use guards with multiple equations.
 
 Pattern synonym declarations can only occur in the top level of a
 module. In particular, they are not allowed as local definitions.
@@ -5332,6 +5705,8 @@ Note also the following points
 
      P :: () => CProv => t1 -> t2 -> .. -> tN -> t
 
+-  The GHCi :ghci-cmd:`:info` command shows pattern types in this format.
+
 -  You may specify an explicit *pattern signature*, as we did for
    ``ExNumPat`` above, to specify the type of a pattern, just as you can
    for a function. As usual, the type signature can be less polymorphic
@@ -5348,7 +5723,21 @@ Note also the following points
          pattern Left' x  = Left x
          pattern Right' x = Right x
 
--  The GHCi :ghci-cmd:`:info` command shows pattern types in this format.
+-  The rules for lexically-scoped type variables (see
+   :ref:`scoped-type-variables`) apply to pattern-synonym signatures.
+   As those rules specify, only the type variables from an explicit,
+   syntactically-visible outer `forall` (the universals) scope over
+   the definition of the pattern synonym; the existentials, bound by
+   the inner forall, do not.  For example ::
+
+         data T a where
+            MkT :: Bool -> b -> (b->Int) -> a -> T a
+
+         pattern P :: forall a. forall b. b -> (b->Int) -> a -> T a
+         pattern P x y v <- MkT True x y (v::a)
+
+   Here the universal type variable `a` scopes over the definition of `P`,
+   but the existential `b` does not.  (c.f. discussion on Trac #14998.)
 
 -  For a bidirectional pattern synonym, a use of the pattern synonym as
    an expression has the type
@@ -5409,6 +5798,24 @@ Matching of pattern synonyms
 
 A pattern synonym occurrence in a pattern is evaluated by first matching
 against the pattern synonym itself, and then on the argument patterns.
+
+More precisely, the semantics of pattern matching is given in
+`Section 3.17 of the Haskell 2010 report <https://www.haskell.org/onlinereport/haskell2010/haskellch3.html#x8-580003.17>`__.   To the informal semantics in Section 3.17.2 we add this extra rule:
+
+* If the pattern is a constructor pattern ``(P p1 ... pn)``, where ``P`` is
+  a pattern synonym defined by ``P x1 ... xn = p`` or ``P x1 ... xn <- p``, then:
+
+  (a) Match the value ``v`` against ``p``. If this match fails or diverges,
+      so does the whole (pattern synonym) match.   Otherwise the match
+      against ``p`` must bind the variables ``x1 ... xn``; let them be bound to values ``v1 ... vn``.
+
+  (b) Match ``v1`` against ``p1``, ``v2`` against ``p2`` and so on.
+      If any of these matches fail or diverge, so does the whole match.
+
+  (c) If all the matches against the ``pi`` succeed, the match succeeds,
+      binding the variables bound by the ``pi`` . (The ``xi`` are not
+      bound; they remain local to the pattern synonym declaration.)
+
 For example, in the following program, ``f`` and ``f'`` are equivalent: ::
 
     pattern Pair x y <- [x, y]
@@ -5451,21 +5858,17 @@ space <http://research.microsoft.com/~simonpj/Papers/type-class-design-space/>`_
 Multi-parameter type classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XMultiParamTypeClasses
-    :shortdesc: Enable :ref:`multi parameter type classes
-        <multi-param-type-classes>`. Implied by
-        :ghc-flag:`-XFunctionalDependencies`.
-    :type: dynamic
-    :reverse: -XNoMultiParamTypeClasses
-    :category:
+.. extension:: MultiParamTypeClasses
+    :shortdesc: Enable multi parameter type classes.
+         Implied by :extension:`FunctionalDependencies`.
 
-    :implies: :ghc-flag:`-XConstrainedClassMethods`
+    :implies: :extension:`ConstrainedClassMethods`
     :since: 6.8.1
 
     Allow the definition of typeclasses with more than one parameter.
 
-Multi-parameter type classes are permitted, with flag
-:ghc-flag:`-XMultiParamTypeClasses`. For example: ::
+Multi-parameter type classes are permitted, with extension
+:extension:`MultiParamTypeClasses`. For example: ::
 
       class Collection c a where
           union :: c a -> c a -> c a
@@ -5476,12 +5879,8 @@ Multi-parameter type classes are permitted, with flag
 The superclasses of a class declaration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XFlexibleContexts
-    :shortdesc: Enable :ref:`flexible contexts <flexible-contexts>`. Implied by
-        :ghc-flag:`-XImplicitParams`.
-    :type: dynamic
-    :reverse: -XNoFlexibleContexts
-    :category:
+.. extension:: FlexibleContexts
+    :shortdesc: Enable flexible contexts.
 
     :since: 6.8.1
 
@@ -5489,7 +5888,7 @@ The superclasses of a class declaration
 
 In Haskell 98 the context of a class declaration (which introduces
 superclasses) must be simple; that is, each predicate must consist of a
-class applied to type variables. The flag :ghc-flag:`-XFlexibleContexts`
+class applied to type variables. The extension :extension:`FlexibleContexts`
 (:ref:`flexible-contexts`) lifts this restriction, so that the only
 restriction on the context in a class declaration is that the class
 hierarchy must be acyclic. So these class declarations are OK: ::
@@ -5533,11 +5932,8 @@ context.
 Constrained class method types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XConstrainedClassMethods
-    :shortdesc: Enable :ref:`constrained class methods <class-method-types>`.
-    :type: dynamic
-    :reverse: -XNoConstrainedClassMethods
-    :category:
+.. extension:: ConstrainedClassMethods
+    :shortdesc: Enable constrained class methods.
 
     :since: 6.8.1
 
@@ -5570,20 +5966,17 @@ this case ``a``).  More precisely, a constraint in a class method signature is r
 
 
 GHC lifts this restriction with language extension
-:ghc-flag:`-XConstrainedClassMethods`. The restriction is a pretty stupid one in
-the first place, so :ghc-flag:`-XConstrainedClassMethods` is implied by
-:ghc-flag:`-XMultiParamTypeClasses`.
+:extension:`ConstrainedClassMethods`. The restriction is a pretty stupid one in
+the first place, so :extension:`ConstrainedClassMethods` is implied by
+:extension:`MultiParamTypeClasses`.
 
 .. _class-default-signatures:
 
 Default method signatures
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XDefaultSignatures
-    :shortdesc: Enable :ref:`default signatures <class-default-signatures>`.
-    :type: dynamic
-    :reverse: -XNoDefaultSignatures
-    :category:
+.. extension:: DefaultSignatures
+    :shortdesc: Enable default signatures.
 
     :since: 7.2.1
 
@@ -5598,7 +5991,7 @@ a class: ::
 
 The type of the ``enum`` method is ``[a]``, and this is also the type of
 the default method. You can lift this restriction and give another type
-to the default method using the flag :ghc-flag:`-XDefaultSignatures`. For
+to the default method using the extension :extension:`DefaultSignatures`. For
 instance, if you have written a generic implementation of enumeration in
 a class ``GEnum`` with method ``genum`` in terms of ``GHC.Generics``,
 you can specify a default method that uses that generic implementation: ::
@@ -5630,7 +6023,7 @@ Then a default method for ``bar`` must take on the form: ::
 
 ``C`` is allowed to be different from ``C'``, but the right-hand sides of the
 type signatures must coincide. We require this because when you declare an
-empty instance for a class that uses :ghc-flag:`-XDefaultSignatures`, GHC
+empty instance for a class that uses :extension:`DefaultSignatures`, GHC
 implicitly fills in the default implementation like this: ::
 
       instance Foo Int where
@@ -5676,23 +6069,19 @@ We use default signatures to simplify generic programming in GHC
 Nullary type classes
 ~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XNullaryTypeClasses
-    :shortdesc: Deprecated, does nothing. :ref:`nullary (no parameter) type
-        classes <nullary-type-classes>` are now enabled using
-        :ghc-flag:`-XMultiParamTypeClasses`.
-    :type: dynamic
-    :reverse: -XNoNullaryTypeClasses
-    :category:
+.. extension:: NullaryTypeClasses
+    :shortdesc: Deprecated, does nothing. nullary (no parameter) type
+        classes are now enabled using :extension:`MultiParamTypeClasses`.
 
     :since: 7.8.1
 
-    Allows the use definition of type classes with no parameters. This flag
-    has been replaced by :ghc-flag:`-XMultiParamTypeClasses`.
+    Allows the use definition of type classes with no parameters. This extension
+    has been replaced by :extension:`MultiParamTypeClasses`.
 
 
 Nullary (no parameter) type classes are enabled with
-:ghc-flag:`-XMultiParamTypeClasses`; historically, they were enabled with the
-(now deprecated) :ghc-flag:`-XNullaryTypeClasses`. Since there are no available
+:extension:`MultiParamTypeClasses`; historically, they were enabled with the
+(now deprecated) :extension:`NullaryTypeClasses`. Since there are no available
 parameters, there can be at most one instance of a nullary class. A nullary type
 class might be used to document some assumption in a type signature (such as
 reliance on the Riemann hypothesis) or add some globally configurable settings
@@ -5718,14 +6107,11 @@ dependence with: ::
 Functional dependencies
 -----------------------
 
-.. ghc-flag:: -XFunctionalDependencies
-    :shortdesc: Enable :ref:`functional dependencies <functional-dependencies>`.
-        Implies :ghc-flag:`-XMultiParamTypeClasses`.
-    :type: dynamic
-    :reverse: -XNoFunctionalDependencies
-    :category:
+.. extension:: FunctionalDependencies
+    :shortdesc: Enable functional dependencies.
+        Implies :extension:`MultiParamTypeClasses`.
 
-    :implies: :ghc-flag:`-XMultiParamTypeClasses`
+    :implies: :extension:`MultiParamTypeClasses`
     :since: 6.8.1
 
     Allow use of functional dependencies in class declarations.
@@ -5893,12 +6279,17 @@ information can be seen both as a generalisation of the proposal for
 Odersky, or as a special case of Mark Jones's later framework for
 "improvement" of qualified types. The underlying ideas are also
 discussed in a more theoretical and abstract setting in a manuscript
-[implparam], where they are identified as one point in a general design
+[Jones1999]_, where they are identified as one point in a general design
 space for systems of implicit parameterisation). To start with an
 abstract example, consider a declaration such as: ::
 
        class C a b where ...
 
+.. [Jones1999]
+    "`Exploring the Design Space for Type-based Implicit Parameterization
+    <https://web.cecs.pdx.edu/~mpj/pubs/fdtr.html>`__", Mark P. Jones, Oregon
+    Graduate Institute of Science & Technology, Technical Report, July 1999.
+
 which tells us simply that ``C`` can be thought of as a binary relation on
 types (or type constructors, depending on the kinds of ``a`` and ``b``). Extra
 clauses can be included in the definition of classes to add information
@@ -5908,7 +6299,7 @@ about dependencies between parameters, as in the following examples: ::
        class E a b | a -> b, b -> a where ...
 
 The notation ``a -> b`` used here between the ``|`` and ``where`` symbols —
-not to be confused with a function type — indicates that the a
+not to be confused with a function type — indicates that the ``a``
 parameter uniquely determines the ``b`` parameter, and might be read as "``a``
 determines ``b``." Thus ``D`` is not just a relation, but actually a (partial)
 function. Similarly, from the two dependencies that are included in the
@@ -5973,9 +6364,9 @@ original definition of ``Collects`` with a simple dependency: ::
 
 The dependency ``ce -> e`` here specifies that the type ``e`` of elements is
 uniquely determined by the type of the collection ``ce``. Note that both
-parameters of Collects are of kind ``*``; there are no constructor classes
-here. Note too that all of the instances of ``Collects`` that we gave
-earlier can be used together with this new definition.
+parameters of Collects are of kind ``Type``; there are no constructor classes
+here. Note too that all of the instances of ``Collects`` that we gave earlier
+can be used together with this new definition.
 
 What about the ambiguity problems that we encountered with the original
 definition? The empty function still has type ``Collects e ce => ce``, but
@@ -6062,26 +6453,19 @@ resolution rules.
 Relaxed rules for the instance head
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XTypeSynonymInstances
-    :shortdesc: Enable :ref:`type synonyms in instance heads
-        <flexible-instance-head>`. Implied by :ghc-flag:`-XFlexibleInstances`.
-    :type: dynamic
-    :reverse: -XNoTypeSynonymInstances
-    :category:
+.. extension:: TypeSynonymInstances
+    :shortdesc: Enable type synonyms in instance heads.
+      Implied by :extension:`FlexibleInstances`.
 
     :since: 6.8.1
 
     Allow definition of type class instances for type synonyms.
 
-.. ghc-flag:: -XFlexibleInstances
-    :shortdesc: Enable :ref:`flexible instances <instance-rules>`.
-        Implies :ghc-flag:`-XTypeSynonymInstances`.
-        Implied by :ghc-flag:`-XImplicitParams`.
-    :type: dynamic
-    :reverse: -XNoFlexibleInstances
-    :category:
+.. extension:: FlexibleInstances
+    :shortdesc: Enable flexible instances.
+        Implies :extension:`TypeSynonymInstances`.
 
-    :implies: :ghc-flag:`-XTypeSynonymInstances`
+    :implies: :extension:`TypeSynonymInstances`
     :since: 6.8.1
 
     Allow definition of type class instances with arbitrary nested types in the
@@ -6097,7 +6481,7 @@ the moment).
 
 GHC relaxes this rule in two ways:
 
--  With the :ghc-flag:`-XTypeSynonymInstances` flag, instance heads may use type
+-  With the :extension:`TypeSynonymInstances` extension, instance heads may use type
    synonyms. As always, using a type synonym is just shorthand for
    writing the RHS of the type synonym definition. For example: ::
 
@@ -6113,7 +6497,7 @@ GHC relaxes this rule in two ways:
 
          instance Monad Point where ...
 
--  The :ghc-flag:`-XFlexibleInstances` flag allows the head of the instance
+-  The :extension:`FlexibleInstances` extension allows the head of the instance
    declaration to mention arbitrary nested types. For example, this
    becomes a legal instance declaration ::
 
@@ -6121,8 +6505,8 @@ GHC relaxes this rule in two ways:
 
    See also the `rules on overlap <#instance-overlap>`__.
 
-   The :ghc-flag:`-XFlexibleInstances` flag implies
-   :ghc-flag:`-XTypeSynonymInstances`.
+   The :extension:`FlexibleInstances` extension implies
+   :extension:`TypeSynonymInstances`.
 
 However, the instance declaration must still conform to the rules for
 instance termination: see :ref:`instance-termination`.
@@ -6136,14 +6520,14 @@ In Haskell 98, the class constraints in the context of the instance
 declaration must be of the form ``C a`` where ``a`` is a type variable
 that occurs in the head.
 
-The :ghc-flag:`-XFlexibleContexts` flag relaxes this rule, as well as relaxing
+The :extension:`FlexibleContexts` extension relaxes this rule, as well as relaxing
 the corresponding rule for type signatures (see
-:ref:`flexible-contexts`). Specifically, :ghc-flag:`-XFlexibleContexts`, allows
+:ref:`flexible-contexts`). Specifically, :extension:`FlexibleContexts`, allows
 (well-kinded) class constraints of form ``(C t1 ... tn)`` in the context
 of an instance declaration.
 
-Notice that the flag does not affect equality constraints in an instance
-context; they are permitted by :ghc-flag:`-XTypeFamilies` or :ghc-flag:`-XGADTs`.
+Notice that the extension does not affect equality constraints in an instance
+context; they are permitted by :extension:`TypeFamilies` or :extension:`GADTs`.
 
 However, the instance declaration must still conform to the rules for
 instance termination: see :ref:`instance-termination`.
@@ -6153,20 +6537,17 @@ instance termination: see :ref:`instance-termination`.
 Instance termination rules
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XUndecidableInstances
-    :shortdesc: Enable :ref:`undecidable instances <undecidable-instances>`.
-    :type: dynamic
-    :reverse: -XNoUndecidableInstances
-    :category:
+.. extension:: UndecidableInstances
+    :shortdesc: Enable undecidable instances.
 
     :since: 6.8.1
 
     Permit definition of instances which may lead to type-checker non-termination.
 
-Regardless of :ghc-flag:`-XFlexibleInstances` and :ghc-flag:`-XFlexibleContexts`,
+Regardless of :extension:`FlexibleInstances` and :extension:`FlexibleContexts`,
 instance declarations must conform to some rules that ensure that
 instance resolution will terminate. The restrictions can be lifted with
-:ghc-flag:`-XUndecidableInstances` (see :ref:`undecidable-instances`).
+:extension:`UndecidableInstances` (see :ref:`undecidable-instances`).
 
 The rules are these:
 
@@ -6262,7 +6643,7 @@ Undecidable instances
 
 Sometimes even the termination rules of :ref:`instance-termination` are
 too onerous. So GHC allows you to experiment with more liberal rules: if
-you use the experimental flag :ghc-flag:`-XUndecidableInstances`, both the Paterson
+you use the experimental extension :extension:`UndecidableInstances`, both the Paterson
 Conditions and the Coverage
 Condition (described in :ref:`instance-termination`) are lifted.
 Termination is still ensured by having a fixed-depth recursion stack. If
@@ -6343,7 +6724,7 @@ indeed the (somewhat strange) definition:
 makes instance inference go into a loop, because it requires the
 constraint ``(Mul a [b] b)``.
 
-The :ghc-flag:`-XUndecidableInstances` flag is also used to lift some of the
+The :extension:`UndecidableInstances` extension is also used to lift some of the
 restrictions imposed on type family instances. See
 :ref:`type-family-decidability`.
 
@@ -6352,30 +6733,24 @@ restrictions imposed on type family instances. See
 Overlapping instances
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XOverlappingInstances
-    :shortdesc: Enable :ref:`overlapping instances <instance-overlap>`.
-    :type: dynamic
-    :reverse: -XNoOverlappingInstances
-    :category:
+.. extension:: OverlappingInstances
+    :shortdesc: Enable overlapping instances.
 
-    Deprecated flag to weaken checks intended to ensure instance resolution
+    Deprecated extension to weaken checks intended to ensure instance resolution
     termination.
 
-.. ghc-flag:: -XIncoherentInstances
-    :shortdesc: Enable :ref:`incoherent instances <instance-overlap>`.
-        Implies :ghc-flag:`-XOverlappingInstances`.
-    :type: dynamic
-    :reverse: -XNoIncoherentInstances
-    :category:
+.. extension:: IncoherentInstances
+    :shortdesc: Enable incoherent instances.
+        Implies :extension:`OverlappingInstances`.
 
     :since: 6.8.1
 
-    Deprecated flag to weaken checks intended to ensure instance resolution
+    Deprecated extension to weaken checks intended to ensure instance resolution
     termination.
 
 In general, as discussed in :ref:`instance-resolution`, *GHC requires
 that it be unambiguous which instance declaration should be used to
-resolve a type-class constraint*. GHC also provides a way to to loosen
+resolve a type-class constraint*. GHC also provides a way to loosen
 the instance resolution, by allowing more than one instance to match,
 *provided there is a most specific one*. Moreover, it can be loosened
 further, by allowing more than one instance to match irrespective of
@@ -6388,8 +6763,8 @@ after the ``instance`` keyword. The pragma may be one of:
 or ``{-# INCOHERENT #-}``.
 
 The matching behaviour is also influenced by two module-level language
-extension flags: :ghc-flag:`-XOverlappingInstances` and
-:ghc-flag:`-XIncoherentInstances`. These flags are now
+extension flags: :extension:`OverlappingInstances` and
+:extension:`IncoherentInstances`. These extensions are now
 deprecated (since GHC 7.10) in favour of the fine-grained per-instance
 pragmas.
 
@@ -6399,16 +6774,16 @@ itself, controlled as follows:
 
 -  An instance is *incoherent* if: it has an ``INCOHERENT`` pragma; or
    if the instance has no pragma and it appears in a module compiled
-   with :ghc-flag:`-XIncoherentInstances`.
+   with :extension:`IncoherentInstances`.
 
 -  An instance is *overlappable* if: it has an ``OVERLAPPABLE`` or
    ``OVERLAPS`` pragma; or if the instance has no pragma and it appears
-   in a module compiled with :ghc-flag:`-XOverlappingInstances`; or if the
+   in a module compiled with :extension:`OverlappingInstances`; or if the
    instance is incoherent.
 
 -  An instance is *overlapping* if: it has an ``OVERLAPPING`` or
    ``OVERLAPS`` pragma; or if the instance has no pragma and it appears
-   in a module compiled with :ghc-flag:`-XOverlappingInstances`; or if the
+   in a module compiled with :extension:`OverlappingInstances`; or if the
    instance is incoherent.
 
 Now suppose that, in some client module, we are searching for an
@@ -6419,9 +6794,12 @@ like this:
    target constraint is a substitution instance of :math:`I`. These instance
    declarations are the *candidates*.
 
--  Eliminate any candidate :math:`IX` for which both of the following hold:
+-  If no candidates remain, the search failes
+
+-  Eliminate any candidate :math:`IX` for which there is another candidate
+   :math:`IY` such that both of the following hold:
 
-   -  There is another candidate :math:`IY` that is strictly more specific; that
+   -  :math:`IY` is strictly more specific than :math:`IX`.  That
       is, :math:`IY` is a substitution instance of :math:`IX` but not vice versa.
 
    -  Either :math:`IX` is *overlappable*, or :math:`IY` is *overlapping*. (This
@@ -6429,19 +6807,20 @@ like this:
       client to deliberately override an instance from a library,
       without requiring a change to the library.)
 
--  If exactly one non-incoherent candidate remains, select it. If all
-   remaining candidates are incoherent, select an arbitrary one.
-   Otherwise the search fails (i.e. when more than one surviving
-   candidate is not incoherent).
+-  If all the remaining candidates are incoherent, the search suceeds, returning
+   an arbitrary surviving candidate.
+
+-  If more than one non-incoherent candidate remains, the search fails.
 
--  If the selected candidate (from the previous step) is incoherent, the
-   search succeeds, returning that candidate.
+-  Otherwise there is exactly one non-incoherent candidate; call it the
+   "prime candidate".
 
--  If not, find all instances that *unify* with the target constraint,
+-  Now find all instances, or in-scope given constraints, that *unify* with
+   the target constraint,
    but do not *match* it. Such non-candidate instances might match when
    the target constraint is further instantiated. If all of them are
-   incoherent, the search succeeds, returning the selected candidate; if
-   not, the search fails.
+   incoherent top-level instances, the search succeeds, returning the prime candidate.
+   Otherwise the search fails.
 
 Notice that these rules are not influenced by flag settings in the
 client module, where the instances are *used*. These rules make it
@@ -6475,7 +6854,7 @@ the last is more specific, and hence is chosen.
 
 If (D) did not exist then (A) and (C) would still be matched, but
 neither is most specific. In that case, the program would be rejected,
-unless :ghc-flag:`-XIncoherentInstances` is enabled, in which case it would be
+unless :extension:`IncoherentInstances` is enabled, in which case it would be
 accepted and (A) or (C) would be chosen arbitrarily.
 
 An instance declaration is *more specific* than another iff the head of
@@ -6483,18 +6862,19 @@ former is a substitution instance of the latter. For example (D) is
 "more specific" than (C) because you can get from (C) to (D) by
 substituting ``a := Int``.
 
-GHC is conservative about committing to an overlapping instance. For
-example: ::
+The final bullet (about unifiying instances)
+makes GHC conservative about committing to an
+overlapping instance. For example: ::
 
       f :: [b] -> [b]
       f x = ...
 
 Suppose that from the RHS of ``f`` we get the constraint ``C b [b]``.
 But GHC does not commit to instance (C), because in a particular call of
-``f``, ``b`` might be instantiate to ``Int``, in which case instance (D)
+``f``, ``b`` might be instantiated to ``Int``, in which case instance (D)
 would be more specific still. So GHC rejects the program.
 
-If, however, you add the flag :ghc-flag:`-XIncoherentInstances` when compiling
+If, however, you enable the extension :extension:`IncoherentInstances` when compiling
 the module that contains (D), GHC will instead pick (C), without
 complaining about the problem of subsequent instantiations.
 
@@ -6510,7 +6890,7 @@ the type ::
 That postpones the question of which instance to pick to the call site
 for ``f`` by which time more is known about the type ``b``. You can
 write this type signature yourself if you use the
-:ghc-flag:`-XFlexibleContexts` flag.
+:extension:`FlexibleContexts` extension.
 
 Exactly the same situation can arise in instance declarations
 themselves. Suppose we have ::
@@ -6530,12 +6910,29 @@ declaration, thus: ::
       instance C Int [b] => Foo [b] where
          f x = ...
 
-(You need :ghc-flag:`-XFlexibleInstances` to do this.)
+(You need :extension:`FlexibleInstances` to do this.)
+
+In the unification check in the final bullet, GHC also uses the
+"in-scope given constraints".  Consider for example ::
+
+   instance C a Int
+
+   g :: forall b c. C b Int => blah
+   g = ...needs (C c Int)...
+
+Here GHC will not solve the constraint ``(C c Int)`` from the
+top-level instance, because a particular call of ``g`` might
+instantiate both ``b`` and ``c`` to the same type, which would
+allow the constraint to be solved in a different way.  This latter
+restriction is principally to make the constraint-solver complete.
+(Interested folk can read ``Note [Instance and Given overlap]`` in ``TcInteract``.)
+It is easy to avoid: in a type signature avoid a constraint that
+matches a top-level instance.  The flag :ghc-flag:`-Wsimplifiable-class-constraints` warns about such signatures.
 
 .. warning::
     Overlapping instances must be used with care. They can give
     rise to incoherence (i.e. different instance choices are made in
-    different parts of the program) even without :ghc-flag:`-XIncoherentInstances`.
+    different parts of the program) even without :extension:`IncoherentInstances`.
     Consider: ::
 
         {-# LANGUAGE OverlappingInstances #-}
@@ -6584,11 +6981,8 @@ declaration, thus: ::
 Instance signatures: type signatures in instance declarations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XInstanceSigs
-    :shortdesc: Enable :ref:`instance signatures <instance-sigs>`.
-    :type: dynamic
-    :reverse: -XNoInstanceSigs
-    :category:
+.. extension:: InstanceSigs
+    :shortdesc: Enable instance signatures.
 
     :since: 7.6.1
 
@@ -6596,7 +6990,7 @@ Instance signatures: type signatures in instance declarations
 
 In Haskell, you can't write a type signature in an instance declaration,
 but it is sometimes convenient to do so, and the language extension
-:ghc-flag:`-XInstanceSigs` allows you to do so. For example: ::
+:extension:`InstanceSigs` allows you to do so. For example: ::
 
       data T a = MkT a a
       instance Eq a => Eq (T a) where
@@ -6635,7 +7029,7 @@ Some details
               xs :: [b]
               xs = [x,x,x]
 
-   Provided that you also specify :ghc-flag:`-XScopedTypeVariables`
+   Provided that you also specify :extension:`ScopedTypeVariables`
    (:ref:`scoped-type-variables`), the ``forall b`` scopes over the
    definition of ``foo``, and in particular over the type signature for
    ``xs``.
@@ -6645,11 +7039,8 @@ Some details
 Overloaded string literals
 --------------------------
 
-.. ghc-flag:: -XOverloadedStrings
-    :shortdesc: Enable :ref:`overloaded string literals <overloaded-strings>`.
-    :type: dynamic
-    :reverse: -XNoOverloadedStrings
-    :category:
+.. extension:: OverloadedStrings
+    :shortdesc: Enable overloaded string literals.
 
     :since: 6.8.1
 
@@ -6658,7 +7049,7 @@ Overloaded string literals
 
 GHC supports *overloaded string literals*. Normally a string literal has
 type ``String``, but with overloaded string literals enabled (with
-:ghc-flag:`-XOverloadedStrings`) a string literal has type
+:extension:`OverloadedStrings`) a string literal has type
 ``(IsString a) => a``.
 
 This means that the usual string syntax can be used, e.g., for
@@ -6681,11 +7072,11 @@ usual: ::
 
 The class ``IsString`` is not in scope by default. If you want to
 mention it explicitly (for example, to give an instance declaration for
-it), you can import it from module ``GHC.Exts``.
+it), you can import it from module ``Data.String``.
 
 Haskell's defaulting mechanism (`Haskell Report, Section
 4.3.4 <http://www.haskell.org/onlinereport/decls.html#sect4.3.4>`__) is
-extended to cover string literals, when :ghc-flag:`-XOverloadedStrings` is
+extended to cover string literals, when :extension:`OverloadedStrings` is
 specified. Specifically:
 
 -  Each type in a ``default`` declaration must be an instance of ``Num``
@@ -6709,7 +7100,7 @@ A small example:
 
     module Main where
 
-    import GHC.Exts( IsString(..) )
+    import Data.String( IsString(..) )
 
     newtype MyString = MyString String deriving (Eq, Show)
     instance IsString MyString where
@@ -6731,11 +7122,8 @@ since it gets translated into an equality comparison.
 Overloaded labels
 -----------------
 
-.. ghc-flag:: -XOverloadedLabels
-    :shortdesc: Enable :ref:`overloaded labels <overloaded-labels>`.
-    :type: dynamic
-    :reverse: -XNoOverloadedLabels
-    :category:
+.. extension:: OverloadedLabels
+    :shortdesc: Enable overloaded labels.
 
     :since: 8.0.1
 
@@ -6743,7 +7131,7 @@ Overloaded labels
 
 GHC supports *overloaded labels*, a form of identifier whose interpretation may
 depend both on its type and on its literal text.  When the
-:ghc-flag:`-XOverloadedLabels` extension is enabled, an overloaded label can written
+:extension:`OverloadedLabels` extension is enabled, an overloaded label can be written
 with a prefix hash, for example ``#foo``.  The type of this expression is
 ``IsLabel "foo" a => a``.
 
@@ -6774,22 +7162,22 @@ The intention is for ``IsLabel`` to be used to support overloaded record fields
 and perhaps anonymous records.  Thus, it may be given instances for base
 datatypes (in particular ``(->)``) in the future.
 
-If :ghc-flag:`-XRebindableSyntax` is enabled, overloaded
+If :extension:`RebindableSyntax` is enabled, overloaded
 labels will be desugared using whatever ``fromLabel`` function is in scope,
 rather than always using ``GHC.OverloadedLabels.fromLabel``.
 
 When writing an overloaded label, there must be no space between the hash sign
-and the following identifier.  The :ghc-flag:`-XMagicHash` extension makes use
-of postfix hash signs; if :ghc-flag:`-XOverloadedLabels` and
-:ghc-flag:`-XMagicHash` are both enabled then ``x#y`` means ``x# y``, but if
-only :ghc-flag:`-XOverloadedLabels` is enabled then it means ``x #y``.  The
-:ghc-flag:`-XUnboxedTuples` extension makes ``(#`` a single lexeme, so when
-:ghc-flag:`-XUnboxedTuples` is enabled you must write a space between an opening
+and the following identifier.  The :extension:`MagicHash` extension makes use
+of postfix hash signs; if :extension:`OverloadedLabels` and
+:extension:`MagicHash` are both enabled then ``x#y`` means ``x# y``, but if
+only :extension:`OverloadedLabels` is enabled then it means ``x #y``.  The
+:extension:`UnboxedTuples` extension makes ``(#`` a single lexeme, so when
+:extension:`UnboxedTuples` is enabled you must write a space between an opening
 parenthesis and an overloaded label.  To avoid confusion, you are strongly
 encouraged to put a space before the hash when using
-:ghc-flag:`-XOverloadedLabels`.
+:extension:`OverloadedLabels`.
 
-When using :ghc-flag:`-XOverloadedLabels` (or other extensions that make use of
+When using :extension:`OverloadedLabels` (or other extensions that make use of
 hash signs) in a ``.hsc`` file (see :ref:`hsc2hs`), the hash signs must be
 doubled (write ``##foo`` instead of ``#foo``) to avoid them being treated as
 ``hsc2hs`` directives.
@@ -6827,11 +7215,8 @@ showing how an overloaded label can be used as a record selector:
 Overloaded lists
 ----------------
 
-.. ghc-flag:: -XOverloadedLists
-    :shortdesc: Enable :ref:`overloaded lists <overloaded-lists>`.
-    :type: dynamic
-    :reverse: -XNoOverloadedLists
-    :category:
+.. extension:: OverloadedLists
+    :shortdesc: Enable overloaded lists.
 
     :since: 7.8.1
 
@@ -6964,11 +7349,11 @@ several example instances:
 Rebindable syntax
 ~~~~~~~~~~~~~~~~~
 
-When desugaring list notation with :ghc-flag:`-XOverloadedLists` GHC uses the
+When desugaring list notation with :extension:`OverloadedLists` GHC uses the
 ``fromList`` (etc) methods from module ``GHC.Exts``. You do not need to
 import ``GHC.Exts`` for this to happen.
 
-However if you use :ghc-flag:`-XRebindableSyntax`, then GHC instead uses
+However if you use :extension:`RebindableSyntax`, then GHC instead uses
 whatever is in scope with the names of ``toList``, ``fromList`` and
 ``fromListN``. That is, these functions are rebindable; c.f.
 :ref:`rebindable-syntax`.
@@ -6998,19 +7383,16 @@ representation).
 Undecidable (or recursive) superclasses
 ---------------------------------------
 
-.. ghc-flag:: -XUndecidableSuperClasses
+.. extension:: UndecidableSuperClasses
     :shortdesc: Allow all superclass constraints, including those that may
         result in non-termination of the typechecker.
-    :type: dynamic
-    :reverse: -XNoUndecidableSuperClasses
-    :category:
 
     :since: 8.0.1
 
     Allow all superclass constraints, including those that may result in
     non-termination of the typechecker.
 
-The language extension :ghc-flag:`-XUndecidableSuperClasses` allows much more flexible
+The language extension :extension:`UndecidableSuperClasses` allows much more flexible
 constraints in superclasses.
 
 A class cannot generally have itself as a superclass. So this is illegal ::
@@ -7046,12 +7428,12 @@ example (Trac #10318) ::
             Fractional (Frac a),
             IntegralDomain (Frac a))
          => IntegralDomain a where
-      type Frac a :: *
+      type Frac a :: Type
 
 Here the superclass cycle does terminate but it's not entirely straightforward
 to see that it does.
 
-With the language extension :ghc-flag:`-XUndecidableSuperClasses` GHC lifts all restrictions
+With the language extension :extension:`UndecidableSuperClasses` GHC lifts all restrictions
 on superclass constraints. If there really *is* a loop, GHC will only
 expand it to finite depth.
 
@@ -7061,16 +7443,13 @@ expand it to finite depth.
 Type families
 =============
 
-.. ghc-flag:: -XTypeFamilies
-    :shortdesc: Enable :ref:`type families <type-families>`.
-        Implies :ghc-flag:`-XExplicitNamespaces`, :ghc-flag:`-XKindSignatures`,
-        and :ghc-flag:`-XMonoLocalBinds`.
-    :type: dynamic
-    :reverse: -XNoTypeFamilies
-    :category:
+.. extension:: TypeFamilies
+    :shortdesc: Enable type families.
+        Implies :extension:`ExplicitNamespaces`, :extension:`KindSignatures`,
+        and :extension:`MonoLocalBinds`.
 
-    :implies: :ghc-flag:`-XMonoLocalBinds`, :ghc-flag:`-XKindSignatures`,
-              :ghc-flag:`-XExplicitNamespaces`
+    :implies: :extension:`MonoLocalBinds`, :extension:`KindSignatures`,
+              :extension:`ExplicitNamespaces`
     :since: 6.8.1
 
     Allow use and definition of indexed type and data families.
@@ -7104,7 +7483,7 @@ synonym families, and closed type synonym families. They are the indexed
 family variants of algebraic data types and type synonyms, respectively.
 The instances of data families can be data types and newtypes.
 
-Type families are enabled by the flag :ghc-flag:`-XTypeFamilies`. Additional
+Type families are enabled by the language extension :extension:`TypeFamilies`. Additional
 information on the use of type families in GHC is available on `the
 Haskell wiki page on type
 families <http://www.haskell.org/haskellwiki/GHC/Indexed_types>`__.
@@ -7116,14 +7495,14 @@ families <http://www.haskell.org/haskellwiki/GHC/Indexed_types>`__.
     and S. Marlow. In Proceedings of “The 32nd Annual
     ACM SIGPLAN-SIGACT Symposium on Principles of
     Programming Languages (POPL'05)”, pages 1-13, ACM
-    Press, 2005)
+    Press, 2005.
 
 .. [AssocTypeSyn2005]
     “`Type Associated Type
     Synonyms <http://www.cse.unsw.edu.au/~chak/papers/CKP05.html>`__\ ”. M.
     Chakravarty, G. Keller, and S. Peyton Jones. In Proceedings of “The
     Tenth ACM SIGPLAN International Conference on Functional Programming”,
-    ACM Press, pages 241-253, 2005).
+    ACM Press, pages 241-253, 2005.
 
 .. [TypeFamilies2008]
     “\ `Type Checking with Open Type
@@ -7155,11 +7534,11 @@ Data family declarations
 
 Indexed data families are introduced by a signature, such as ::
 
-    data family GMap k :: * -> *
+    data family GMap k :: Type -> Type
 
 The special ``family`` distinguishes family from standard data
 declarations. The result kind annotation is optional and, as usual,
-defaults to ``*`` if omitted. An example is ::
+defaults to ``Type`` if omitted. An example is ::
 
     data family Array e
 
@@ -7167,12 +7546,12 @@ Named arguments can also be given explicit kind signatures if needed.
 Just as with :ref:`GADT declarations <gadt>` named arguments are
 entirely optional, so that we can declare ``Array`` alternatively with ::
 
-    data family Array :: * -> *
+    data family Array :: Type -> Type
 
 Unlike with ordinary data definitions, the result kind of a data family
-does not need to be ``*``: it can alternatively be a kind variable
-(with :ghc-flag:`-XPolyKinds`). Data instances' kinds must end in
-``*``, however.
+does not need to be ``Type``: it can alternatively be a kind variable
+(with :extension:`PolyKinds`). Data instances' kinds must end in
+``Type``, however.
 
 .. _data-instance-declarations:
 
@@ -7195,6 +7574,17 @@ instance for ``GMap`` is ::
 In this example, the declaration has only one variant. In general, it
 can be any number.
 
+When :extension:`ExplicitForAll` is enabled, type or kind variables used on
+the left hand side can be explicitly bound. For example: ::
+
+    data instance forall a (b :: Proxy a). F (Proxy b) = FProxy Bool
+
+When an explicit ``forall`` is present, all *type* variables mentioned which
+are not already in scope must be bound by the ``forall``. Kind variables will
+be implicitly bound if necessary, for example: ::
+
+    data instance forall (a :: k). F a = FOtherwise
+
 When the flag :ghc-flag:`-Wunused-type-patterns` is enabled, type
 variables that are mentioned in the patterns on the left hand side, but not
 used on the right hand side are reported. Variables that occur multiple times
@@ -7206,7 +7596,10 @@ ordinary type variables.
 This resembles the wildcards that can be used in
 :ref:`partial-type-signatures`. However, there are some differences.
 No error messages reporting the inferred types are generated, nor does
-the flag :ghc-flag:`-XPartialTypeSignatures` have any effect.
+the extension :extension:`PartialTypeSignatures` have any effect.
+
+A type or kind variable explicitly bound using :extension:`ExplicitForAll` but
+not used on the left hand side will generate an error, not a warning.
 
 Data and newtype instance declarations are only permitted when an
 appropriate family declaration is in scope - just as a class instance
@@ -7299,35 +7692,36 @@ Type family declarations
 
 Open indexed type families are introduced by a signature, such as ::
 
-    type family Elem c :: *
+    type family Elem c :: Type
 
 The special ``family`` distinguishes family from standard type
 declarations. The result kind annotation is optional and, as usual,
-defaults to ``*`` if omitted. An example is ::
+defaults to ``Type`` if omitted. An example is ::
 
     type family Elem c
 
 Parameters can also be given explicit kind signatures if needed. We call
 the number of parameters in a type family declaration, the family's
 arity, and all applications of a type family must be fully saturated
-with respect to to that arity. This requirement is unlike ordinary type synonyms
+with respect to that arity. This requirement is unlike ordinary type synonyms
 and it implies that the kind of a type family is not sufficient to
 determine a family's arity, and hence in general, also insufficient to
 determine whether a type family application is well formed. As an
 example, consider the following declaration: ::
 
-    type family F a b :: * -> *   -- F's arity is 2,
-                                  -- although its overall kind is * -> * -> * -> *
+    type family F a b :: Type -> Type
+      -- F's arity is 2,
+      -- although its overall kind is Type -> Type -> Type -> Type
 
 Given this declaration the following are examples of well-formed and
 malformed types: ::
 
-    F Char [Int]       -- OK!  Kind: * -> *
-    F Char [Int] Bool  -- OK!  Kind: *
+    F Char [Int]       -- OK!  Kind: Type -> Type
+    F Char [Int] Bool  -- OK!  Kind: Type
     F IO Bool          -- WRONG: kind mismatch in the first argument
     F Bool             -- WRONG: unsaturated application
 
-The result kind annotation is optional and defaults to ``*`` (like
+The result kind annotation is optional and defaults to ``Type`` (like
 argument kinds) if omitted. Polykinded type families can be declared
 using a parameter in the kind annotation: ::
 
@@ -7359,6 +7753,10 @@ with underscores to avoid warnings when the
 :ghc-flag:`-Wunused-type-patterns` flag is enabled. The same rules apply
 as for :ref:`data-instance-declarations`.
 
+Also in the same way as :ref:`data-instance-declarations`, when
+:extension:`ExplicitForAll` is enabled, type and kind variables can be
+explicilty bound in a type instance declaration.
+
 Type family instance declarations are only legitimate when an
 appropriate family declaration is in scope - just like class instances
 require the class declaration to be visible. Moreover, each instance
@@ -7393,8 +7791,14 @@ Note that GHC must be sure that ``a`` cannot unify with ``Int`` or
 their code, GHC will not be able to simplify the type. After all, ``a``
 might later be instantiated with ``Int``.
 
-A closed type family's equations have the same restrictions as the
-equations for open type family instances.
+A closed type family's equations have the same restrictions and extensions as
+the equations for open type family instances. For instance, when
+:extension:`ExplicitForAll` is enabled, type or kind variables used on the
+left hand side of an equation can be explicitly bound, such as in: ::
+
+  type family R a where
+    forall t a. R (t a) = [a]
+    forall a.   R a     = a
 
 A closed type family may be declared with no equations. Such closed type
 families are opaque type-level definitions that will never reduce, are
@@ -7411,7 +7815,7 @@ Type family examples
 
 Here are some examples of admissible and illegal type instances: ::
 
-    type family F a :: *
+    type family F a :: Type
     type instance F [Int]   = Int   -- OK!
     type instance F String  = Char  -- OK!
     type instance F (F a)   = a     -- WRONG: type parameter mentions a type family
@@ -7426,7 +7830,7 @@ Here are some examples of admissible and illegal type instances: ::
     type instance H Char = Char    -- WRONG: cannot have instances of closed family
     type family K a where          -- OK!
 
-    type family G a b :: * -> *
+    type family G a b :: Type -> Type
     type instance G Int            = (,)     -- WRONG: must be two type parameters
     type instance G Int Char Float = Double  -- WRONG: must be two type parameters
 
@@ -7477,8 +7881,8 @@ like types. For example, the following is accepted: ::
     type instance J Int = Bool
     type instance J Int = Maybe
 
-These instances are compatible because they differ in their implicit
-kind parameter; the first uses ``*`` while the second uses ``* -> *``.
+These instances are compatible because they differ in their implicit kind
+parameter; the first uses ``Type`` while the second uses ``Type -> Type``.
 
 The definition for "compatible" uses a notion of "apart", whose
 definition in turn relies on type family reduction. This condition of
@@ -7524,7 +7928,7 @@ However see :ref:`ghci-decls` for the overlap rules in GHCi.
 Decidability of type synonym instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XUndecidableInstances
+.. extension:: UndecidableInstances
     :noindex:
 
     Relax restrictions on the decidability of type synonym family instances.
@@ -7557,7 +7961,7 @@ as ``a ~ [F a]``, where a recursive occurrence of a type variable is
 underneath a family application and data constructor application - see
 the above mentioned paper for details.
 
-If the option :ghc-flag:`-XUndecidableInstances` is passed to the compiler, the
+If the option :extension:`UndecidableInstances` is passed to the compiler, the
 above restrictions are not enforced and it is on the programmer to ensure
 termination of the normalisation of type families during type inference.
 
@@ -7570,11 +7974,11 @@ When the name of a type argument of a data or type instance
 declaration doesn't matter, it can be replaced with an underscore
 (``_``). This is the same as writing a type variable with a unique name. ::
 
-    data family F a b :: *
+    data family F a b :: Type
     data instance F Int _ = Int
     -- Equivalent to  data instance F Int b = Int
 
-    type family T a :: *
+    type family T a :: Type
     type instance T (a,_) = a
     -- Equivalent to  type instance T (a,b) = a
 
@@ -7601,11 +8005,11 @@ A data or type synonym family can be declared as part of a type class,
 thus: ::
 
     class GMapKey k where
-      data GMap k :: * -> *
+      data GMap k :: Type -> Type
       ...
 
     class Collects ce where
-      type Elem ce :: *
+      type Elem ce :: Type
       ...
 
 When doing so, we (optionally) may drop the "``family``" keyword.
@@ -7617,12 +8021,12 @@ may be omitted and they may be in an order other than in the class head.
 Hence, the following contrived example is admissible: ::
 
       class C a b c where
-        type T c a x :: *
+        type T c a x :: Type
 
 Here ``c`` and ``a`` are class parameters, but the type is also indexed
 on a third parameter ``x``.
 
-.. _assoc-data-inst:
+.. _assoc-inst:
 
 Associated instances
 ~~~~~~~~~~~~~~~~~~~~
@@ -7639,12 +8043,12 @@ keyword in the family instance: ::
       type Elem [e] = e
       ...
 
-The data or type family instance for an assocated type must follow
+The data or type family instance for an associated type must follow
 the rule that the type indexes corresponding to class parameters must have
 precisely the same as type given in the instance head. For example: ::
 
     class Collects ce where
-      type Elem ce :: *
+      type Elem ce :: Type
 
     instance Eq (Elem [e]) => Collects [e] where
       -- Choose one of the following alternatives:
@@ -7665,17 +8069,17 @@ Note the following points:
    to mention kind variables that are implicitly bound. For example, these are
    legitimate: ::
 
-    data family Nat :: k -> k -> *
+    data family Nat :: k -> k -> Type
     -- k is implicitly bound by an invisible kind pattern
-    newtype instance Nat :: (k -> *) -> (k -> *) -> * where
+    newtype instance Nat :: (k -> Type) -> (k -> Type) -> Type where
       Nat :: (forall xx. f xx -> g xx) -> Nat f g
 
     class Funct f where
-      type Codomain f :: *
+      type Codomain f :: Type
     instance Funct ('KProxy :: KProxy o) where
       -- o is implicitly bound by the kind signature
       -- of the LHS type pattern ('KProxy)
-      type Codomain 'KProxy = NatTr (Proxy :: o -> *)
+      type Codomain 'KProxy = NatTr (Proxy :: o -> Type)
 
 -  The instance for an associated type can be omitted in class
    instances. In that case, unless there is a default instance (see
@@ -7696,7 +8100,16 @@ Note the following points:
    parameter is ``[v]``, and one for which it is ``Int``. Since you
    cannot give any *subsequent* instances for ``(GMap Flob ...)``, this
    facility is most useful when the free indexed parameter is of a kind
-   with a finite number of alternatives (unlike ``*``).
+   with a finite number of alternatives (unlike ``Type``).
+
+-  When :extension:`ExplicitForAll` is enabled, type and kind variables can be
+   explicily bound in associated data or type family instances in the same way
+   (and with the same restrictions) as :ref:`data-instance-declarations` or
+   :ref:`type-instance-declarations`. For example, adapting the above, the
+   following is accepted: ::
+
+     instance Eq (Elem [e]) => Collects [e] where
+       type forall e. Elem [e] = e
 
 .. _assoc-decl-defs:
 
@@ -7734,6 +8147,10 @@ Note the following points:
    is relaxed for *kind* variables, however, as the right hand side is allowed
    to mention kind variables that are implicitly bound on the left hand side.
 
+   Because of this, unlike :ref:`assoc-inst`, explicit binding of type/kind
+   variables in default declarations is not permitted by
+   :extension:`ExplicitForAll`.
+
 -  Unlike the associated type family declaration itself, the type variables of
    the default instance are independent of those of the parent class.
 
@@ -7741,8 +8158,8 @@ Here are some examples:
 
 ::
 
-      class C (a :: *) where
-        type F1 a :: *
+      class C (a :: Type) where
+        type F1 a :: Type
         type instance F1 a = [a]     -- OK
         type instance F1 a = a->a    -- BAD; only one default instance is allowed
 
@@ -7795,7 +8212,7 @@ admit such data instances as they would compromise type safety.
 
 Bear in mind that it is also possible for the *right*-hand side of an
 associated family instance to contain *kind* parameters (by using the
-:ghc-flag:`-XPolyKinds` extension). For instance, this class and instance are
+:extension:`PolyKinds` extension). For instance, this class and instance are
 perfectly admissible: ::
 
     class C k where
@@ -7877,7 +8294,7 @@ Recall our running ``GMapKey`` class example:
 ::
 
     class GMapKey k where
-      data GMap k :: * -> *
+      data GMap k :: Type -> Type
       insert :: GMap k v -> k -> v -> GMap k v
       lookup :: GMap k v -> k -> Maybe v
       empty  :: GMap k v
@@ -8024,14 +8441,11 @@ which implicitly defines an instance of the form ::
 Injective type families
 -----------------------
 
-.. ghc-flag:: -XTypeFamilyDependencies
-    :shortdesc: Enable :ref:`injective type families <injective-ty-fams>`.
-        Implies :ghc-flag:`-XTypeFamilies`.
-    :type: dynamic
-    :reverse: -XNoTypeFamilyDependencies
-    :category:
+.. extension:: TypeFamilyDependencies
+    :shortdesc: Enable injective type families.
+        Implies :extension:`TypeFamilies`.
 
-    :implies: :ghc-flag:`-XTypeFamilies`
+    :implies: :extension:`TypeFamilies`
     :since: 8.0.1
 
     Allow functional dependency annotations on type families. This allows one to
@@ -8157,11 +8571,8 @@ family applications as possibly unifying with anything.
 Datatype promotion
 ==================
 
-.. ghc-flag:: -XDataKinds
-    :shortdesc: Enable :ref:`datatype promotion <promotion>`.
-    :type: dynamic
-    :reverse: -XNoDataKinds
-    :category:
+.. extension:: DataKinds
+    :shortdesc: Enable datatype promotion.
 
     :since: 7.4.1
 
@@ -8169,7 +8580,7 @@ Datatype promotion
 
 This section describes *data type promotion*, an extension to the kind
 system that complements kind polymorphism. It is enabled by
-:ghc-flag:`-XDataKinds`, and described in more detail in the paper `Giving
+:extension:`DataKinds`, and described in more detail in the paper `Giving
 Haskell a Promotion <http://dreixel.net/research/pdf/ghp.pdf>`__, which
 appeared at TLDI 2012.
 
@@ -8179,7 +8590,7 @@ Motivation
 Standard Haskell has a rich type language. Types classify terms and
 serve to avoid many common programming mistakes. The kind language,
 however, is relatively simple, distinguishing only regular types (kind
-``*``) and type constructors (e.g. kind ``* -> * -> *``).
+``Type``) and type constructors (e.g. kind ``Type -> Type -> Type``).
 In particular when using advanced type
 system features, such as type families (:ref:`type-families`) or GADTs
 (:ref:`gadt`), this simple kind system is insufficient, and fails to
@@ -8189,19 +8600,19 @@ numbers, and length-indexed vectors: ::
     data Ze
     data Su n
 
-    data Vec :: * -> * -> * where
+    data Vec :: Type -> Type -> Type where
       Nil  :: Vec a Ze
       Cons :: a -> Vec a n -> Vec a (Su n)
 
-The kind of ``Vec`` is ``* -> * -> *``. This means that, e.g.,
+The kind of ``Vec`` is ``Type -> Type -> Type``. This means that, e.g.,
 ``Vec Int Char`` is a well-kinded type, even though this is not what we
 intend when defining length-indexed vectors.
 
-With :ghc-flag:`-XDataKinds`, the example above can then be rewritten to: ::
+With :extension:`DataKinds`, the example above can then be rewritten to: ::
 
     data Nat = Ze | Su Nat
 
-    data Vec :: * -> Nat -> * where
+    data Vec :: Type -> Nat -> Type where
       Nil  :: Vec a 'Ze
       Cons :: a -> Vec a n -> Vec a ('Su n)
 
@@ -8211,7 +8622,7 @@ ill-kinded, and GHC will report an error.
 Overview
 --------
 
-With :ghc-flag:`-XDataKinds`, GHC automatically promotes every datatype
+With :extension:`DataKinds`, GHC automatically promotes every datatype
 to be a kind and its (value) constructors to be type constructors. The
 following types ::
 
@@ -8226,48 +8637,39 @@ following types ::
 give rise to the following kinds and type constructors (where promoted
 constructors are prefixed by a tick ``'``): ::
 
-    Nat :: *
+    Nat :: Type
     'Zero :: Nat
     'Succ :: Nat -> Nat
 
-    List :: * -> *
+    List :: Type -> Type
     'Nil  :: forall k. List k
     'Cons :: forall k. k -> List k -> List k
 
-    Pair  :: * -> * -> *
+    Pair  :: Type -> Type -> Type
     'Pair :: forall k1 k2. k1 -> k2 -> Pair k1 k2
 
-    Sum :: * -> * -> *
+    Sum :: Type -> Type -> Type
     'L :: k1 -> Sum k1 k2
     'R :: k2 -> Sum k1 k2
 
-The following restrictions apply to promotion:
+Virtually all data constructors, even those with rich kinds, can be promoted.
+There are only a couple of exceptions to this rule:
 
--  We promote ``data`` types and ``newtypes``; type synonyms and
-   type/data families are not promoted (:ref:`type-families`).
+-  Data family instance constructors cannot be promoted at the moment. GHC's
+   type theory just isn’t up to the task of promoting data families, which
+   requires full dependent types.
 
--  We only promote types whose kinds are of the form
-   ``* -> ... -> * -> *``. In particular, we do not promote
-   higher-kinded datatypes such as ``data Fix f = In (f (Fix f))``, or
-   datatypes whose kinds involve promoted types such as
-   ``Vec :: * -> Nat -> *``.
+-  Data constructors with contexts that contain non-equality constraints cannot
+   be promoted. For example: ::
 
--  We do not promote data constructors that are kind polymorphic,
-   involve constraints, mention type or data families, or involve types
-   that are not promotable.
+     data Foo :: Type -> Type where
+       MkFoo1 :: a ~ Int         => Foo a    -- promotable
+       MkFoo2 :: a ~~ Int        => Foo a    -- promotable
+       MkFoo3 :: Show a          => Foo a    -- not promotable
 
-The flag :ghc-flag:`-XTypeInType` (which implies :ghc-flag:`-XDataKinds`)
-relaxes some of these restrictions, allowing:
-
--  Promotion of type synonyms and type families, but not data families.
-   GHC's type theory just isn't up to the task of promoting data families,
-   which requires full dependent types.
-
--  All datatypes, even those with rich kinds, get promoted. For example: ::
-
-     data Proxy a = Proxy
-     data App f a = MkApp (f a)   -- App :: forall k. (k -> *) -> k -> *
-     x = Proxy :: Proxy ('MkApp ('Just 'True))
+   ``MkFoo1`` and ``MkFoo2`` can be promoted, since their contexts
+   only involve equality-oriented constraints. However, ``MkFoo3``'s context
+   contains a non-equality constraint ``Show a``, and thus cannot be promoted.
 
 .. _promotion-syntax:
 
@@ -8305,15 +8707,15 @@ promotion quote and the data constructor: ::
 Promoted list and tuple types
 -----------------------------
 
-With :ghc-flag:`-XDataKinds`, Haskell's list and tuple types are natively
+With :extension:`DataKinds`, Haskell's list and tuple types are natively
 promoted to kinds, and enjoy the same convenient syntax at the type
 level, albeit prefixed with a quote: ::
 
-    data HList :: [*] -> * where
+    data HList :: [Type] -> Type where
       HNil  :: HList '[]
       HCons :: a -> HList t -> HList (a ': t)
 
-    data Tuple :: (*,*) -> * where
+    data Tuple :: (Type,Type) -> Type where
       Tuple :: a -> b -> Tuple '(a,b)
 
     foo0 :: HList '[]
@@ -8332,8 +8734,8 @@ required, because the types ``[]`` and ``[Int]`` have existing meanings in
 Haskell.
 
 .. note::
-    The declaration for ``HCons`` also requires :ghc-flag:`-XTypeOperators`
-    because of infix type operator ``(:')``
+    The declaration for ``HCons`` also requires :extension:`TypeOperators`
+    because of infix type operator ``(':)``
 
 
 .. _promotion-existentials:
@@ -8344,7 +8746,7 @@ Promoting existential data constructors
 Note that we do promote existential data constructors that are otherwise
 suitable. For example, consider the following: ::
 
-    data Ex :: * where
+    data Ex :: Type where
       MkEx :: forall a. a -> Ex
 
 Both the type ``Ex`` and the data constructor ``MkEx`` get promoted,
@@ -8363,7 +8765,7 @@ The return kind ``k`` is an implicit parameter to ``UnEx``. The
 elaborated definitions are as follows (where implicit parameters are
 denoted by braces): ::
 
-    type family UnEx {k :: *} (ex :: Ex) :: k
+    type family UnEx {k :: Type} (ex :: Ex) :: k
     type instance UnEx {k} (MkEx @k x) = x
 
 Thus, the instance triggers only when the implicit parameter to ``UnEx``
@@ -8376,34 +8778,24 @@ See also :ghc-ticket:`7347`.
 .. _type-in-type:
 .. _kind-polymorphism:
 
-Kind polymorphism and Type-in-Type
+Kind polymorphism
 ==================================
 
-.. ghc-flag:: -XTypeInType
-    :shortdesc: Allow :ref:`kinds to be used as types <type-in-type>`,
-        including explicit kind variable quantification, higher-rank
-        kinds, kind synonyms, and kind families.
-        Implies :ghc-flag:`-XDataKinds`, :ghc-flag:`-XKindSignatures`,
-        and :ghc-flag:`-XPolyKinds`.
-    :type: dynamic
-    :reverse: -XNoTypeInType
-    :category:
+.. extension:: TypeInType
+    :shortdesc: Deprecated. Enable kind polymorphism and datatype promotion.
 
-    :implies: :ghc-flag:`-XPolyKinds`, :ghc-flag:`-XDataKinds`, :ghc-flag:`-XKindSignatures`
+    :implies: :extension:`PolyKinds`, :extension:`DataKinds`, :extension:`KindSignatures`
     :since: 8.0.1
 
-    Allow kinds to be as intricate as types, allowing explicit quantification
-    over kind variables, higher-rank kinds, and the use of type synonyms and
-    families in kinds, among other features.
+    The extension :extension:`TypeInType` is now deprecated: its sole effect is
+    to switch on :extension:`PolyKinds`
+    (and hence :extension:`KindSignatures`) and :extension:`DataKinds`.
 
-.. ghc-flag:: -XPolyKinds
-    :shortdesc: Enable :ref:`kind polymorphism <kind-polymorphism>`.
-        Implies :ghc-flag:`-XKindSignatures`.
-    :type: dynamic
-    :reverse: -XNoPolyKinds
-    :category:
+.. extension:: PolyKinds
+    :shortdesc: Enable kind polymorphism.
+        Implies :extension:`KindSignatures`.
 
-    :implies: :ghc-flag:`-XKindSignatures`
+    :implies: :extension:`KindSignatures`
     :since: 7.4.1
 
     Allow kind polymorphic types.
@@ -8414,31 +8806,6 @@ although it is a conservative extension beyond standard Haskell. The extensions
 above simply enable syntax and tweak the inference algorithm to allow users to
 take advantage of the extra expressiveness of GHC's kind system.
 
-The difference between :ghc-flag:`-XTypeInType` and :ghc-flag:`-XPolyKinds`
----------------------------------------------------------------------------
-
-It is natural to consider :ghc-flag:`-XTypeInType` as an extension of
-:ghc-flag:`-XPolyKinds`. The latter simply enables fewer features of GHC's
-rich kind system than does the former. The need for two separate extensions
-stems from their history: :ghc-flag:`-XPolyKinds` was introduced for GHC 7.4,
-when it was experimental and temperamental. The wrinkles were smoothed out for
-GHC 7.6. :ghc-flag:`-XTypeInType` was introduced for GHC 8.0, and is currently
-experimental and temperamental, with the wrinkles to be smoothed out in due
-course. The intent of having the two extensions is that users can rely on
-:ghc-flag:`-XPolyKinds` to work properly while being duly sceptical of
-:ghc-flag:`-XTypeInType`. In particular, we recommend enabling
-:ghc-flag:`-dcore-lint` whenever using :ghc-flag:`-XTypeInType`; that flag
-turns on a set of internal checks within GHC that will discover bugs in the
-implementation of :ghc-flag:`-XTypeInType`. Please report bugs at `our bug
-tracker <https://ghc.haskell.org/trac/ghc/wiki/ReportABug>`__.
-
-Although we have tried to allow the new behavior only when
-:ghc-flag:`-XTypeInType` is enabled, some particularly thorny cases may have
-slipped through. It is thus possible that some construct is available in GHC
-8.0 with :ghc-flag:`-XPolyKinds` that was not possible in GHC 7.x. If you spot
-such a case, you are welcome to submit that as a bug as well. We flag
-newly-available capabilities below.
-
 Overview of kind polymorphism
 -----------------------------
 
@@ -8446,22 +8813,22 @@ Consider inferring the kind for ::
 
   data App f a = MkApp (f a)
 
-In Haskell 98, the inferred kind for ``App`` is ``(* -> *) -> * -> *``.
-But this is overly specific, because another suitable Haskell 98 kind for
-``App`` is ``((* -> *) -> *) -> (* -> *) -> *``, where the kind assigned
-to ``a`` is ``* -> *``. Indeed, without kind signatures
-(:ghc-flag:`-XKindSignatures`), it is necessary to use a dummy constructor
-to get a Haskell compiler to infer the second kind. With kind polymorphism
-(:ghc-flag:`-XPolyKinds`), GHC infers the kind ``forall k. (k -> *) -> k -> *``
-for ``App``, which is its most general kind.
+In Haskell 98, the inferred kind for ``App`` is ``(Type -> Type) -> Type ->
+Type``. But this is overly specific, because another suitable Haskell 98 kind
+for ``App`` is ``((Type -> Type) -> Type) -> (Type -> Type) -> Type``, where the
+kind assigned to ``a`` is ``Type -> Type``. Indeed, without kind signatures
+(:extension:`KindSignatures`), it is necessary to use a dummy constructor to get
+a Haskell compiler to infer the second kind. With kind polymorphism
+(:extension:`PolyKinds`), GHC infers the kind ``forall k. (k -> Type) -> k ->
+Type`` for ``App``, which is its most general kind.
 
 Thus, the chief benefit of kind polymorphism is that we can now infer these
 most general kinds and use ``App`` at a variety of kinds: ::
 
-  App Maybe Int   -- `k` is instantiated to *
+  App Maybe Int   -- `k` is instantiated to Type
 
-  data T a = MkT (a Int)    -- `a` is inferred to have kind (* -> *)
-  App T Maybe     -- `k` is instantiated to (* -> *)
+  data T a = MkT (a Int)    -- `a` is inferred to have kind (Type -> Type)
+  App T Maybe     -- `k` is instantiated to (Type -> Type)
 
 Overview of Type-in-Type
 ------------------------
@@ -8476,16 +8843,15 @@ between types and kinds is a hallmark of dependently typed languages.
 Full dependently typed languages also remove the difference between expressions
 and types, but doing that in GHC is a story for another day.
 
-One simplification allowed by combining types and kinds is that the type
-of ``*`` is just ``*``. It is true that the ``* :: *`` axiom can lead to
-non-termination, but this is not a problem in GHC, as we already have other
-means of non-terminating programs in both types and expressions. This
-decision (among many, many others) *does* mean that despite the expressiveness
-of GHC's type system, a "proof" you write in Haskell is not an irrefutable
-mathematical proof. GHC promises only partial correctness, that if your
-programs compile and run to completion, their results indeed have the types
-assigned. It makes no claim about programs that do not finish in a finite
-amount of time.
+One simplification allowed by combining types and kinds is that the type of
+``Type`` is just ``Type``. It is true that the ``Type :: Type`` axiom can lead
+to non-termination, but this is not a problem in GHC, as we already have other
+means of non-terminating programs in both types and expressions. This decision
+(among many, many others) *does* mean that despite the expressiveness of GHC's
+type system, a "proof" you write in Haskell is not an irrefutable mathematical
+proof. GHC promises only partial correctness, that if your programs compile and
+run to completion, their results indeed have the types assigned. It makes no
+claim about programs that do not finish in a finite amount of time.
 
 To learn more about this decision and the design of GHC under the hood
 please see the `paper <http://www.seas.upenn.edu/~sweirich/papers/fckinds.pdf>`__
@@ -8494,9 +8860,10 @@ introducing this kind system to GHC/Haskell.
 Principles of kind inference
 ----------------------------
 
-Generally speaking, when :ghc-flag:`-XPolyKinds` is on, GHC tries to infer the
+Generally speaking, when :extension:`PolyKinds` is on, GHC tries to infer the
 most general kind for a declaration.
-In this case the definition has a right-hand side to inform kind
+In many cases (for example, in a datatype declaration)
+the definition has a right-hand side to inform kind
 inference. But that is not always the case. Consider ::
 
     type family F a
@@ -8504,42 +8871,114 @@ inference. But that is not always the case. Consider ::
 Type family declarations have no right-hand side, but GHC must still
 infer a kind for ``F``. Since there are no constraints, it could infer
 ``F :: forall k1 k2. k1 -> k2``, but that seems *too* polymorphic. So
-GHC defaults those entirely-unconstrained kind variables to ``*`` and we
-get ``F :: * -> *``. You can still declare ``F`` to be kind-polymorphic
+GHC defaults those entirely-unconstrained kind variables to ``Type`` and we
+get ``F :: Type -> Type``. You can still declare ``F`` to be kind-polymorphic
 using kind signatures: ::
 
-    type family F1 a                -- F1 :: * -> *
-    type family F2 (a :: k)         -- F2 :: forall k. k -> *
-    type family F3 a :: k           -- F3 :: forall k. * -> k
+    type family F1 a                -- F1 :: Type -> Type
+    type family F2 (a :: k)         -- F2 :: forall k. k -> Type
+    type family F3 a :: k           -- F3 :: forall k. Type -> k
     type family F4 (a :: k1) :: k2  -- F4 :: forall k1 k2. k1 -> k2
 
 The general principle is this:
 
--  *When there is a right-hand side, GHC infers the most polymorphic
-   kind consistent with the right-hand side.* Examples: ordinary data
+-  When there is a right-hand side, GHC infers the most polymorphic
+   kind consistent with the right-hand side. Examples: ordinary data
    type and GADT declarations, class declarations. In the case of a
    class declaration the role of "right hand side" is played by the
    class method signatures.
 
--  *When there is no right hand side, GHC defaults argument and result
-   kinds to ``*``, except when directed otherwise by a kind signature*.
+-  When there is no right hand side, GHC defaults argument and result
+   kinds to ``Type``, except when directed otherwise by a kind signature.
    Examples: data and open type family declarations.
 
 This rule has occasionally-surprising consequences (see
-:ghc-ticket:`10132`. ::
+:ghc-ticket:`10132`). ::
 
     class C a where    -- Class declarations are generalised
                        -- so C :: forall k. k -> Constraint
       data D1 a        -- No right hand side for these two family
       type F1 a        -- declarations, but the class forces (a :: k)
-                       -- so   D1, F1 :: forall k. k -> *
+                       -- so   D1, F1 :: forall k. k -> Type
 
-    data D2 a   -- No right-hand side so D2 :: * -> *
-    type F2 a   -- No right-hand side so F2 :: * -> *
+    data D2 a   -- No right-hand side so D2 :: Type -> Type
+    type F2 a   -- No right-hand side so F2 :: Type -> Type
 
 The kind-polymorphism from the class declaration makes ``D1``
 kind-polymorphic, but not so ``D2``; and similarly ``F1``, ``F1``.
 
+.. _inferring-variable-order:
+
+Inferring the order of variables in a type/class declaration
+------------------------------------------------------------
+
+It is possible to get intricate dependencies among the type variables
+introduced in a type or class declaration. Here is an example::
+
+  data T a (b :: k) c = MkT (a c)
+
+After analysing this declaration, GHC will discover that ``a`` and
+``c`` can be kind-polymorphic, with ``a :: k2 -> Type`` and
+``c :: k2``. We thus infer the following kind::
+
+  T :: forall {k2 :: Type} (k :: Type). (k2 -> Type) -> k -> k2 -> Type
+
+Note that ``k2`` is placed *before* ``k``, and that ``k`` is placed *before*
+``a``. Also, note that ``k2`` is written here in braces. As explained with
+:extension:`TypeApplications` (:ref:`inferred-vs-specified`),
+type and kind variables that GHC generalises
+over, but not written in the original program, are not available for visible
+type application. (These are called *inferred* variables.)
+Such variables are written in braces with
+:ghc-flag:`-fprint-explicit-foralls` enabled.
+
+The general principle is this:
+
+  * Variables not available for type application come first.
+
+  * Then come variables the user has written, implicitly brought into scope
+    in a type variable's kind.
+
+  * Lastly come the normal type variables of a declaration.
+
+  * Variables not given an explicit ordering by the user are sorted according
+    to ScopedSort (:ref:`ScopedSort`).
+
+With the ``T`` example above, we could bind ``k`` *after* ``a``; doing so
+would not violate dependency concerns. However, it would violate our general
+principle, and so ``k`` comes first.
+
+Sometimes, this ordering does not respect dependency. For example::
+
+  data T2 k (a :: k) (c :: Proxy '[a, b])
+
+It must be that ``a`` and ``b`` have the same kind. Note also that ``b``
+is implicitly declared in ``c``\'s kind. Thus, according to our general
+principle, ``b`` must come *before* ``k``. However, ``b`` *depends on*
+``k``. We thus reject ``T2`` with a suitable error message.
+
+In associated types, we order the type variables as if the type family was a
+top-level declaration, ignoring the visibilities of the class's type variable
+binders. Here is an example: ::
+
+  class C (a :: k) b where
+    type F (c :: j) (d :: Proxy m) a b
+
+We infer these kinds::
+
+  C :: forall {k1 :: Type} (k :: Type). k -> k1 -> Constraint
+  F :: forall {k1 :: Type} {k2 :: Type} {k3 :: Type} j (m :: k1).
+       j -> Proxy m -> k2 -> k3 -> Type
+
+Note that the kind of ``a`` is specified in the kind of ``C`` but inferred in
+the kind of ``F``.
+
+The "general principle" described here is meant to make all this more
+predictable for users. It would not be hard to extend GHC to relax
+this principle. If you should want a change here, consider writing
+a `proposal <https://github.com/ghc-proposals/ghc-proposals/>`_ to
+do so.
+
 .. index::
    single: CUSK
    single: complete user-supplied kind signature
@@ -8553,21 +8992,21 @@ Just as in type inference, kind inference for recursive types can only
 use *monomorphic* recursion. Consider this (contrived) example: ::
 
     data T m a = MkT (m a) (T Maybe (m a))
-    -- GHC infers kind  T :: (* -> *) -> * -> *
+    -- GHC infers kind  T :: (Type -> Type) -> Type -> Type
 
 The recursive use of ``T`` forced the second argument to have kind
-``*``. However, just as in type inference, you can achieve polymorphic
+``Type``. However, just as in type inference, you can achieve polymorphic
 recursion by giving a *complete user-supplied kind signature* (or CUSK)
 for ``T``. A CUSK is present when all argument kinds and the result kind
 are known, without any need for inference. For example: ::
 
-    data T (m :: k -> *) :: k -> * where
+    data T (m :: k -> Type) :: k -> Type where
       MkT :: m a -> T Maybe (m a) -> T m a
 
 The complete user-supplied kind signature specifies the polymorphic kind
 for ``T``, and this signature is used for all the calls to ``T``
 including the recursive ones. In particular, the recursive use of ``T``
-is at kind ``*``.
+is at kind ``Type``.
 
 What exactly is considered to be a "complete user-supplied kind
 signature" for a type constructor? These are the forms:
@@ -8578,35 +9017,30 @@ signature" for a type constructor? These are the forms:
    annotation does not affect whether or not the declaration has a
    complete signature. ::
 
-       data T1 :: (k -> *) -> k -> *       where ...
-       -- Yes;  T1 :: forall k. (k->*) -> k -> *
+       data T1 :: (k -> Type) -> k -> Type       where ...
+       -- Yes;  T1 :: forall k. (k->Type) -> k -> Type
 
-       data T2 (a :: k -> *) :: k -> *     where ...
-       -- Yes;  T2 :: forall k. (k->*) -> k -> *
+       data T2 (a :: k -> Type) :: k -> Type     where ...
+       -- Yes;  T2 :: forall k. (k->Type) -> k -> Type
 
-       data T3 (a :: k -> *) (b :: k) :: * where ...
-       -- Yes;  T3 :: forall k. (k->*) -> k -> *
+       data T3 (a :: k -> Type) (b :: k) :: Type where ...
+       -- Yes;  T3 :: forall k. (k->Type) -> k -> Type
 
-       data T4 (a :: k -> *) (b :: k)      where ...
-       -- Yes;  T4 :: forall k. (k->*) -> k -> *
+       data T4 (a :: k -> Type) (b :: k)      where ...
+       -- Yes;  T4 :: forall k. (k->Type) -> k -> Type
 
-       data T5 a (b :: k) :: *             where ...
+       data T5 a (b :: k) :: Type             where ...
        -- No;  kind is inferred
 
        data T6 a b                         where ...
        -- No;  kind is inferred
 
--  For a datatype with a top-level ``::`` when :ghc-flag:`-XTypeInType`
-   is in effect: all kind variables introduced after the ``::`` must
-   be explicitly quantified. ::
-
-     -- -XTypeInType is on
-     data T1 :: k -> *            -- No CUSK: `k` is not explicitly quantified
-     data T2 :: forall k. k -> *  -- CUSK: `k` is bound explicitly
-     data T3 :: forall (k :: *). k -> *   -- still a CUSK
+-  For a datatype with a top-level ``::``: all kind variables introduced after
+   the ``::`` must be explicitly quantified. ::
 
-   Note that the first example would indeed have a CUSK without
-   :ghc-flag:`-XTypeInType`.
+     data T1 :: k -> Type            -- No CUSK: `k` is not explicitly quantified
+     data T2 :: forall k. k -> Type  -- CUSK: `k` is bound explicitly
+     data T3 :: forall (k :: Type). k -> Type   -- still a CUSK
 
 -  For a class, every type variable must be annotated with a kind.
 
@@ -8622,13 +9056,12 @@ signature" for a type constructor? These are the forms:
    signature -- no inference can be done before detecting the signature.
 
 -  An un-associated open type or data family declaration *always* has a CUSK;
-   un-annotated type variables default to
-   kind ``*``: ::
+   un-annotated type variables default to kind ``Type``: ::
 
-       data family D1 a               -- D1 :: * -> *
-       data family D2 (a :: k)        -- D2 :: forall k. k -> *
-       data family D3 (a :: k) :: *   -- D3 :: forall k. k -> *
-       type family S1 a :: k -> *     -- S1 :: forall k. * -> k -> *
+       data family D1 a                  -- D1 :: Type -> Type
+       data family D2 (a :: k)           -- D2 :: forall k. k -> Type
+       data family D3 (a :: k) :: Type   -- D3 :: forall k. k -> Type
+       type family S1 a :: k -> Type     -- S1 :: forall k. Type -> k -> Type
 
 -  An associated type or data family declaration has a CUSK precisely if
    its enclosing class has a CUSK. ::
@@ -8643,21 +9076,15 @@ signature" for a type constructor? These are the forms:
    variables are annotated and a return kind (with a top-level ``::``)
    is supplied.
 
-With :ghc-flag:`-XTypeInType` enabled, it is possible to write a datatype
-that syntactically has a CUSK (according to the rules above)
-but actually requires some inference. As a very contrived example, consider ::
+It is possible to write a datatype that syntactically has a CUSK (according to
+the rules above) but actually requires some inference. As a very contrived
+example, consider ::
 
-  data Proxy a           -- Proxy :: forall k. k -> *
+  data Proxy a           -- Proxy :: forall k. k -> Type
   data X (a :: Proxy k)
 
-According to the rules above ``X`` has a CUSK. Yet, what is the kind of ``k``?
-It is impossible to know. This code is thus rejected as masquerading as having
-a CUSK, but not really. If you wish ``k`` to be polykinded, it is straightforward
-to specify this: ::
-
-  data X (a :: Proxy (k1 :: k2))
-
-The above definition is indeed fully fixed, with no masquerade.
+According to the rules above ``X`` has a CUSK. Yet, the kind of ``k`` is undetermined.
+It is thus quantified over, giving ``X`` the kind ``forall k1 (k :: k1). Proxy k -> Type``.
 
 Kind inference in closed type families
 --------------------------------------
@@ -8710,9 +9137,9 @@ for it: ::
 In the class declaration, nothing constrains the kind of the type ``a``,
 so it becomes a poly-kinded type variable ``(a :: k)``. Yet, in the
 instance declaration, the right-hand side of the associated type
-instance ``b -> b`` says that ``b`` must be of kind ``*``. GHC could
+instance ``b -> b`` says that ``b`` must be of kind ``Type``. GHC could
 theoretically propagate this information back into the instance head,
-and make that instance declaration apply only to type of kind ``*``, as
+and make that instance declaration apply only to type of kind ``Type``, as
 opposed to types of any kind. However, GHC does *not* do this.
 
 In short: GHC does *not* propagate kind information from the members of
@@ -8731,25 +9158,25 @@ When kind-checking a type, GHC considers only what is written in that
 type when figuring out how to generalise the type's kind.
 
 For example,
-consider these definitions (with :ghc-flag:`-XScopedTypeVariables`): ::
+consider these definitions (with :extension:`ScopedTypeVariables`): ::
 
-  data Proxy a    -- Proxy :: forall k. k -> *
+  data Proxy a    -- Proxy :: forall k. k -> Type
   p :: forall a. Proxy a
-  p = Proxy :: Proxy (a :: *)
+  p = Proxy :: Proxy (a :: Type)
 
 GHC reports an error, saying that the kind of ``a`` should be a kind variable
-``k``, not ``*``. This is because, by looking at the type signature
+``k``, not ``Type``. This is because, by looking at the type signature
 ``forall a. Proxy a``, GHC assumes ``a``'s kind should be generalised, not
-restricted to be ``*``. The function definition is then rejected for being
+restricted to be ``Type``. The function definition is then rejected for being
 more specific than its type signature.
 
 Explicit kind quantification
 ----------------------------
 
-Enabled by :ghc-flag:`-XTypeInType`, GHC now supports explicit kind quantification,
+Enabled by :extension:`PolyKinds`, GHC supports explicit kind quantification,
 as in these examples: ::
 
-  data Proxy :: forall k. k -> *
+  data Proxy :: forall k. k -> Type
   f :: (forall k (a :: k). Proxy a -> ()) -> Int
 
 Note that the second example has a ``forall`` that binds both a kind ``k`` and
@@ -8780,10 +9207,10 @@ Consider the type ::
 
 This datatype ``G`` is GADT-like in both its kind and its type. Suppose you
 have ``g :: G a``, where ``a :: k``. Then pattern matching to discover that
-``g`` is in fact ``GMaybe`` tells you both that ``k ~ (* -> *)`` and
-``a ~ Maybe``. The definition for ``G`` requires that :ghc-flag:`-XTypeInType`
+``g`` is in fact ``GMaybe`` tells you both that ``k ~ (Type -> Type)`` and
+``a ~ Maybe``. The definition for ``G`` requires that :extension:`PolyKinds`
 be in effect, but pattern-matching on ``G`` requires no extension beyond
-:ghc-flag:`-XGADTs`. That this works is actually a straightforward extension
+:extension:`GADTs`. That this works is actually a straightforward extension
 of regular GADTs and a consequence of the fact that kinds and types are the
 same.
 
@@ -8796,7 +9223,7 @@ for the datatype (:ref:`complete-kind-signatures`).
 Higher-rank kinds
 -----------------
 
-In concert with :ghc-flag:`-XRankNTypes`, GHC supports higher-rank kinds.
+In concert with :extension:`RankNTypes`, GHC supports higher-rank kinds.
 Here is an example::
 
   -- Heterogeneous propositional equality
@@ -8832,12 +9259,29 @@ In this redefinition, we give an explicit kind for ``(:~~:)``, deferring the cho
 of ``k2`` until after the first argument (``a``) has been given. With this declaration
 for ``(:~~:)``, the instance for ``HTestEquality`` is accepted.
 
+Another difference between higher-rank kinds and types can be found in their
+treatment of inferred and user-specified type variables. Consider the following
+program: ::
+
+  newtype Foo (f :: forall k. k -> Type) = MkFoo (f Int)
+  data Proxy a = Proxy
+
+  foo :: Foo Proxy
+  foo = MkFoo Proxy
+
+The kind of ``Foo``'s parameter is ``forall k. k -> Type``, but the kind of
+``Proxy`` is ``forall {k}. k -> Type``, where ``{k}`` denotes that the kind
+variable ``k`` is to be inferred, not specified by the user. (See
+:ref:`visible-type-application` for more discussion on the inferred-specified
+distinction). GHC does not consider ``forall k. k -> Type`` and
+``forall {k}. k -> Type`` to be equal at the kind level, and thus rejects
+``Foo Proxy`` as ill-kinded.
+
 Constraints in kinds
 --------------------
 
-As kinds and types are the same, kinds can now (with :ghc-flag:`-XTypeInType`)
-contain type constraints. Only equality constraints are currently supported,
-however. We expect this to extend to other constraints in the future.
+As kinds and types are the same, kinds can (with :extension:`TypeInType`)
+contain type constraints. However, only equality constraints are supported.
 
 Here is an example of a constrained kind: ::
 
@@ -8846,7 +9290,7 @@ Here is an example of a constrained kind: ::
     IsTypeLit Symbol = 'True
     IsTypeLit a      = 'False
 
-  data T :: forall a. (IsTypeLit a ~ 'True) => a -> * where
+  data T :: forall a. (IsTypeLit a ~ 'True) => a -> Type where
     MkNat    :: T 42
     MkSymbol :: T "Don't panic!"
 
@@ -8855,50 +9299,22 @@ we get an error that the equality constraint is not satisfied; ``Int`` is
 not a type literal. Note that explicitly quantifying with ``forall a`` is
 not necessary here.
 
-The kind ``*``
---------------
-
-The kind ``*`` classifies ordinary types. Without :ghc-flag:`-XTypeInType`,
-this identifier is always in scope when writing a kind. However, with
-:ghc-flag:`-XTypeInType`, a user may wish to use ``*`` in a type or a
-type operator ``*`` in a kind. To make this all more manageable, ``*``
-becomes an (almost) ordinary name with :ghc-flag:`-XTypeInType` enabled.
-So as not to cause naming collisions, it is not imported by default;
-you must ``import Data.Kind`` to get ``*`` (but only with :ghc-flag:`-XTypeInType`
-enabled).
-
-The only way ``*`` is unordinary is in its parsing. In order to be backward
-compatible, ``*`` is parsed as if it were an alphanumeric idenfifier; note
-that we do not write ``Int :: (*)`` but just plain ``Int :: *``. Due to the
-bizarreness with which ``*`` is parsed--and the fact that it is the only such
-operator in GHC--there are some corner cases that are
-not handled. We are aware of three:
-
-- In a Haskell-98-style data constructor, you must put parentheses around
-  ``*``, like this: ::
-
-    data Universe = Ty (*) | Num Int | ...
-
-- In an import/export list, you must put parentheses around ``*``, like this: ::
-
-    import Data.Kind ( type (*) )
-
-  Note that the keyword ``type`` there is just to disambiguate the import
-  from a term-level ``(*)``. (:ref:`explicit-namespaces`)
+The kind ``Type``
+-----------------
 
-- In an instance declaration head (the part after the word ``instance``), you
-  must parenthesize ``*``. This applies to all manners of instances, including
-  the left-hand sides of individual equations of a closed type family.
+.. extension:: StarIsType
+    :shortdesc: Treat ``*`` as ``Data.Kind.Type``.
 
-The ``Data.Kind`` module also exports ``Type`` as a synonym for ``*``.
-Now that type synonyms work in kinds, it is conceivable that we will deprecate
-``*`` when there is a good migration story for everyone to use ``Type``.
-If you like neither of these names, feel free to write your own synonym: ::
+    :since: 8.6.1
 
-  type Set = *   -- silly Agda programmers...
+    Treat the unqualified uses of the ``*`` type operator as nullary and desugar
+    to ``Data.Kind.Type``.
 
-All the affordances for ``*`` also apply to ``★``, the Unicode variant
-of ``*``.
+The kind ``Type`` (imported from ``Data.Kind``) classifies ordinary types. With
+:extension:`StarIsType` (currently enabled by default), ``*`` is desugared to
+``Type``, but using this legacy syntax is not recommended due to conflicts with
+:extension:`TypeOperators`. This also applies to ``★``, the Unicode variant of
+``*``.
 
 Inferring dependency in datatype declarations
 ---------------------------------------------
@@ -8931,19 +9347,44 @@ system does not have principal types) or merely practical (inferring this
 dependency is hard, given GHC's implementation). So, GHC takes the easy
 way out and requires a little help from the user.
 
-Kind defaulting without :ghc-flag:`-XPolyKinds`
+Inferring dependency in user-written ``forall``\s
+-------------------------------------------------
+
+A programmer may use ``forall`` in a type to introduce new quantified type
+variables. These variables may depend on each other, even in the same
+``forall``. However, GHC requires that the dependency be inferrable from
+the body of the ``forall``. Here are some examples::
+
+  data Proxy k (a :: k) = MkProxy   -- just to use below
+
+  f :: forall k a. Proxy k a        -- This is just fine. We see that (a :: k).
+  f = undefined
+
+  g :: Proxy k a -> ()              -- This is to use below.
+  g = undefined
+
+  data Sing a
+  h :: forall k a. Sing k -> Sing a -> ()  -- No obvious relationship between k and a
+  h _ _ = g (MkProxy :: Proxy k a)  -- This fails. We didn't know that a should have kind k.
+
+Note that in the last example, it's impossible to learn that ``a`` depends on ``k`` in the
+body of the ``forall`` (that is, the ``Sing k -> Sing a -> ()``). And so GHC rejects
+the program.
+
+Kind defaulting without :extension:`PolyKinds`
 -----------------------------------------------
 
-Without :ghc-flag:`-XPolyKinds` or :ghc-flag:`-XTypeInType` enabled, GHC
-refuses to generalise over kind variables. It thus defaults kind variables
-to ``*`` when possible; when this is not possible, an error is issued.
+Without :extension:`PolyKinds`, GHC refuses to generalise over kind variables.
+It thus defaults kind variables to ``Type`` when possible; when this is not
+possible, an error is issued.
 
 Here is an example of this in action: ::
 
-  {-# LANGUAGE TypeInType #-}
-  data Proxy a = P   -- inferred kind: Proxy :: k -> *
+  {-# LANGUAGE PolyKinds #-}
+  import Data.Kind (Type)
+  data Proxy a = P   -- inferred kind: Proxy :: k -> Type
   data Compose f g x = MkCompose (f (g x))
-    -- inferred kind: Compose :: (b -> *) -> (a -> b) -> a -> *
+    -- inferred kind: Compose :: (b -> Type) -> (a -> b) -> a -> Type
 
   -- separate module having imported the first
   {-# LANGUAGE NoPolyKinds, DataKinds #-}
@@ -8952,13 +9393,13 @@ Here is an example of this in action: ::
 In the last line, we use the promoted constructor ``'MkCompose``, which has
 kind ::
 
-  forall (a :: *) (b :: *) (f :: b -> *) (g :: a -> b) (x :: a).
+  forall (a :: Type) (b :: Type) (f :: b -> Type) (g :: a -> b) (x :: a).
     f (g x) -> Compose f g x
 
 Now we must infer a type for ``z``. To do so without generalising over kind
-variables, we must default the kind variables of ``'MkCompose``. We can
-easily default ``a`` and ``b`` to ``*``, but ``f`` and ``g`` would be ill-kinded
-if defaulted. The definition for ``z`` is thus an error.
+variables, we must default the kind variables of ``'MkCompose``. We can easily
+default ``a`` and ``b`` to ``Type``, but ``f`` and ``g`` would be ill-kinded if
+defaulted. The definition for ``z`` is thus an error.
 
 Pretty-printing in the presence of kind polymorphism
 ----------------------------------------------------
@@ -8988,16 +9429,16 @@ polymorphism.
 
 Here are the key definitions, all available from ``GHC.Exts``: ::
 
-  TYPE :: RuntimeRep -> *   -- highly magical, built into GHC
+  TYPE :: RuntimeRep -> Type   -- highly magical, built into GHC
 
   data RuntimeRep = LiftedRep     -- for things like `Int`
                   | UnliftedRep   -- for things like `Array#`
                   | IntRep        -- for `Int#`
-                 | TupleRep [RuntimeRep]  -- unboxed tuples, indexed by the representations of the elements
-                 | SumRep [RuntimeRep]    -- unboxed sums, indexed by the representations of the disjuncts
+                  | TupleRep [RuntimeRep]  -- unboxed tuples, indexed by the representations of the elements
+                  | SumRep [RuntimeRep]    -- unboxed sums, indexed by the representations of the disjuncts
                   | ...
 
-  type * = TYPE LiftedRep    -- * is just an ordinary type synonym
+  type Type = TYPE LiftedRep    -- Type is just an ordinary type synonym
 
 The idea is that we have a new fundamental type constant ``TYPE``, which
 is parameterised by a ``RuntimeRep``. We thus get ``Int# :: TYPE 'IntRep``
@@ -9035,7 +9476,7 @@ representation-polymorphic type.
 
 However, not all is lost. We can still do this: ::
 
-  ($) :: forall r (a :: *) (b :: TYPE r).
+  ($) :: forall r (a :: Type) (b :: TYPE r).
          (a -> b) -> a -> b
   f $ x = f x
 
@@ -9067,12 +9508,12 @@ stub out functions that return unboxed types.
 Printing levity-polymorphic types
 ---------------------------------
 
-.. ghc-flag:: -Wprint-explicit-runtime-rep
+.. ghc-flag:: -fprint-explicit-runtime-reps
     :shortdesc: Print ``RuntimeRep`` variables in types which are
         runtime-representation polymorphic.
     :type: dynamic
     :reverse: -fno-print-explicit-runtime-reps
-    :category:
+    :category: verbosity
 
     Print ``RuntimeRep`` parameters as they appear; otherwise, they are
     defaulted to ``'LiftedRep``.
@@ -9081,7 +9522,8 @@ Most GHC users will not need to worry about levity polymorphism
 or unboxed types. For these users, seeing the levity polymorphism
 in the type of ``$`` is unhelpful. And thus, by default, it is suppressed,
 by supposing all type variables of type ``RuntimeRep`` to be ``'LiftedRep``
-when printing, and printing ``TYPE 'LiftedRep`` as ``*``.
+when printing, and printing ``TYPE 'LiftedRep`` as ``Type`` (or ``*`` when
+:extension:`StarIsType` is on).
 
 Should you wish to see levity polymorphism in your types, enable
 the flag :ghc-flag:`-fprint-explicit-runtime-reps`.
@@ -9094,7 +9536,7 @@ Type-Level Literals
 GHC supports numeric and string literals at the type level, giving
 convenient access to a large number of predefined type-level constants.
 Numeric literals are of kind ``Nat``, while string literals are of kind
-``Symbol``. This feature is enabled by the :ghc-flag:`-XDataKinds` language
+``Symbol``. This feature is enabled by the :extension:`DataKinds` language
 extension.
 
 The kinds of the literals and all other low-level operations for this
@@ -9207,8 +9649,8 @@ the type level:
     GHC.TypeLits> natVal (lg (Proxy :: Proxy 2) (Proxy :: Proxy 8))
     3
 
-Constraints in types
-====================
+Equality constraints, Coercible, and the kind Constraint
+========================================================
 
 .. _equality-constraints:
 
@@ -9285,18 +9727,15 @@ denotes representational equality between ``t1`` and ``t2`` in the sense
 of Roles (:ref:`roles`). It is exported by :base-ref:`Data.Coerce.`, which also
 contains the documentation. More details and discussion can be found in the
 paper
-`"Safe Coercions" <http://www.cis.upenn.edu/~eir/papers/2014/coercible/coercible.pdf>`__.
+`"Safe Coercions" <https://www.microsoft.com/en-us/research/uploads/prod/2018/05/coercible-JFP.pdf>`__.
 
 .. _constraint-kind:
 
 The ``Constraint`` kind
 -----------------------
 
-.. ghc-flag:: -XConstraintKinds
-    :shortdesc: Enable a :ref:`kind of constraints <constraint-kind>`.
-    :type: dynamic
-    :reverse: -XNoConstraintKinds
-    :category:
+.. extension:: ConstraintKinds
+    :shortdesc: Enable a kind of constraints.
 
     :since: 7.4.1
 
@@ -9308,12 +9747,12 @@ arrow) have a very restricted syntax. They can only be:
 -  Class constraints, e.g. ``Show a``
 
 -  :ghc-flag:`Implicit parameter <-XImplicitParams>` constraints, e.g.
-   ``?x::Int`` (with the :ghc-flag:`-XImplicitParams` flag)
+   ``?x::Int`` (with the :extension:`ImplicitParams` extension)
 
 -  :ref:`Equality constraints <equality-constraints>`, e.g. ``a ~ Int``
-   (with the :ghc-flag:`-XTypeFamilies` or :ghc-flag:`-XGADTs` flag)
+   (with the :extension:`TypeFamilies` or :extension:`GADTs` extensions)
 
-With the :ghc-flag:`-XConstraintKinds` flag, GHC becomes more liberal in what it
+With the :extension:`ConstraintKinds` extension, GHC becomes more liberal in what it
 accepts as constraints in your program. To be precise, with this flag
 any *type* of the new kind ``Constraint`` can be used as a constraint.
 The following things have kind ``Constraint``:
@@ -9327,8 +9766,8 @@ The following things have kind ``Constraint``:
 
 -  Anything whose form is not yet known, but the user has declared to
    have kind ``Constraint`` (for which they need to import it from
-   ``GHC.Exts``). So for example
-   ``type Foo (f :: \* -> Constraint) = forall b. f b => b -> b``
+   ``Data.Kind``). So for example
+   ``type Foo (f :: Type -> Constraint) = forall b. f b => b -> b``
    is allowed, as well as examples involving type families: ::
 
        type family Typ a b :: Constraint
@@ -9367,9 +9806,267 @@ these two programs:
 
 You may write programs that use exotic sorts of constraints in instance
 contexts and superclasses, but to do so you must use
-:ghc-flag:`-XUndecidableInstances` to signal that you don't mind if the type
+:extension:`UndecidableInstances` to signal that you don't mind if the type
 checker fails to terminate.
 
+.. _quantified-constraints:
+
+Quantified constraints
+======================
+
+.. extension:: QuantifiedConstraints
+    :shortdesc: Allow ``forall`` quantifiers in constraints.
+
+    :since: 8.6.1
+
+    Allow constraints to quantify over types.
+
+The extension :extension:`QuantifiedConstraints` introduces **quantified constraints**,
+which give a new level of expressiveness in constraints. For example, consider ::
+
+ data Rose f a = Branch a (f (Rose f a))
+
+ instance (Eq a, ???) => Eq (Rose f a)
+   where
+     (Branch x1 c1) == (Branch x2 c2)
+        = x1==x1 && c1==c2
+
+From the ``x1==x2`` we need ``Eq a``, which is fine.  From ``c1==c2`` we need ``Eq (f (Rose f a))`` which
+is *not* fine in Haskell today; we have no way to solve such a constraint.
+
+:extension:`QuantifiedConstraints` lets us write this ::
+
+ instance (Eq a, forall b. (Eq b) => Eq (f b))
+        => Eq (Rose f a)
+   where
+     (Branch x1 c1) == (Branch x2 c2)
+        = x1==x1 && c1==c2
+
+Here, the quantified constraint ``forall b. (Eq b) => Eq (f b)`` behaves
+a bit like a local instance declaration, and makes the instance typeable.
+
+The paper `Quantified class constraints <http://i.cs.hku.hk/~bruno//papers/hs2017.pdf>`_ (by Bottu, Karachalias, Schrijvers, Oliveira, Wadler, Haskell Symposium 2017) describes this feature in technical detail, with examples, and so is a primary reference source for this proposal.
+
+Motivation
+----------------
+Introducing quantified constraints offers two main benefits:
+
+- Firstly, they enable terminating resolution where this was not possible before.  Consider for instance the following instance declaration for the general rose datatype ::
+
+   data Rose f x = Rose x (f (Rose f x))
+
+   instance (Eq a, forall b. Eq b => Eq (f b)) => Eq (Rose f a) where
+     (Rose x1 rs1) == (Rose x2 rs2) = x1 == x2 && rs1 == rs2
+
+  This extension allows us to write constraints of the form ``forall b. Eq b =>
+  Eq (f b)``, which is needed to solve the ``Eq (f (Rose f x))`` constraint
+  arising from the second usage of the ``(==)`` method.
+
+- Secondly, quantified constraints allow for more concise and precise specifications. As an example, consider the MTL type class for monad transformers::
+
+   class Trans t where
+     lift :: Monad m => m a -> (t m) a
+
+  The developer knows that a monad transformer takes a monad ``m`` into a new monad ``t m``.
+  But this property is not formally specified in the above declaration.
+  This omission becomes an issue when defining monad transformer composition::
+
+    newtype (t1 * t2) m a = C { runC :: t1 (t2 m) a }
+
+    instance (Trans t1, Trans t2) => Trans (t1 * t2) where
+      lift = C . lift . lift
+
+  The goal here is to ``lift`` from monad ``m`` to ``t2 m`` and
+  then ``lift`` this again into ``t1 (t2 m)``.
+  However, this second ``lift`` can only be accepted when ``(t2 m)`` is a monad
+  and there is no way of establishing that this fact universally holds.
+
+  Quantified constraints enable this property to be made explicit in the ``Trans``
+  class declaration::
+
+    class (forall m. Monad m => Monad (t m)) => Trans t where
+      lift :: Monad m => m a -> (t m) a
+
+This idea is very old; see Seciton 7 of `Derivable type classes <https://www.microsoft.com/en-us/research/publication/derivable-type-classes/>`_.
+
+Syntax changes
+----------------
+
+`Haskell 2010 <https://www.haskell.org/onlinereport/haskell2010/haskellch10.html#x17-18000010.5>`_ defines a ``context`` (the bit to the left of ``=>`` in a type) like this
+
+.. code-block:: none
+
+    context ::= class
+            |   ( class1, ..., classn )
+
+    class ::= qtycls tyvar
+            |  qtycls (tyvar atype1 ... atypen)
+
+We to extend ``class`` (warning: this is a rather confusingly named non-terminal symbol) with two extra forms, namely precisely what can appear in an instance declaration
+
+.. code-block:: none
+
+    class ::= ...
+          | [context =>] qtycls inst
+          | [context =>] tyvar inst
+
+The definition of ``inst`` is unchanged from the Haskell Report (roughly, just a type).
+The ``context =>`` part is optional.  That is the only syntactic change to the language.
+
+Notes:
+
+- Where GHC allows extensions instance declarations we allow exactly the same extensions to this new form of ``class``.  Specifically, with :extension:`ExplicitForAll` and :extension:`MultiParameterTypeClasses` the syntax becomes
+
+  .. code-block:: none
+
+    class ::= ...
+           | [forall tyavrs .] [context =>] qtycls inst1 ... instn
+           | [forall tyavrs .] [context =>] tyvar inst1 ... instn
+
+  Note that an explicit ``forall`` is often absolutely essential. Consider the rose-tree example ::
+
+    instance (Eq a, forall b. Eq b => Eq (f b)) => Eq (Rose f a) where ...
+
+  Without the ``forall b``, the type variable ``b`` would be quantified over the whole instance declaration, which is not what is intended.
+
+- One of these new quantified constraints can appear anywhere that any other constraint can, not just in instance declarations.  Notably, it can appear in a type signature for a value binding, data constructor, or expression.  For example ::
+
+   f :: (Eq a, forall b. Eq b => Eq (f b)) => Rose f a -> Rose f a -> Bool
+   f t1 t2 = not (t1 == t2)
+
+- The form with a type variable at the head allows this::
+
+   instance (forall xx. c (Free c xx)) => Monad (Free c) where
+       Free f >>= g = f g
+
+  See `Iceland Jack's summary <https://ghc.haskell.org/trac/ghc/ticket/14733#comment:6>`_.  The key point is that the bit to the right of the ``=>`` may be headed by a type *variable* (``c`` in this case), rather than a class.  It should not be one of the forall'd variables, though.
+
+  (NB: this goes beyond what is described in `the paper <http://i.cs.hku.hk/~bruno//papers/hs2017.pdf>`_, but does not seem to introduce any new technical difficulties.)
+
+
+Typing changes
+----------------
+
+See `the paper <http://i.cs.hku.hk/~bruno//papers/hs2017.pdf>`_.
+
+Superclasses
+----------------
+
+Suppose we have::
+
+     f :: forall m. (forall a. Ord a => Ord (m a)) => m Int -> Bool
+     f x = x == x
+
+From the ``x==x`` we need an ``Eq (m Int)`` constraint, but the context only gives us a way to figure out ``Ord (m a)`` constraints.  But from the given constraint ``forall a. Ord a => Ord (m a)`` we derive a second given constraint ``forall a. Ord a => Eq (m a)``, and from that we can readily solve ``Eq (m Int)``.  This process is very similar to the way that superclasses already work: given an ``Ord a`` constraint we derive a second given ``Eq a`` constraint.
+
+NB: This treatment of superclasses goes beyond `the paper <http://i.cs.hku.hk/~bruno//papers/hs2017.pdf>`_, but is specifically desired by users.
+
+Overlap
+-------------
+
+Quantified constraints can potentially lead to overlapping local axioms.
+Consider for instance the following example::
+
+ class A a where {}
+ class B a where {}
+ class C a where {}
+ class (A a => C a) => D a where {}
+ class (B a => C a) => E a where {}
+
+ class C a => F a where {}
+ instance (B a, D a, E a) => F a where {}
+
+When type checking the instance declaration for ``F a``,
+we need to check that the superclass ``C`` of ``F`` holds.
+We thus try to entail the constraint ``C a`` under the theory containing:
+
+- The instance axioms : ``(B a, D a, E a) => F a``
+- The local axioms from the instance context : ``B a``, ``D a`` and ``E a``
+- The closure of the superclass relation over these local axioms : ``A a => C a`` and ``B a => C a``
+
+However, the ``A a => C a`` and ``B a => C a`` axioms both match the wanted constraint ``C a``.
+There are several possible approaches for handling these overlapping local axioms:
+
+- **Pick first**.  We can simply select the **first matching axiom** we encounter.
+  In the above example, this would be ``A a => C a``.
+  We'd then need to entail ``A a``, for which we have no matching axioms available, causing the above program to be rejected.
+
+  But suppose we made a slight adjustment to the order of the instance context, putting ``E a`` before ``D a``::
+
+   instance (B a, E a, D a) => F a where {}
+
+  The first matching axiom we encounter while entailing ``C a``, is ``B a => C a``.
+  We have a local axiom ``B a`` available, so now the program is suddenly accepted.
+  This behaviour, where the ordering of an instance context determines
+  whether or not the program is accepted, seems rather confusing for the developer.
+
+- **Reject if in doubt**.  An alternative approach would be to check for overlapping axioms,
+  when solving a constraint.
+  When multiple matching axioms are discovered, we **reject the program**.
+  This approach is a bit conservative, in that it may reject working programs.
+  But it seem much more transparent towards the developer, who
+  can be presented with a clear message, explaining why the program is rejected.
+
+- **Backtracking**.  Lastly, a simple form of **backtracking** could be introduced.
+  We simply select the first matching axiom we encounter and when the entailment fails,
+  we backtrack and look for other axioms that might match the wanted constraint.
+
+  This seems the most intuitive and transparent approach towards the developer,
+  who no longer needs to concern himself with the fact that his code might contain
+  overlapping axioms or with the ordering of his instance contexts.  But backtracking
+  would apply equally to ordinary instance selection (in the presence of overlapping
+  instances), so it is a much more pervasive change, with substantial consequences
+  for the type inference engine.
+
+GHC adopts **Reject if in doubt** for now.  We can see how painful it
+is in practice, and try something more ambitious if necessary.
+
+Instance lookup
+-------------------
+
+In the light of the overlap decision, instance lookup works like this when
+trying to solve a class constraint ``C t``
+
+1. First see if there is a given un-quantified constraint ``C t``.  If so, use it to solve the constraint.
+
+2. If not, look at all the available given quantified constraints; if exactly one one matches ``C t``, choose it; if more than one matches, report an error.
+
+3. If no quantified constraints match, look up in the global instances, as described in :ref:`instance-resolution` and :ref:`instance-overlap`.
+
+Termination
+---------------
+
+GHC uses the :ref:`Paterson Conditions <instance-termination>` to ensure
+that instance resolution terminates. How are those rules modified for quantified
+constraints? In two ways.
+
+- Each quantified constraint, taken by itself, must satisfy the termination rules for an instance declaration.
+
+- After "for each class constraint ``(C t1 ... tn)``", add "or each quantified constraint ``(forall as. context => C t1 .. tn)``"
+
+Note that the second item only at the *head* of the quantified constraint, not its context.  Reason: the head is the new goal that has to be solved if we use the instance declaration.
+
+Of course, ``UndecidableInstances`` lifts the Paterson Conditions, as now.
+
+Coherence
+-----------
+
+Although quantified constraints are a little like local instance declarations, they differ
+in one big way: the local instances are written by the compiler, not the user, and hence
+cannot introduce incoherence.  Consider ::
+
+  f :: (forall a. Eq a => Eq (f a)) => f b -> f Bool
+  f x = ...rhs...
+
+In ``...rhs...`` there is, in effect a local instance for ``Eq (f a)`` for any ``a``.  But
+at a call site for ``f`` the compiler itself produces evidence to pass to ``f``. For example,
+if we called ``f Nothing``, then ``f`` is ``Maybe`` and the compiler must prove (at the
+call site) that ``forall a. Eq a => Eq (Maybe a)`` holds.  It can do this easily, by
+appealing to the existing instance declaration for ``Eq (Maybe a)``.
+
+In short, quantifed constraints do not introduce incoherence.
+
+
 .. _extensions-to-type-signatures:
 
 Extensions to type signatures
@@ -9380,13 +10077,10 @@ Extensions to type signatures
 Explicit universal quantification (forall)
 ------------------------------------------
 
-.. ghc-flag:: -XExplicitForAll
-    :shortdesc: Enable :ref:`explicit universal quantification <explicit-foralls>`.
-        Implied by :ghc-flag:`-XScopedTypeVariables`, :ghc-flag:`-XLiberalTypeSynonyms`,
-        :ghc-flag:`-XRankNTypes` and :ghc-flag:`-XExistentialQuantification`.
-    :type: dynamic
-    :reverse: -XNoExplicitForAll
-    :category:
+.. extension:: ExplicitForAll
+    :shortdesc: Enable explicit universal quantification.
+        Implied by :extension:`ScopedTypeVariables`, :extension:`LiberalTypeSynonyms`,
+        :extension:`RankNTypes` and :extension:`ExistentialQuantification`.
 
     :since: 6.12.1
 
@@ -9394,7 +10088,7 @@ Explicit universal quantification (forall)
     is implicit.
 
 Haskell type signatures are implicitly quantified. When the language
-option :ghc-flag:`-XExplicitForAll` is used, the keyword ``forall`` allows us to
+option :extension:`ExplicitForAll` is used, the keyword ``forall`` allows us to
 say exactly what this means. For example: ::
 
     g :: b -> b
@@ -9406,10 +10100,11 @@ means this: ::
 The two are treated identically, except that the latter may bring type variables
 into scope (see :ref:`scoped-type-variables`).
 
-Notes:
+This extension also enables explicit quantification of type and kind variables
+in :ref:`data-instance-declarations`, :ref:`type-instance-declarations`,
+:ref:`closed-type-families`, :ref:`assoc-inst`, and :ref:`rewrite-rules`.
 
-- With :ghc-flag:`-XExplicitForAll`, ``forall`` becomes a keyword; you can't use ``forall`` as a
-  type variable any more!
+Notes:
 
 - As well in type signatures, you can also use an explicit ``forall``
   in an instance declaration: ::
@@ -9429,16 +10124,16 @@ Notes:
 The context of a type signature
 -------------------------------
 
-The :ghc-flag:`-XFlexibleContexts` flag lifts the Haskell 98 restriction that
+The :extension:`FlexibleContexts` extension lifts the Haskell 98 restriction that
 the type-class constraints in a type signature must have the form *(class
 type-variable)* or *(class (type-variable type1 type2 ... typen))*. With
-:ghc-flag:`-XFlexibleContexts` these type signatures are perfectly okay
+:extension:`FlexibleContexts` these type signatures are perfectly okay
 ::
 
       g :: Eq [a] => ...
       g :: Ord (T a ()) => ...
 
-The flag :ghc-flag:`-XFlexibleContexts` also lifts the corresponding restriction
+The flag :extension:`FlexibleContexts` also lifts the corresponding restriction
 on class declarations (:ref:`superclass-rules`) and instance
 declarations (:ref:`instance-rules`).
 
@@ -9447,12 +10142,9 @@ declarations (:ref:`instance-rules`).
 Ambiguous types and the ambiguity check
 ---------------------------------------
 
-.. ghc-flag:: -XAllowAmbiguousTypes
-    :shortdesc: Allow the user to write :ref:`ambiguous types <ambiguity>`, and
+.. extension:: AllowAmbiguousTypes
+    :shortdesc: Allow the user to write ambiguous types, and
         the type inference engine to infer them.
-    :type: dynamic
-    :reverse: -XNoAllowAmbiguousTypes
-    :category:
 
     :since: 7.8.1
 
@@ -9470,7 +10162,7 @@ give rise to an ambiguous constraint. Indeed, the *only* purpose of the
 ambiguity check is to report functions that cannot possibly be called.
 We could soundly omit the ambiguity check on type signatures entirely,
 at the expense of delaying ambiguity errors to call sites. Indeed, the
-language extension :ghc-flag:`-XAllowAmbiguousTypes` switches off the ambiguity
+language extension :extension:`AllowAmbiguousTypes` switches off the ambiguity
 check.
 
 Ambiguity can be subtle. Consider this example which uses functional
@@ -9543,7 +10235,7 @@ because it gives rise to a constraint ``(D Bool beta)``, which is
 soluble by the ``(D Bool b)`` instance.
 
 Another way of getting rid of the ambiguity at the call site is to use
-the :ghc-flag:`-XTypeApplications` flag to specify the types. For example: ::
+the :extension:`TypeApplications` extension to specify the types. For example: ::
 
       class D a b where
         h :: b
@@ -9554,7 +10246,7 @@ the :ghc-flag:`-XTypeApplications` flag to specify the types. For example: ::
 Here ``a`` is ambiguous in the definition of ``D`` but later specified
 to be `Int` using type applications.
 
-:ghc-flag:`-XAllowAmbiguousTypes` allows you to switch off the ambiguity check.
+:extension:`AllowAmbiguousTypes` allows you to switch off the ambiguity check.
 However, even with ambiguity checking switched off, GHC will complain about a
 function that can *never* be called, such as this one: ::
 
@@ -9577,12 +10269,9 @@ function that can *never* be called, such as this one: ::
 Explicitly-kinded quantification
 --------------------------------
 
-.. ghc-flag:: -XKindSignatures
-    :shortdesc: Enable :ref:`kind signatures <kinding>`.
-        Implied by :ghc-flag:`-XTypeFamilies` and :ghc-flag:`-XPolyKinds`.
-    :type: dynamic
-    :reverse: -XNoKindSignatures
-    :category:
+.. extension:: KindSignatures
+    :shortdesc: Enable kind signatures.
+        Implied by :extension:`TypeFamilies` and :extension:`PolyKinds`.
 
     :since: 6.8.1
 
@@ -9602,36 +10291,34 @@ The only use for the ``Unused`` constructor was to force the correct
 kind for the type variable ``cxt``.
 
 GHC now instead allows you to specify the kind of a type variable
-directly, wherever a type variable is explicitly bound, with the flag
-:ghc-flag:`-XKindSignatures`.
+directly, wherever a type variable is explicitly bound, with the extension
+:extension:`KindSignatures`.
 
-This flag enables kind signatures in the following places:
+This extension enables kind signatures in the following places:
 
 -  ``data`` declarations: ::
 
-         data Set (cxt :: * -> *) a = Set [a]
+         data Set (cxt :: Type -> Type) a = Set [a]
 
 -  ``type`` declarations: ::
 
-         type T (f :: * -> *) = f Int
+         type T (f :: Type -> Type) = f Int
 
 -  ``class`` declarations: ::
 
-         class (Eq a) => C (f :: * -> *) a where ...
+         class (Eq a) => C (f :: Type -> Type) a where ...
 
 -  ``forall``\'s in type signatures: ::
 
-         f :: forall (cxt :: * -> *). Set cxt Int
+         f :: forall (cxt :: Type -> Type). Set cxt Int
 
-The parentheses are required. Some of the spaces are required too, to
-separate the lexemes. If you write ``(f::*->*)`` you will get a parse
-error, because ``::*->*`` is a single lexeme in Haskell.
+The parentheses are required.
 
 As part of the same extension, you can put kind annotations in types as
 well. Thus: ::
 
-       f :: (Int :: *) -> Int
-       g :: forall a. a -> (a :: *)
+       f :: (Int :: Type) -> Int
+       g :: forall a. a -> (a :: Type)
 
 The syntax is
 
@@ -9648,19 +10335,26 @@ The parentheses are required.
 Lexically scoped type variables
 ===============================
 
-.. ghc-flag:: -XScopedTypeVariables
-    :shortdesc: Enable :ref:`lexically-scoped type variables
-        <scoped-type-variables>`.
-    :type: dynamic
-    :reverse: -XNoScopedTypeVariables
-    :category:
+.. extension:: ScopedTypeVariables
+    :shortdesc: Enable lexically-scoped type variables.
 
-    :implies: :ghc-flag:`-XExplicitForAll`
+    :implies: :extension:`ExplicitForAll`
     :since: 6.8.1
 
     Enable lexical scoping of type variables explicitly introduced with
     ``forall``.
 
+.. tip::
+
+    ``ScopedTypeVariables`` breaks GHC's usual rule that explicit ``forall`` is optional and doesn't affect semantics.
+    For the :ref:`decl-type-sigs` (or :ref:`exp-type-sigs`) examples in this section,
+    the explicit ``forall`` is required.
+    (If omitted, usually the program will not compile; in a few cases it will compile but the functions get a different signature.)
+    To trigger those forms of ``ScopedTypeVariables``, the ``forall`` must appear against the top-level signature (or outer expression)
+    but *not* against nested signatures referring to the same type variables.
+
+    Explicit ``forall`` is not always required -- see :ref:`pattern signature equivalent <pattern-equiv-form>` for the example in this section, or :ref:`pattern-type-sigs`.
+
 GHC supports *lexically scoped type variables*, without which some type
 signatures are simply impossible to write. For example: ::
 
@@ -9679,6 +10373,21 @@ signature for ``ys``. In Haskell 98 it is not possible to declare a type
 for ``ys``; a major benefit of scoped type variables is that it becomes
 possible to do so.
 
+.. _pattern-equiv-form:
+
+An equivalent form for that example, avoiding explicit ``forall`` uses :ref:`pattern-type-sigs`: ::
+
+    f :: [a] -> [a]
+    f (xs :: [aa]) = xs ++ ys
+      where
+        ys :: [aa]
+        ys = reverse xs
+
+Unlike the ``forall`` form, type variable ``a`` from ``f``'s signature is not scoped over ``f``'s equation(s).
+Type variable ``aa`` bound by the pattern signature is scoped over the right-hand side of ``f``'s equation.
+(Therefore there is no need to use a distinct type variable; using ``a`` would be equivalent.)
+
+
 Overview
 --------
 
@@ -9745,6 +10454,26 @@ This only happens if:
    the definition of "``g``", so "``x::a``" means "``x::forall a. a``"
    by Haskell's usual implicit quantification rules.
 
+-  The type variable is quantified by the single, syntactically visible,
+   outermost ``forall`` of the type signature. For example, GHC will reject
+   all of the following examples: ::
+
+         f1 :: forall a. forall b. a -> [b] -> [b]
+         f1 _ (x:xs) = xs ++ [ x :: b ]
+
+         f2 :: forall a. a -> forall b. [b] -> [b]
+         f2 _ (x:xs) = xs ++ [ x :: b ]
+
+         type Foo = forall b. [b] -> [b]
+
+         f3 :: Foo
+         f3 (x:xs) = xs ++ [ x :: b ]
+
+   In ``f1`` and ``f2``, the type variable ``b`` is not quantified by the
+   outermost ``forall``, so it is not in scope over the bodies of the
+   functions. Neither is ``b`` in scope over the body of ``f3``, as the
+   ``forall`` is tucked underneath the ``Foo`` type synonym.
+
 -  The signature gives a type for a function binding or a bare variable
    binding, not a pattern binding. For example: ::
 
@@ -9757,10 +10486,12 @@ This only happens if:
          f3 :: forall a. [a] -> [a]
          Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ])   -- Not OK!
 
-   The binding for ``f3`` is a pattern binding, and so its type
-   signature does not bring ``a`` into scope. However ``f1`` is a
-   function binding, and ``f2`` binds a bare variable; in both cases the
-   type signature brings ``a`` into scope.
+   ``f1`` is a function binding, and ``f2`` binds a bare variable;
+   in both cases the type signature brings ``a`` into scope.
+   However the binding for ``f3`` is a pattern binding,
+   and so ``f3`` is a fresh variable brought into scope by the pattern,
+   not connected with top level ``f3``.
+   Then type variable ``a`` is not in scope of the right-hand side of ``Just f3 = ...``.
 
 .. _exp-type-sigs:
 
@@ -9806,17 +10537,28 @@ example: ::
     f xs = (n, zs)
       where
         (ys::[a], n) = (reverse xs, length xs) -- OK
-        zs::[a] = xs ++ ys                     -- OK
+        (zs::[a])    = xs ++ ys                     -- OK
 
-        Just (v::b) = ...  -- Not OK; b is not in scope
+        Just (v::b)  = ...  -- Not OK; b is not in scope
 
 Here, the pattern signatures for ``ys`` and ``zs`` are fine, but the one
 for ``v`` is not because ``b`` is not in scope.
 
 However, in all patterns *other* than pattern bindings, a pattern type
 signature may mention a type variable that is not in scope; in this
-case, *the signature brings that type variable into scope*. This is
-particularly important for existential data constructors. For example: ::
+case, *the signature brings that type variable into scope*. For example: ::
+
+    -- same f and g as above, now assuming that 'a' is not already in scope
+    f = \(x::Int, y::a) -> x           -- 'a' is in scope on RHS of ->
+
+    g (x::a) = x :: a
+
+    hh (Just (v :: b)) = v :: b
+
+The pattern type signature makes the type variable available on the right-hand side of the equation.
+
+Bringing type variables into scope is particularly important
+for existential data constructors. For example: ::
 
     data T = forall a. MkT [a]
 
@@ -9824,28 +10566,25 @@ particularly important for existential data constructors. For example: ::
     k (MkT [t::a]) =
         MkT t3
       where
-        t3::[a] = [t,t,t]
-
-Here, the pattern type signature ``(t::a)`` mentions a lexical type
-variable that is not already in scope. Indeed, it *cannot* already be in
-scope, because it is bound by the pattern match. GHC's rule is that in
-this situation (and only then), a pattern type signature can mention a
-type variable that is not already in scope; the effect is to bring it
-into scope, standing for the existentially-bound type variable.
-
-When a pattern type signature binds a type variable in this way, GHC
-insists that the type variable is bound to a *rigid*, or fully-known,
-type variable. This means that any user-written type signature always
-stands for a completely known type.
-
-If all this seems a little odd, we think so too. But we must have *some*
-way to bring such type variables into scope, else we could not name
-existentially-bound type variables in subsequent type signatures.
-
-This is (now) the *only* situation in which a pattern type signature is
-allowed to mention a lexical variable that is not already in scope. For
-example, both ``f`` and ``g`` would be illegal if ``a`` was not already
-in scope.
+        (t3::[a]) = [t,t,t]
+
+Here, the pattern type signature ``[t::a]`` mentions a lexical type
+variable that is not already in scope. Indeed, it *must not* already be in
+scope, because it is bound by the pattern match.
+The effect is to bring it into scope,
+standing for the existentially-bound type variable.
+
+It does seem odd that the existentially-bound type variable *must not*
+be already in scope. Contrast that usually name-bindings merely shadow
+(make a 'hole') in a same-named outer variable's scope.
+But we must have *some* way to bring such type variables into scope,
+else we could not name existentially-bound type variables
+in subsequent type signatures.
+
+Compare the two (identical) definitions for examples ``f``, ``g``;
+they are both legal whether or not ``a`` is already in scope.
+They differ in that *if* ``a`` is already in scope, the signature constrains
+the pattern, rather than the pattern binding the variable.
 
 .. _cls-inst-scoped-tyvars:
 
@@ -9877,11 +10616,8 @@ Bindings and generalisation
 Switching off the dreaded Monomorphism Restriction
 --------------------------------------------------
 
-.. ghc-flag:: -XNoMonomorphismRestriction
-    :shortdesc: Disable the :ref:`monomorphism restriction <monomorphism>`.
-    :type: dynamic
-    :reverse: -XMonomorphismRestriction
-    :category:
+.. extension:: NoMonomorphismRestriction
+    :shortdesc: Disable the monomorphism restriction.
 
     :default: on
     :since: 6.8.1
@@ -9892,7 +10628,7 @@ Switching off the dreaded Monomorphism Restriction
 Haskell's monomorphism restriction (see `Section
 4.5.5 <http://www.haskell.org/onlinereport/decls.html#sect4.5.5>`__ of
 the Haskell Report) can be completely switched off by
-:ghc-flag:`-XNoMonomorphismRestriction`. Since GHC 7.8.1, the monomorphism
+:extension:`NoMonomorphismRestriction`. Since GHC 7.8.1, the monomorphism
 restriction is switched off by default in GHCi's interactive options
 (see :ref:`ghci-interactive-options`).
 
@@ -9901,12 +10637,9 @@ restriction is switched off by default in GHCi's interactive options
 Let-generalisation
 ------------------
 
-.. ghc-flag:: -XMonoLocalBinds
-    :shortdesc: Enable :ref:`do not generalise local bindings <mono-local-binds>`.
-        Implied by :ghc-flag:`-XTypeFamilies` and :ghc-flag:`-XGADTs`.
-    :type: dynamic
-    :reverse: -XNoMonoLocalBinds
-    :category:
+.. extension:: MonoLocalBinds
+    :shortdesc: Enable do not generalise local bindings.
+        Implied by :extension:`TypeFamilies` and :extension:`GADTs`.
 
     :since: 6.12.1
 
@@ -9914,7 +10647,7 @@ Let-generalisation
 
 An ML-style language usually generalises the type of any ``let``\-bound or
 ``where``\-bound variable, so that it is as polymorphic as possible. With the
-flag :ghc-flag:`-XMonoLocalBinds` GHC implements a slightly more conservative
+extension :extension:`MonoLocalBinds` GHC implements a slightly more conservative
 policy, using the following rules:
 
 -  A variable is *closed* if and only if
@@ -9960,70 +10693,24 @@ papers <https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/jfp-
 "Let should not be generalised" and "Modular type inference with local
 assumptions", and a related `blog post <http://ghc.haskell.org/trac/ghc/blog/LetGeneralisationInGhc7>`__.
 
-The flag :ghc-flag:`-XMonoLocalBinds` is implied by :ghc-flag:`-XTypeFamilies`
-and :ghc-flag:`-XGADTs`. You can switch it off again with
-:ghc-flag:`-XNoMonoLocalBinds <-XMonoLocalBinds>` but type inference becomes
-less predicatable if you do so. (Read the papers!)
-
-.. _kind-generalisation:
-
-Kind generalisation
--------------------
-
-Just as :ghc-flag:`-XMonoLocalBinds` places limitations on when the *type* of a
-*term* is generalised (see :ref:`mono-local-binds`), it also limits when the
-*kind* of a *type signature* is generalised. Here is an example involving
-:ref:`type signatures on instance declarations <instance-sigs>`: ::
-
-    data Proxy a = Proxy
-    newtype Tagged s b = Tagged b
-
-    class C b where
-      c :: forall (s :: k). Tagged s b
-
-    instance C (Proxy a) where
-      c :: forall s. Tagged s (Proxy a)
-      c = Tagged Proxy
-
-With :ghc-flag:`-XMonoLocalBinds` enabled, this ``C (Proxy a)`` instance will
-fail to typecheck. The reason is that the type signature for ``c`` captures
-``a``, an outer-scoped type variable, which means the type signature is not
-closed. Therefore, the inferred kind for ``s`` will *not* be generalised, and
-as a result, it will fail to unify with the kind variable ``k`` which is
-specified in the declaration of ``c``. This can be worked around by specifying
-an explicit kind variable for ``s``, e.g., ::
-
-    instance C (Proxy a) where
-      c :: forall (s :: k). Tagged s (Proxy a)
-      c = Tagged Proxy
-
-or, alternatively: ::
-
-    instance C (Proxy a) where
-      c :: forall k (s :: k). Tagged s (Proxy a)
-      c = Tagged Proxy
-
-This declarations are equivalent using Haskell's implicit "add implicit
-foralls" rules (see :ref:`implicit-quantification`). The implicit foralls rules
-are purely syntactic and are quite separate from the kind generalisation
-described here.
+The extension :extension:`MonoLocalBinds` is implied by :extension:`TypeFamilies`
+and :extension:`GADTs`. You can switch it off again with
+:extension:`NoMonoLocalBinds <-XMonoLocalBinds>` but type inference becomes
+less predictable if you do so. (Read the papers!)
 
 .. _visible-type-application:
 
 Visible type application
 ========================
 
-.. ghc-flag:: -XTypeApplications
-    :shortdesc: Enable :ref:`type application syntax <visible-type-application>`.
-    :type: dynamic
-    :reverse: -XNoTypeApplications
-    :category:
+.. extension:: TypeApplications
+    :shortdesc: Enable type application syntax in terms and types.
 
     :since: 8.0.1
 
     Allow the use of type application syntax.
 
-The :ghc-flag:`-XTypeApplications` extension allows you to use
+The :extension:`TypeApplications` extension allows you to use
 *visible type application* in expressions. Here is an
 example: ``show (read @Int "5")``. The ``@Int``
 is the visible type application; it specifies the value of the type variable
@@ -10038,35 +10725,156 @@ is an identifier (the common case), its type is considered known only when
 the identifier has been given a type signature. If the identifier does
 not have a type signature, visible type application cannot be used.
 
-Here are the details:
+GHC also permits visible kind application, where users can declare the kind
+arguments to be instantiated in kind-polymorphic cases. Its usage parallels
+visible type application in the term level, as specified above.
+
+.. _inferred-vs-specified:
+
+Inferred vs. specified type variables
+-------------------------------------
+
+.. index::
+   single: type variable; inferred vs. specified
+
+GHC tracks a distinction between what we call *inferred* and *specified*
+type variables. Only specified type variables are available for instantiation
+with visible type application. An example illustrates this well::
+
+  f :: (Eq b, Eq a) => a -> b -> Bool
+  f x y = (x == x) && (y == y)
+
+  g x y = (x == x) && (y == y)
+
+The functions ``f`` and ``g`` have the same body, but only ``f`` is given
+a type signature. When GHC is figuring out how to process a visible type application,
+it must know what variable to instantiate. It thus must be able to provide
+an ordering to the type variables in a function's type.
+
+If the user has supplied a type signature, as in ``f``, then this is easy:
+we just take the ordering from the type signature, going left to right and
+using the first occurrence of a variable to choose its position within the
+ordering. Thus, the variables in ``f`` will be ``b``, then ``a``.
+
+In contrast, there is no reliable way to do this for ``g``; we will not know
+whether ``Eq a`` or ``Eq b`` will be listed first in the constraint in ``g``\'s
+type. In order to have visible type application be robust between releases of
+GHC, we thus forbid its use with ``g``.
+
+We say that the type variables in ``f`` are *specified*, while those in
+``g`` are *inferred*. The general rule is this: if the user has written
+a type variable in the source program, it is *specified*; if not, it is
+*inferred*.
+
+Thus rule applies in datatype declarations, too. For example, if we have
+``data Proxy a = Proxy`` (and :extension:`PolyKinds` is enabled), then
+``a`` will be assigned kind ``k``, where ``k`` is a fresh kind variable.
+Because ``k`` was not written by the user, it will be unavailable for
+type application in the type of the constructor ``Proxy``; only the ``a``
+will be available.
+
+When :ghc-flag:`-fprint-explicit-foralls` is enabled, inferred variables
+are printed in braces. Thus, the type of the data constructor ``Proxy``
+from the previous example would be ``forall {k} (a :: k). Proxy a``.
+We can observe this behavior in a GHCi session: ::
+
+  > :set -XTypeApplications -fprint-explicit-foralls
+  > let myLength1 :: Foldable f => f a -> Int; myLength1 = length
+  > :type +v myLength1
+  myLength1 :: forall (f :: * -> *) a. Foldable f => f a -> Int
+  > let myLength2 = length
+  > :type +v myLength2
+  myLength2 :: forall {a} {t :: * -> *}. Foldable t => t a -> Int
+  > :type +v myLength2 @[]
+
+  <interactive>:1:1: error:
+      • Cannot apply expression of type ‘t0 a0 -> Int’
+        to a visible type argument ‘[]’
+      • In the expression: myLength2 @[]
+
+Notice that since ``myLength1`` was defined with an explicit type signature,
+:ghci-cmd:`:type +v` reports that all of its type variables are available
+for type application. On the other hand, ``myLength2`` was not given a type
+signature. As a result, all of its type variables are surrounded with braces,
+and trying to use visible type application with ``myLength2`` fails.
+
+Also note the use of :ghci-cmd:`:type +v` in the GHCi session above instead
+of :ghci-cmd:`:type`. This is because :ghci-cmd:`:type` gives you the type
+that would be inferred for a variable assigned to the expression provided
+(that is, the type of ``x`` in ``let x = <expr>``). As we saw above with
+``myLength2``, this type will have no variables available to visible type
+application. On the other hand, :ghci-cmd:`:type +v` gives you the actual
+type of the expression provided. To illustrate this: ::
+
+  > :type myLength1
+  myLength1 :: forall {a} {f :: * -> *}. Foldable f => f a -> Int
+  > :type myLength2
+  myLength2 :: forall {a} {t :: * -> *}. Foldable t => t a -> Int
+
+Using :ghci-cmd:`:type` might lead one to conclude that none of the type
+variables in ``myLength1``'s type signature are available for type
+application. This isn't true, however! Be sure to use :ghci-cmd:`:type +v`
+if you want the most accurate information with respect to visible type
+application properties.
+
+.. index::
+   single: ScopedSort
+
+.. _ScopedSort:
+
+Ordering of specified variables
+-------------------------------
+
+In the simple case of the previous section, we can say that specified variables
+appear in left-to-right order. However, not all cases are so simple. Here are
+the rules in the subtler cases:
+
+- If an identifier's type has a ``forall``, then the order of type variables
+  as written in the ``forall`` is retained.
+
+- If the type signature includes any kind annotations (either on variable
+  binders or as annotations on types), any variables used in kind
+  annotations come before any variables never used in kind annotations.
+  This rule is not recursive: if there is an annotation within an annotation,
+  then the variables used therein are on equal footing. Examples::
 
-- If an identifier's type signature does not include an
-  explicit ``forall``, the type variable arguments appear
-  in the left-to-right order in which the variables appear in the type.
-  So, ``foo :: Monad m => a b -> m (a c)``
-  will have its type variables
-  ordered as ``m, a, b, c``.
+    f :: Proxy (a :: k) -> Proxy (b :: j) -> ()
+      -- as if f :: forall k j a b. ...
+
+    g :: Proxy (b :: j) -> Proxy (a :: (Proxy :: (k -> Type) -> Type) Proxy) -> ()
+      -- as if g :: forall j k b a. ...
+      -- NB: k is in a kind annotation within a kind annotation
 
 - If any of the variables depend on other variables (that is, if some
   of the variables are *kind* variables), the variables are reordered
   so that kind variables come before type variables, preserving the
   left-to-right order as much as possible. That is, GHC performs a
-  stable topological sort on the variables.
+  stable topological sort on the variables. Example::
+
+    h :: Proxy (a :: (j, k)) -> Proxy (b :: Proxy a) -> ()
+      -- as if h :: forall j k a b. ...
 
-  For example: if we have ``bar :: Proxy (a :: (j, k)) -> b``, then
-  the variables are ordered ``j``, ``k``, ``a``, ``b``.
+  In this example, all of ``a``, ``j``, and ``k`` are considered kind
+  variables and will always be placed before ``b``, a lowly type variable.
+  (Note that ``a`` is used in ``b``\'s kind.) Yet, even though ``a`` appears
+  lexically before ``j`` and ``k``, ``j`` and ``k`` are quantified first,
+  because ``a`` depends on ``j`` and ``k``. Note further that ``j`` and ``k``
+  are not reordered with respect to each other, even though doing so would
+  not violate dependency conditions.
 
-- Visible type application is available to instantiate only user-specified
-  type variables. This means that in ``data Proxy a = Proxy``, the unmentioned
-  kind variable used in ``a``'s kind is *not* available for visible type
-  application.
+  A "stable topological sort" here, we mean that we perform this algorithm
+  (which we call *ScopedSort*):
+
+  * Work left-to-right through the input list of type variables, with a cursor.
+  * If variable ``v`` at the cursor is depended on by any earlier variable ``w``,
+    move ``v`` immediately before the leftmost such ``w``.
 
 - Class methods' type arguments include the class type
   variables, followed by any variables an individual method is polymorphic
   in. So, ``class Monad m where return :: a -> m a`` means
   that ``return``'s type arguments are ``m, a``.
 
-- With the :ghc-flag:`-XRankNTypes` extension
+- With the :extension:`RankNTypes` extension
   (:ref:`universal-quantification`), it is possible to declare
   type arguments somewhere other than the beginning of a type. For example,
   we can have ``pair :: forall a. a -> forall b. b -> (a, b)``
@@ -10078,87 +10886,27 @@ Here are the details:
   application. If you want to specify only the second type argument to
   ``wurble``, then you can say ``wurble @_ @Int``.
   The first argument is a wildcard, just like in a partial type signature.
-  However, if used in a visible type application, it is *not*
-  necessary to specify :ghc-flag:`-XPartialTypeSignatures` and your
+  However, if used in a visible type application/visible kind application,
+  it is *not* necessary to specify :extension:`PartialTypeSignatures` and your
   code will not generate a warning informing you of the omitted type.
 
-- When printing types with :ghc-flag:`-fprint-explicit-foralls` enabled,
-  type variables not available for visible type application are printed
-  in braces. We can observe this behavior in a GHCi session: ::
-
-    > :set -XTypeApplications -fprint-explicit-foralls
-    > let myLength1 :: Foldable f => f a -> Int; myLength1 = length
-    > :type +v myLength1
-    myLength1 :: forall (f :: * -> *) a. Foldable f => f a -> Int
-    > let myLength2 = length
-    > :type +v myLength2
-    myLength2 :: forall {a} {t :: * -> *}. Foldable t => t a -> Int
-    > :type +v myLength2 @[]
-
-    <interactive>:1:1: error:
-        • Cannot apply expression of type ‘t0 a0 -> Int’
-          to a visible type argument ‘[]’
-        • In the expression: myLength2 @[]
-
-  Notice that since ``myLength1`` was defined with an explicit type signature,
-  :ghci-cmd:`:type +v` reports that all of its type variables are available
-  for type application. On the other hand, ``myLength2`` was not given a type
-  signature. As a result, all of its type variables are surrounded with braces,
-  and trying to use visible type application with ``myLength2`` fails.
-
-  Also note the use of :ghci-cmd:`:type +v` in the GHCi session above instead
-  of :ghci-cmd:`:type`. This is because :ghci-cmd:`:type` gives you the type
-  that would be inferred for a variable assigned to the expression provided
-  (that is, the type of ``x`` in ``let x = <expr>``). As we saw above with
-  ``myLength2``, this type will have no variables available to visible type
-  application. On the other hand, :ghci-cmd:`:type +v` gives you the actual
-  type of the expression provided. To illustrate this: ::
-
-    > :type myLength1
-    myLength1 :: forall {a} {f :: * -> *}. Foldable f => f a -> Int
-    > :type myLength2
-    myLength2 :: forall {a} {t :: * -> *}. Foldable t => t a -> Int
-
-  Using :ghci-cmd:`:type` might lead one to conclude that none of the type
-  variables in ``myLength1``'s type signature are available for type
-  application. This isn't true, however! Be sure to use :ghci-cmd:`:type +v`
-  if you want the most accurate information with respect to visible type
-  application properties.
-
-- Data constructors declared with GADT syntax follow different rules
-  for the time being; it is expected that these will be brought in line
-  with other declarations in the future. The rules for GADT
-  data constructors are as follows:
-
-     * All kind and type variables are considered specified and available for
-       visible type application.
-
-     * Universal variables always come first, in precisely the order they
-       appear in the type declaration. Universal variables that are
-       constrained by a GADT return type are not included in the data constructor.
-
-     * Existential variables come next. Their order is determined by a user-
-       written `forall`; or, if there is none, by taking the left-to-right order
-       in the data constructor's type and doing a stable topological sort.
+The section in this manual on kind polymorphism describes how variables
+in type and class declarations are ordered (:ref:`inferring-variable-order`).
 
 .. _implicit-parameters:
 
 Implicit parameters
 ===================
 
-.. ghc-flag:: -XImplicitParams
-    :shortdesc: Enable :ref:`Implicit Parameters <implicit-parameters>`.
-        Implies :ghc-flag:`-XFlexibleContexts` and :ghc-flag:`-XFlexibleInstances`.
-    :type: dynamic
-    :reverse: -XNoImplicitParams
-    :category:
+.. extension:: ImplicitParams
+    :shortdesc: Enable Implicit Parameters.
 
     :since: 6.8.1
 
     Allow definition of functions expecting implicit parameters.
 
 Implicit parameters are implemented as described in [Lewis2000]_ and enabled
-with the option :ghc-flag:`-XImplicitParams`. (Most of the following, still rather
+with the option :extension:`ImplicitParams`. (Most of the following, still rather
 incomplete, documentation is due to Jeff Lewis.)
 
 .. [Lewis2000]
@@ -10350,28 +11098,22 @@ a type signature for ``y``, then ``y`` will get type
 Arbitrary-rank polymorphism
 ===========================
 
-.. ghc-flag:: -XRankNTypes
-    :shortdesc: Enable :ref:`rank-N types <universal-quantification>`.
-        Implied by :ghc-flag:`-XImpredicativeTypes`.
-    :type: dynamic
-    :reverse: -XNoRankNTypes
-    :category:
+.. extension:: RankNTypes
+    :shortdesc: Enable rank-N types.
+        Implied by :extension:`ImpredicativeTypes`.
 
-    :implies: :ghc-flag:`-XExplicitForAll`
+    :implies: :extension:`ExplicitForAll`
     :since: 6.8.1
 
     Allow types of arbitrary rank.
 
-.. ghc-flag:: -XRank2Types
-    :shortdesc: Enable :ref:`rank-2 types <universal-quantification>`.
-        Synonym for :ghc-flag:`-XRankNTypes`.
-    :type: dynamic
-    :reverse: -XNoRank2Types
-    :category:
+.. extension:: Rank2Types
+    :shortdesc: Enable rank-2 types.
+        Synonym for :extension:`RankNTypes`.
 
     :since: 6.8.1
 
-    A deprecated alias of :ghc-flag:`-XRankNTypes`.
+    A deprecated alias of :extension:`RankNTypes`.
 
 GHC's type system supports *arbitrary-rank* explicit universal
 quantification in types. For example, all the following types are legal: ::
@@ -10397,8 +11139,8 @@ the left of the function arrow can be overloaded.
 The function ``f3`` has a rank-3 type; it has rank-2 types on the left
 of a function arrow.
 
-The language option :ghc-flag:`-XRankNTypes` (which implies
-:ghc-flag:`-XExplicitForAll`) enables higher-rank
+The language option :extension:`RankNTypes` (which implies
+:extension:`ExplicitForAll`) enables higher-rank
 types. That is, you can nest ``forall``\ s arbitrarily deep in function
 arrows. For example, a forall-type (also called a "type scheme"),
 including a type-class context, is legal:
@@ -10413,11 +11155,11 @@ including a type-class context, is legal:
 
 -  In a pattern type signature (see :ref:`scoped-type-variables`)
 
-The :ghc-flag:`-XRankNTypes` option is also required for any type with a
+The :extension:`RankNTypes` option is also required for any type with a
 ``forall`` or context to the right of an arrow (e.g.
 ``f :: Int -> forall a. a->a``, or ``g :: Int -> Ord a => a -> a``).
 Such types are technically rank 1, but are clearly not Haskell-98, and
-an extra flag did not seem worth the bother.
+an extra extension did not seem worth the bother.
 
 In particular, in ``data`` and ``newtype`` declarations the constructor
 arguments may be polymorphic types of any rank; see examples in
@@ -10426,8 +11168,8 @@ monomorphic. This is important because by default GHC will not
 instantiate type variables to a polymorphic type
 (:ref:`impredicative-polymorphism`).
 
-The obsolete language options :ghc-flag:`-XPolymorphicComponents` and
-:ghc-flag:`-XRank2Types` are synonyms for :ghc-flag:`-XRankNTypes`. They used to
+The obsolete language options :extension:`PolymorphicComponents` and
+:extension:`Rank2Types` are synonyms for :extension:`RankNTypes`. They used to
 specify finer distinctions that GHC no longer makes. (They should really elicit
 a deprecation warning, but they don't, purely to avoid the need to library
 authors to change their old flags specifications.)
@@ -10590,7 +11332,7 @@ the following pairs are equivalent: ::
                     h x y = y
                  in ...
 
-Notice that GHC always adds implicit quantfiers *at the outermost level*
+Notice that GHC always adds implicit quantifiers *at the outermost level*
 of a user-written type; it
 does *not* find the inner-most possible quantification
 point. For example: ::
@@ -10629,14 +11371,11 @@ so no implicit quantification happens, and the declaration is rejected
 Impredicative polymorphism
 ==========================
 
-.. ghc-flag:: -XImpredicativeTypes
-    :shortdesc: Enable :ref:`impredicative types <impredicative-polymorphism>`.
-        Implies :ghc-flag:`-XRankNTypes`.
-    :type: dynamic
-    :reverse: -XNoImpredicativeTypes
-    :category:
+.. extension:: ImpredicativeTypes
+    :shortdesc: Enable impredicative types.
+        Implies :extension:`RankNTypes`.
 
-    :implies: :ghc-flag:`-XRankNTypes`
+    :implies: :extension:`RankNTypes`
     :since: 6.10.1
 
     Allow impredicative polymorphic types.
@@ -10655,7 +11394,7 @@ that is not allowed. Instantiating polymorphic type variables with
 polymorphic types is called *impredicative polymorphism*.
 
 GHC has extremely flaky support for *impredicative polymorphism*,
-enabled with :ghc-flag:`-XImpredicativeTypes`. If it worked, this would mean
+enabled with :extension:`ImpredicativeTypes`. If it worked, this would mean
 that you *could* call a polymorphic function at a polymorphic type, and
 parameterise data structures over polymorphic types. For example: ::
 
@@ -10694,7 +11433,8 @@ written with a leading underscore (e.g., "``_``", "``_foo``",
 will generate an error message that describes which type is expected at
 the hole's location, information about the origin of any free type
 variables, and a list of local bindings that might help fill the hole
-with actual code. Typed holes are always enabled in GHC.
+and bindings in scope that fit the type of the hole that might help fill
+the hole with actual code. Typed holes are always enabled in GHC.
 
 The goal of typed holes is to help with writing Haskell code rather than
 to change the type system. Typed holes can be used to obtain extra
@@ -10716,11 +11456,12 @@ will fail with the following error: ::
         Found hole `_' with type: a
         Where: `a' is a rigid type variable bound by
                    the type signature for f :: a -> a at hole.hs:1:6
-        Relevant bindings include
-          f :: a -> a (bound at hole.hs:2:1)
-          x :: a (bound at hole.hs:2:3)
         In the expression: _
         In an equation for `f': f x = _
+        Relevant bindings include
+          x :: a (bound at hole.hs:2:3)
+          f :: a -> a (bound at hole.hs:2:1)
+        Valid hole fits include x :: a (bound at hole.hs:2:3)
 
 Here are some more details:
 
@@ -10757,13 +11498,36 @@ Here are some more details:
 
    .. code-block:: none
 
-       Foo.hs:5:15: error:
-           Found hole: _x :: Bool
-           Relevant bindings include
-             p :: Bool (bound at Foo.hs:3:6)
-             cons :: Bool -> [Bool] (bound at Foo.hs:3:1)
-
-       Foo.hs:5:20: error:
+       Foo.hs:3:21: error:
+          Found hole: _x :: Bool
+          Or perhaps ‘_x’ is mis-spelled, or not in scope
+          In the first argument of ‘(:)’, namely ‘_x’
+          In the second argument of ‘(:)’, namely ‘_x : y’
+          In the second argument of ‘(:)’, namely ‘True : _x : y’
+          Relevant bindings include
+            z :: Bool (bound at Foo.hs:3:6)
+          cons :: Bool -> [Bool] (bound at Foo.hs:3:1)
+          Valid hole fits include
+            z :: Bool (bound at mpt.hs:2:6)
+            otherwise :: Bool
+              (imported from ‘Prelude’ at mpt.hs:1:8-10
+              (and originally defined in ‘GHC.Base’))
+            False :: Bool
+              (imported from ‘Prelude’ at mpt.hs:1:8-10
+              (and originally defined in ‘GHC.Types’))
+            True :: Bool
+              (imported from ‘Prelude’ at mpt.hs:1:8-10
+              (and originally defined in ‘GHC.Types’))
+            maxBound :: forall a. Bounded a => a
+              with maxBound @Bool
+              (imported from ‘Prelude’ at mpt.hs:1:8-10
+              (and originally defined in ‘GHC.Enum’))
+            minBound :: forall a. Bounded a => a
+              with minBound @Bool
+              (imported from ‘Prelude’ at mpt.hs:1:8-10
+              (and originally defined in ‘GHC.Enum’))
+
+       Foo.hs:3:26: error:
            Variable not in scope: y :: [Bool]
 
    More information is given for explicit holes (i.e. ones that start
@@ -10781,24 +11545,33 @@ Here are some more details:
 
    .. code-block:: none
 
-       unbound.hs:1:8:
-           Found hole '_x' with type: a
-           Where: `a' is a rigid type variable bound by
-                      the inferred type of cons :: [a] at unbound.hs:1:1
-           Relevant bindings include cons :: [a] (bound at unbound.hs:1:1)
-           In the first argument of `(:)', namely `_x'
-           In the expression: _x : _x
-           In an equation for `cons': cons = _x : _x
-
-       unbound.hs:1:13:
-           Found hole '_x' with type: [a]
-           Arising from: an undeclared identifier `_x' at unbound.hs:1:13-14
-           Where: `a' is a rigid type variable bound by
-                      the inferred type of cons :: [a] at unbound.hs:1:1
-           Relevant bindings include cons :: [a] (bound at unbound.hs:1:1)
-           In the second argument of `(:)', namely `_x'
-           In the expression: _x : _x
-           In an equation for `cons': cons = _x : _x
+      unbound.hs:1:8:
+          Found hole '_x' with type: a
+          Where: `a' is a rigid type variable bound by
+                     the inferred type of cons :: [a] at unbound.hs:1:1
+          In the first argument of `(:)', namely `_x'
+          In the expression: _x : _x
+          In an equation for `cons': cons = _x : _x
+          Relevant bindings include cons :: [a] (bound at unbound.hs:1:1)
+
+      unbound.hs:1:13:
+          Found hole: _x :: [a]
+          Where: ‘a’ is a rigid type variable bound by
+                  the inferred type of cons :: [a]
+                  at unbound.hs:3:1-12
+          Or perhaps ‘_x’ is mis-spelled, or not in scope
+          In the second argument of ‘(:)’, namely ‘_x’
+          In the expression: _x : _x
+          In an equation for ‘cons’: cons = _x : _x
+          Relevant bindings include cons :: [a] (bound at unbound.hs:3:1)
+          Valid hole fits include
+            cons :: forall a. [a]
+              with cons @a
+              (defined at mpt.hs:3:1)
+            mempty :: forall a. Monoid a => a
+              with mempty @[a]
+              (imported from ‘Prelude’ at mpt.hs:1:8-10
+              (and originally defined in ‘GHC.Base’))
 
    Notice the two different types reported for the two different
    occurrences of ``_x``.
@@ -10822,11 +11595,67 @@ Here are some more details:
    implementation terms, they are reported by the renamer rather than
    the type checker.)
 
-There's a flag for controlling the amount of context information shown for
-typed holes:
+- The list of valid hole fits is found by checking which bindings in scope
+  would fit into the hole. As an example, compiling the following module with
+  GHC: ::
+
+      import Data.List (inits)
+
+      g :: [String]
+      g = _ "hello, world"
+
+  yields the errors:
+
+
+  .. code-block:: none
+
+
+    • Found hole: _ :: [Char] -> [String]
+    • In the expression: _
+      In the expression: _ "hello, world"
+      In an equation for ‘g’: g = _ "hello, world"
+    • Relevant bindings include g :: [String] (bound at mpt.hs:6:1)
+      Valid hole fits include
+        lines :: String -> [String]
+          (imported from ‘Prelude’ at mpt.hs:3:8-9
+           (and originally defined in ‘base-4.11.0.0:Data.OldList’))
+        words :: String -> [String]
+          (imported from ‘Prelude’ at mpt.hs:3:8-9
+           (and originally defined in ‘base-4.11.0.0:Data.OldList’))
+        inits :: forall a. [a] -> [[a]]
+          with inits @Char
+          (imported from ‘Data.List’ at mpt.hs:4:19-23
+           (and originally defined in ‘base-4.11.0.0:Data.OldList’))
+        repeat :: forall a. a -> [a]
+          with repeat @String
+          (imported from ‘Prelude’ at mpt.hs:3:8-9
+           (and originally defined in ‘GHC.List’))
+        fail :: forall (m :: * -> *). Monad m => forall a. String -> m a
+          with fail @[] @String
+          (imported from ‘Prelude’ at mpt.hs:3:8-9
+           (and originally defined in ‘GHC.Base’))
+        return :: forall (m :: * -> *). Monad m => forall a. a -> m a
+          with return @[] @String
+          (imported from ‘Prelude’ at mpt.hs:3:8-9
+           (and originally defined in ‘GHC.Base’))
+        pure :: forall (f :: * -> *). Applicative f => forall a. a -> f a
+          with pure @[] @String
+          (imported from ‘Prelude’ at mpt.hs:3:8-9
+           (and originally defined in ‘GHC.Base’))
+        read :: forall a. Read a => String -> a
+          with read @[String]
+          (imported from ‘Prelude’ at mpt.hs:3:8-9
+           (and originally defined in ‘Text.Read’))
+        mempty :: forall a. Monoid a => a
+          with mempty @([Char] -> [String])
+          (imported from ‘Prelude’ at mpt.hs:3:8-9
+           (and originally defined in ‘GHC.Base’))
+
+There are a few flags for controlling the amount of context information shown
+for typed holes:
 
 .. ghc-flag:: -fshow-hole-constraints
-    :shortdesc: Show constraints when reporting typed holes
+    :shortdesc: Show constraints when reporting typed holes.
     :type: dynamic
     :category: verbosity
 
@@ -10840,29 +11669,333 @@ typed holes:
 
     .. code-block:: none
 
-        show_constraints.hs:4:7: error:
-            • Found hole: _ :: Bool
-            • In the expression: _
-              In an equation for ‘f’: f x = _
-            • Relevant bindings include
-                x :: a (bound at show_constraints.hs:4:3)
-                f :: a -> Bool (bound at show_constraints.hs:4:1)
-              Constraints include
-                Eq a (from the type signature for:
-                             f :: Eq a => a -> Bool
-                      at show_constraints.hs:3:1-22)
+      show_constraints.hs:4:7: error:
+          • Found hole: _ :: Bool
+          • In the expression: _
+            In an equation for ‘f’: f x = _
+          • Relevant bindings include
+              x :: a (bound at show_constraints.hs:4:3)
+              f :: a -> Bool (bound at show_constraints.hs:4:1)
+            Constraints include Eq a (from show_constraints.hs:3:1-22)
+            Valid hole fits include
+              otherwise :: Bool
+              False :: Bool
+              True :: Bool
+              maxBound :: forall a. Bounded a => a
+                with maxBound @Bool
+              minBound :: forall a. Bounded a => a
+                with minBound @Bool
+
+.. _typed-hole-valid-hole-fits:
+
+Valid Hole Fits
+-------------------
+GHC sometimes suggests valid hole fits for typed holes, which is
+configurable by a few flags.
+
+.. ghc-flag:: -fno-show-valid-hole-fits
+    :shortdesc: Disables showing a list of valid hole fits for typed holes
+        in type error messages.
+    :type: dynamic
+    :category: verbosity
+
+    :default: off
+
+    This flag can be toggled to turn off the display of valid hole fits
+    entirely.
+
+.. ghc-flag:: -fmax-valid-hole-fits=⟨n⟩
+    :shortdesc: *default: 6.* Set the maximum number of valid hole fits for
+        typed holes to display in type error messages.
+    :type: dynamic
+    :reverse: -fno-max-valid-hole-fits
+    :category: verbosity
+
+    :default: 6
+
+    The list of valid hole fits is limited by displaying up to 6
+    hole fits per hole. The number of hole fits shown can be set by this
+    flag. Turning the limit off with :ghc-flag:`-fno-max-valid-hole-fits`
+    displays all found hole fits.
+
+
+.. ghc-flag:: -fshow-type-of-hole-fits
+    :shortdesc: Toggles whether to show the type of the valid hole fits
+       in the output.
+    :type: dynamic
+    :category: verbosity
+    :reverse: -fno-type-of-hole-fits
+
+    :default: on
+
+    By default, the hole fits show the type of the hole fit.
+    This can be turned off by the reverse of this flag.
+
+
+
+.. ghc-flag:: -fshow-type-app-of-hole-fits
+    :shortdesc: Toggles whether to show the type application of the valid
+       hole fits in the output.
+    :type: dynamic
+    :category: verbosity
+    :reverse: -fno-show-type-app-of-hole-fits
+
+    :default: on
+
+    By default, the hole fits show the type application needed to make
+    this hole fit fit the type of the hole, e.g. for the hole
+    ``(_ :: Int -> [Int])``, ``mempty`` is a hole fit with
+    ``mempty @(Int -> [Int])``. This can be toggled off with
+    the reverse of this flag.
+
+.. ghc-flag:: -fshow-docs-of-hole-fits
+    :shortdesc: Toggles whether to show the documentation of the valid
+       hole fits in the output.
+    :type: dynamic
+    :category: verbosity
+    :reverse: -fno-show-docs-of-hole-fits
+
+    :default: off
+
+    It can sometime be the case that the name and type of a valid hole
+    fit is not enough to realize what the fit stands for. This flag
+    adds the documentation of the fit to the message, if the
+    documentation is available (and the module from which the function
+    comes was compiled with the ``-haddock`` flag).
+
+.. ghc-flag:: -fshow-type-app-vars-of-hole-fits
+    :shortdesc: Toggles whether to show what type each quantified
+       variable takes in a valid hole fit.
+    :type: dynamic
+    :category: verbosity
+    :reverse: -fno-show-type-app-vars-of-hole-fits
+
+    :default: on
+
+    By default, the hole fits show the type application needed to make
+    this hole fit fit the type of the hole, e.g. for the hole
+    ``(_ :: Int -> [Int])``, ``mempty :: Monoid a => a`` is a hole fit
+    with ``mempty @(Int -> [Int])``. This flag toggles whether to show
+    ``a ~ (Int -> [Int])`` instead of ``mempty @(Int -> [Int])`` in the where
+    clause of the valid hole fit message.
+
+.. ghc-flag:: -fshow-provenance-of-hole-fits
+    :shortdesc: Toggles whether to show the provenance of the valid hole fits
+       in the output.
+    :type: dynamic
+    :category: verbosity
+    :reverse: -fno-show-provenance-of-hole-fits
+
+    :default: on
+
+    By default, each hole fit shows the provenance information of its
+    hole fit, i.e. where it was bound or defined, and what module
+    it was originally defined in if it was imported. This can be toggled
+    off using the reverse of this flag.
+
+
+.. ghc-flag:: -funclutter-valid-hole-fits
+    :shortdesc: Unclutter the list of valid hole fits by not showing
+        provenance nor type applications of suggestions.
+    :type: dynamic
+    :category: verbosity
+
+    :default: off
+
+    This flag can be toggled to decrease the verbosity of the valid hole fit
+    suggestions by not showing the provenance nor type application of the
+    suggestions.
+
+
+
+.. _typed-holes-refinement-hole-fits:
+
+Refinement Hole Fits
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the flag :ghc-flag:`-frefinement-level-hole-fits=⟨n⟩` is set to an
+``n`` larger than ``0``, GHC will offer up a list of valid refinement
+hole fits, which are valid hole fits that need up to ``n`` levels of
+additional refinement to be complete, where each level represents an additional
+hole in the hole fit that requires filling in.  As an example, consider the
+hole in ::
+
+  f :: [Integer] -> Integer
+  f = _
+
+When the refinement level is not set, it will only offer valid hole fits
+suggestions: ::
+
+  Valid hole fits include
+    f :: [Integer] -> Integer
+    head :: forall a. [a] -> a
+      with head @Integer
+    last :: forall a. [a] -> a
+      with last @Integer
+    maximum :: forall (t :: * -> *).
+                Foldable t =>
+                forall a. Ord a => t a -> a
+      with maximum @[] @Integer
+    minimum :: forall (t :: * -> *).
+                Foldable t =>
+                forall a. Ord a => t a -> a
+      with minimum @[] @Integer
+    product :: forall (t :: * -> *).
+                Foldable t =>
+                forall a. Num a => t a -> a
+      with product @[] @Integer
+    sum :: forall (t :: * -> *).
+            Foldable t =>
+            forall a. Num a => t a -> a
+      with sum @[] @Integer
+
+However, with :ghc-flag:`-frefinement-level-hole-fits=⟨n⟩` set to e.g. `1`,
+it will additionally offer up a list of refinement hole fits, in this case: ::
+
+  Valid refinement hole fits include
+    foldl1 (_ :: Integer -> Integer -> Integer)
+      with foldl1 @[] @Integer
+      where foldl1 :: forall (t :: * -> *).
+                      Foldable t =>
+                      forall a. (a -> a -> a) -> t a -> a
+    foldr1 (_ :: Integer -> Integer -> Integer)
+      with foldr1 @[] @Integer
+      where foldr1 :: forall (t :: * -> *).
+                      Foldable t =>
+                      forall a. (a -> a -> a) -> t a -> a
+    const (_ :: Integer)
+      with const @Integer @[Integer]
+      where const :: forall a b. a -> b -> a
+    ($) (_ :: [Integer] -> Integer)
+      with ($) @'GHC.Types.LiftedRep @[Integer] @Integer
+      where ($) :: forall a b. (a -> b) -> a -> b
+    fail (_ :: String)
+      with fail @((->) [Integer]) @Integer
+      where fail :: forall (m :: * -> *).
+                    Monad m =>
+                    forall a. String -> m a
+    return (_ :: Integer)
+      with return @((->) [Integer]) @Integer
+      where return :: forall (m :: * -> *). Monad m => forall a. a -> m a
+    (Some refinement hole fits suppressed;
+      use -fmax-refinement-hole-fits=N or -fno-max-refinement-hole-fits)
+
+Which shows that the hole could be replaced with e.g. ``foldl1 _``. While not
+fixing the hole, this can help users understand what options they have.
+
+.. ghc-flag:: -frefinement-level-hole-fits=⟨n⟩
+    :shortdesc: *default: off.* Sets the level of refinement of the
+         refinement hole fits, where level ``n`` means that hole fits
+         of up to ``n`` holes will be considered.
+    :type: dynamic
+    :reverse: -fno-refinement-level-hole-fits
+    :category: verbosity
+
+    :default: off
+
+    The list of valid refinement hole fits is generated by considering
+    hole fits with a varying amount of additional holes. The amount of
+    holes in a refinement can be set by this flag. If the flag is set to 0
+    or not set at all, no valid refinement hole fits will be suggested.
+
+.. ghc-flag:: -fabstract-refinement-hole-fits
+    :shortdesc: *default: off.* Toggles whether refinements where one or more
+         of the holes are abstract are reported.
+    :type: dynamic
+    :reverse: -fno-abstract-refinement-hole-fits
+    :category: verbosity
+
+    :default: off
+
+    Valid list of valid refinement hole fits can often grow large when
+    the refinement level is ``>= 2``, with holes like ``head _ _`` or
+    ``fst _ _``, which are valid refinements, but which are unlikely to be
+    relevant since one or more of the holes are still completely open, in that
+    neither the type nor kind of those holes are constrained by the proposed
+    identifier at all. By default, such holes are not reported. By turning this
+    flag on, such holes are included in the list of valid refinement hole fits.
+
+.. ghc-flag:: -fmax-refinement-hole-fits=⟨n⟩
+    :shortdesc: *default: 6.* Set the maximum number of refinement hole fits
+         for typed holes to display in type error messages.
+    :type: dynamic
+    :reverse: -fno-max-refinement-hole-fits
+    :category: verbosity
+
+    :default: 6
+
+    The list of valid refinement hole fits is limited by displaying up to 6
+    hole fits per hole. The number of hole fits shown can be set by this
+    flag. Turning the limit off with :ghc-flag:`-fno-max-refinement-hole-fits`
+    displays all found hole fits.
+
+.. ghc-flag:: -fshow-hole-matches-of-hole-fits
+    :shortdesc: Toggles whether to show the type of the additional holes
+       in refinement hole fits.
+    :type: dynamic
+    :category: verbosity
+    :reverse: -fno-show-hole-matches-of-hole-fits
+
+    :default: on
+
+    The types of the additional holes in refinement hole fits are displayed
+    in the output, e.g. ``foldl1 (_ :: a -> a -> a)`` is a refinement
+    for the hole ``_ :: [a] -> a``. If this flag is toggled off, the output
+    will display only ``foldl1 _``, which can be used as a direct replacement
+    for the hole, without requiring ``-XScopedTypeVariables``.
+
+
+
+
+Sorting Valid Hole Fits
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are currently two ways to sort valid hole fits.
+Sorting can be toggled with :ghc-flag:`-fsort-valid-hole-fits`
+
+.. ghc-flag:: -fno-sort-valid-hole-fits
+    :shortdesc: Disables the sorting of the list of valid hole fits for typed holes
+        in type error messages.
+    :type: dynamic
+    :category: verbosity
+
+    :default: off
+
+    By default the valid hole fits are sorted to show the most relevant
+    hole fits at the top of the list of valid hole fits. This can be
+    toggled off with this flag.
+
+.. ghc-flag:: -fsort-by-size-hole-fits
+    :shortdesc: Sort valid hole fits by size.
+    :type: dynamic
+    :reverse: -fno-sort-by-size-hole-fits
+
+    :default: on
+
+    Sorts by how big the types the quantified type variables in the type of the
+    function would have to be in order to match the type of the hole.
+
+
+.. ghc-flag:: -fsort-by-subsumption-hole-fits
+    :shortdesc: Sort valid hole fits by subsumption.
+    :type: dynamic
+    :reverse: -fno-sort-by-subsumption-hole-fits
+
+    :default: off
 
+    An alternative sort. Sorts by checking which hole fits subsume other
+    hole fits, such that if hole fit a could be used as hole fits for
+    hole fit b, then b appears before a in the output. It is more precise than
+    the default sort, but also a lot slower, since a subsumption check has to be
+    run for each pair of valid hole fits.
 
 .. _partial-type-signatures:
 
 Partial Type Signatures
 =======================
 
-.. ghc-flag:: -XPartialTypeSignatures
-    :shortdesc: Enable :ref:`partial type signatures <partial-type-signatures>`.
-    :type: dynamic
-    :reverse: -XNoPartialTypeSignatures
-    :category:
+.. extension:: PartialTypeSignatures
+    :shortdesc: Enable partial type signatures.
 
     :since: 7.10.1
 
@@ -10887,7 +12020,7 @@ type-checker to infer.
 
 By default, the type-checker will report an error message for each hole
 in a partial type signature, informing the programmer of the inferred
-type. When the :ghc-flag:`-XPartialTypeSignatures` flag is enabled, the
+type. When the :extension:`PartialTypeSignatures` extension is enabled, the
 type-checker will accept the inferred type for each hole, generating
 warnings instead of errors. Additionally, these warnings can be silenced
 with the :ghc-flag:`-Wno-partial-type-signatures <-Wpartial-type-signatures>`
@@ -10975,11 +12108,8 @@ generalised over, i.e. replaced by a fresh type variable, e.g.
 Named Wildcards
 ~~~~~~~~~~~~~~~
 
-.. ghc-flag:: -XNamedWildCards
-    :shortdesc: Enable :ref:`named wildcards <named-wildcards>`.
-    :type: dynamic
-    :reverse: -XNoNamedWildCards
-    :category:
+.. extension:: NamedWildCards
+    :shortdesc: Enable named wildcards.
 
     :since: 7.10.1
 
@@ -11024,13 +12154,13 @@ simplified away.
 
 By default, GHC (as the Haskell 2010 standard prescribes) parses
 identifiers starting with an underscore in a type as type variables. To
-treat them as named wildcards, the :ghc-flag:`-XNamedWildCards` flag should be
+treat them as named wildcards, the :extension:`NamedWildCards` extension should be
 enabled. The example below demonstrated the effect. ::
 
     foo :: _a -> _a
     foo _ = False
 
-Compiling this program without enabling :ghc-flag:`-XNamedWildCards` produces
+Compiling this program without enabling :extension:`NamedWildCards` produces
 the following error message complaining about the type variable ``_a``
 no matching the actual type ``Bool``.
 
@@ -11046,8 +12176,8 @@ no matching the actual type ``Bool``.
           In an equation for ‘foo’: foo _ = False
         • Relevant bindings include foo :: _a -> _a (bound at Test.hs:5:1)
 
-Compiling this program with :ghc-flag:`-XNamedWildCards` (as well as
-:ghc-flag:`-XPartialTypeSignatures`) enabled produces the following error
+Compiling this program with :extension:`NamedWildCards` (as well as
+:extension:`PartialTypeSignatures`) enabled produces the following error
 message reporting the inferred type of the named wildcard ``_a``.
 
 .. code-block:: none
@@ -11142,10 +12272,19 @@ Anonymous and named wildcards *can* occur on the left hand side of a
 type or data instance declaration;
 see :ref:`type-wildcards-lhs`.
 
-Anonymous wildcards are also allowed in visible type applications
-(:ref:`visible-type-application`). If you want to specify only the second type
-argument to ``wurble``, then you can say ``wurble @_ @Int`` where the first
-argument is a wildcard.
+Anonymous wildcards are also allowed in visible type applications/ visible kind
+applications (:ref:`visible-type-application`). If you want to specify only the
+second type argument to ``wurble``, then you can say ``wurble @_ @Int`` where
+the first argument is a wildcard.
+
+Standalone ``deriving`` declarations permit the use of a single,
+extra-constraints wildcard, like so: ::
+
+   deriving instance _ => Eq (Foo a)
+
+This denotes a derived ``Eq (Foo a)`` instance where the context is inferred,
+in much the same way that ordinary ``deriving`` clauses do. Any other use of
+wildcards in a standalone ``deriving`` declaration is prohibited.
 
 In all other contexts, type wildcards are disallowed, and a named wildcard is treated
 as an ordinary type variable.  For example: ::
@@ -11176,7 +12315,7 @@ splices.
    expression splices are supported.
 
 -  Pattern splices: anonymous and named wildcards can be used in pattern
-   signatures. Note that :ghc-flag:`-XScopedTypeVariables` has to be enabled
+   signatures. Note that :extension:`ScopedTypeVariables` has to be enabled
    to allow pattern signatures. Extra-constraints wildcards are not supported,
    just like in regular pattern signatures.
    ::
@@ -11214,7 +12353,7 @@ To solve this, GHC provides a single type-level function, ::
 
     type family TypeError (msg :: ErrorMessage) :: k
 
-along with a small type-level language (via :ghc-flag:`-XDataKinds`)
+along with a small type-level language (via :extension:`DataKinds`)
 for constructing pretty-printed error messages, ::
 
     -- ErrorMessage is intended to be used as a kind
@@ -11349,6 +12488,29 @@ demonstrates:
     Prelude> fst x
     True
 
+Limitations of deferred type errors
+-----------------------------------
+The errors that can be deferred are:
+
+- Out of scope term variables
+- Equality constraints; e.g. `ord True` gives rise to an insoluble equality constraint `Char ~ Bool`, which can be deferred.
+- Type-class and implicit-parameter constraints
+
+All other type errors are reported immediately, and cannot be deferred; for
+example, an ill-kinded type signature, an instance declaration that is
+non-terminating or ill-formed, a type-family instance that does not
+obey the declared injectivity constraints, etc etc.
+
+In a few cases, even equality constraints cannot be deferred.  Specifically:
+
+- Kind-equalities cannot be deferred, e.g. ::
+
+    f :: Int Bool -> Char
+
+  This type signature contains a kind error which cannot be deferred.
+
+- Type equalities under a forall cannot be deferred (c.f. Trac #14605).
+
 .. _template-haskell:
 
 Template Haskell
@@ -11365,7 +12527,7 @@ page on the GHC Wiki has a wealth of information. You may also consult the
 :th-ref:`Haddock reference documentation <Language.Haskell.TH.>`.
 Many changes to the original
 design are described in `Notes on Template Haskell version
-2 <http://research.microsoft.com/~simonpj/papers/meta-haskell/notes2.ps>`__.
+2 <https://www.haskell.org/ghc/docs/papers/th2.ps>`__.
 Not all of these changes are in GHC, however.
 
 The first example from that paper is set out below (:ref:`th-example`)
@@ -11380,34 +12542,28 @@ GHC. It is not detailed enough to understand Template Haskell; see the
 Syntax
 ------
 
-.. ghc-flag:: -XTemplateHaskell
-    :shortdesc: Enable :ref:`Template Haskell <template-haskell>`.
-    :type: dynamic
-    :reverse: -XNoTemplateHaskell
-    :category:
+.. extension:: TemplateHaskell
+    :shortdesc: Enable Template Haskell.
 
-    :implies: :ghc-flag:`-XTemplateHaskellQuotes`
+    :implies: :extension:`TemplateHaskellQuotes`
     :since: 6.0. Typed splices introduced in GHC 7.8.1.
 
     Enable Template Haskell's splice and quotation syntax.
 
-.. ghc-flag:: -XTemplateHaskellQuotes
+.. extension:: TemplateHaskellQuotes
     :shortdesc: Enable quotation subset of
         :ref:`Template Haskell <template-haskell>`.
-    :type: dynamic
-    :reverse: -XNoTemplateHaskellQuotes
-    :category:
 
     :since: 8.0.1
 
     Enable only Template Haskell's quotation syntax.
 
 Template Haskell has the following new syntactic constructions. You need to use
-the flag :ghc-flag:`-XTemplateHaskell` to switch these syntactic extensions on.
-Alternatively, the :ghc-flag:`-XTemplateHaskellQuotes` flag can be used to
+the extension :extension:`TemplateHaskell` to switch these syntactic extensions on.
+Alternatively, the :extension:`TemplateHaskellQuotes` extension can be used to
 enable the quotation subset of Template Haskell (i.e. without splice syntax).
-The :ghc-flag:`-XTemplateHaskellQuotes` extension is considered safe under
-:ref:`safe-haskell` while :ghc-flag:`-XTemplateHaskell` is not.
+The :extension:`TemplateHaskellQuotes` extension is considered safe under
+:ref:`safe-haskell` while :extension:`TemplateHaskell` is not.
 
 -  A splice is written ``$x``, where ``x`` is an identifier, or
    ``$(...)``, where the "..." is an arbitrary expression. There must be
@@ -11535,7 +12691,7 @@ The :ghc-flag:`-XTemplateHaskellQuotes` extension is considered safe under
 
    The ``template-haskell`` library provides ``Lift`` instances for many
    common data types. Furthermore, it is possible to derive ``Lift``
-   instances automatically by using the :ghc-flag:`-XDeriveLift` language extension.
+   instances automatically by using the :extension:`DeriveLift` language extension.
    See :ref:`deriving-lift` for more information.
 
 -  You may omit the ``$(...)`` in a top-level declaration splice. Simply
@@ -11754,9 +12910,9 @@ non-trivial program, you may be interested in combining this with the
 :ghc-flag:`-ddump-to-file` flag (see :ref:`dumping-output`. For each file using
 Template Haskell, this will show the output in a ``.dump-splices`` file.
 
-The flag :ghc-flag:`-dth-dec-file=⟨file⟩` shows the expansions of all top-level
+The flag :ghc-flag:`-dth-dec-file` dumps the expansions of all top-level
 TH declaration splices, both typed and untyped, in the file :file:`M.th.hs`
-where M is the name of the module being compiled. Note that other types of
+for each module `M` being compiled. Note that other types of
 splices (expressions, types, and patterns) are not shown. Application
 developers can check this into their repository so that they can grep for
 identifiers that were defined in Template Haskell. This is similar to using
@@ -11775,7 +12931,7 @@ Below is a sample output of :ghc-flag:`-ddump-splices` ::
       foo :: Int -> Int
       foo x = (x + 1)
 
-Below is the output of the same sample using :ghc-flag:`-dth-dec-file=⟨file⟩` ::
+Below is the output of the same sample using :ghc-flag:`-dth-dec-file` ::
 
     -- TH_pragma.hs:(6,4)-(8,26): Splicing declarations
     foo :: Int -> Int
@@ -11903,11 +13059,8 @@ releases).
 Template Haskell Quasi-quotation
 --------------------------------
 
-.. ghc-flag:: -XQuasiQuotes
-    :shortdesc: Enable :ref:`quasiquotation <th-quasiquotation>`.
-    :type: dynamic
-    :reverse: -XNoQuasiQuotes
-    :category:
+.. extension:: QuasiQuotes
+    :shortdesc: Enable quasiquotation.
 
     :since: 6.10.1
 
@@ -11984,13 +13137,13 @@ Here are the salient features
         single: quasi-quotes; ambiguity with list comprehensions
         single: list comprehensions; ambiguity with quasi-quotes
 
-    :ghc-flag:`-XQuasiQuotes` introduces an unfortunate ambiguity with list
+    :extension:`QuasiQuotes` introduces an unfortunate ambiguity with list
     comprehension syntax. Consider the following, ::
 
         let x = [v| v <- [0..10]]
 
-    Without :ghc-flag:`-XQuasiQuotes` this is parsed as a list comprehension.
-    With :ghc-flag:`-XQuasiQuotes` this is parsed as a quasi-quote; however,
+    Without :extension:`QuasiQuotes` this is parsed as a list comprehension.
+    With :extension:`QuasiQuotes` this is parsed as a quasi-quote; however,
     this parse will fail due to the lack of a closing ``|]``. See
     :ghc-ticket:`11679`.
 
@@ -12086,11 +13239,8 @@ Run "main" and here is your output:
 Arrow notation
 ==============
 
-.. ghc-flag:: -XArrows
-    :shortdesc: Enable :ref:`arrow notation <arrow-notation>` extension
-    :type: dynamic
-    :reverse: -XNoArrows
-    :category:
+.. extension:: Arrows
+    :shortdesc: Enable arrow notation extension
 
     :since: 6.8.1
 
@@ -12128,7 +13278,7 @@ more details, see
 -  The arrows web page at
    ``http://www.haskell.org/arrows/`` <http://www.haskell.org/arrows/>`__.
 
-With the :ghc-flag:`-XArrows` flag, GHC supports the arrow notation described in
+With the :extension:`Arrows` extension, GHC supports the arrow notation described in
 the second of these papers, translating it using combinators from the
 :base-ref:`Control.Arrow.` module.
 What follows is a brief introduction to the notation; it won't make much
@@ -12189,7 +13339,7 @@ A simple example of the new notation is the expression ::
 We call this a procedure or arrow abstraction. As with a lambda
 expression, the variable ``x`` is a new variable bound within the
 ``proc``-expression. It refers to the input to the arrow. In the above
-example, ``-<`` is not an identifier but an new reserved symbol used for
+example, ``-<`` is not an identifier but a new reserved symbol used for
 building commands from an expression of arrow type and an expression to
 be fed as input to that arrow. (The weird look will make more sense
 later.) It may be read as analogue of application for arrows. The above
@@ -12511,16 +13661,16 @@ Bang patterns and Strict Haskell
 In high-performance Haskell code (e.g. numeric code) eliminating
 thunks from an inner loop can be a huge win.
 GHC supports three extensions to allow the programmer to specify
-use of strict (call-by-value) evalution rather than lazy (call-by-need)
+use of strict (call-by-value) evaluation rather than lazy (call-by-need)
 evaluation.
 
-- Bang patterns (:ghc-flag:`-XBangPatterns`) makes pattern matching and
+- Bang patterns (:extension:`BangPatterns`) makes pattern matching and
   let bindings stricter.
 
-- Strict data types (:ghc-flag:`-XStrictData`) makes constructor fields
+- Strict data types (:extension:`StrictData`) makes constructor fields
   strict by default, on a per-module basis.
 
-- Strict pattern (:ghc-flag:`-XStrict`) makes all patterns and let bindings
+- Strict pattern (:extension:`Strict`) makes all patterns and let bindings
   strict by default, on a per-module basis.
 
 The latter two extensions are simply a way to avoid littering high-performance
@@ -12533,11 +13683,8 @@ Bang patterns and strict matching do not affect the type system in any way.
 Bang patterns
 -------------
 
-.. ghc-flag:: -XBangPatterns
-    :shortdesc: Enable :ref:`bang patterns <bang-patterns>`.
-    :type: dynamic
-    :reverse: -XNoBangPatterns
-    :category:
+.. extension:: BangPatterns
+    :shortdesc: Enable bang patterns.
 
     :since: 6.8.1
 
@@ -12635,11 +13782,8 @@ Note the following points:
 Strict-by-default data types
 ----------------------------
 
-.. ghc-flag:: -XStrictData
-    :shortdesc: Enable :ref:`default strict datatype fields <strict-data>`.
-    :type: dynamic
-    :reverse: -XNoStrictData
-    :category:
+.. extension:: StrictData
+    :shortdesc: Enable default strict datatype fields.
 
     :since: 8.0.1
 
@@ -12667,13 +13811,10 @@ The extension only affects definitions in this module.
 Strict-by-default pattern bindings
 ----------------------------------
 
-.. ghc-flag:: -XStrict
+.. extension:: Strict
     :shortdesc: Make bindings in the current module strict by default.
-    :type: dynamic
-    :reverse: -XNoStrict
-    :category:
 
-    :implies: :ghc-flag:`-XStrictData`
+    :implies: :extension:`StrictData`
     :since: 8.0.1
 
     Make bindings in the current module strict by default.
@@ -12698,6 +13839,10 @@ optionally had by adding ``!`` in front of a variable.
 
    Adding ``~`` in front of ``x`` gives the regular lazy behavior.
 
+   Turning patterns into irrefutable ones requires ``~(~p)`` or ``(~ ~p)`` when ``Strict`` is enabled.
+
+
+
 -  **Let/where bindings**
 
    When the user writes ::
@@ -13013,7 +14158,7 @@ GHC offers a helping hand here, doing all of this for you. For every use
 of ``assert`` in the user's source: ::
 
     kelvinToC :: Double -> Double
-    kelvinToC k = assert (k >= 0.0) (k+273.15)
+    kelvinToC k = assert (k >= 0.0) (k-273.15)
 
 GHC will rewrite this to also include the source location where the
 assertion was made, ::
@@ -13046,17 +14191,14 @@ Static pointers
 .. index::
    single: Static pointers
 
-.. ghc-flag:: -XStaticPointers
-    :shortdesc: Enable :ref:`static pointers <static-pointers>`.
-    :type: dynamic
-    :reverse: -XNoStaticPointers
-    :category:
+.. extension:: StaticPointers
+    :shortdesc: Enable static pointers.
 
     :since: 7.10.1
 
     Allow use of static pointer syntax.
 
-The language extension :ghc-flag:`-XStaticPointers` adds a new syntactic form
+The language extension :extension:`StaticPointers` adds a new syntactic form
 ``static e``, which stands for a reference to the closed expression ⟨e⟩.
 This reference is stable and portable, in the sense that it remains
 valid across different processes on possibly different machines. Thus, a
@@ -13111,10 +14253,17 @@ While the following definitions are rejected: ::
 .. note::
 
     While modules loaded in GHCi with the :ghci-cmd:`:load` command may use
-    :ghc-flag:`-XStaticPointers` and ``static`` expressions, statements
+    :extension:`StaticPointers` and ``static`` expressions, statements
     entered on the REPL may not. This is a limitation of GHCi; see
     :ghc-ticket:`12356` for details.
 
+.. note::
+
+    The set of keys used for locating static pointers in the Static Pointer
+    Table is not guaranteed to remain stable for different program binaries.
+    Or in other words, only processes launched from the same program binary
+    are guaranteed to use the same set of keys.
+
 .. _typechecking-static-pointers:
 
 Static semantics of static pointers
@@ -13214,9 +14363,11 @@ Certain pragmas are *file-header pragmas*:
 ``LANGUAGE`` pragma
 -------------------
 
-.. index::
-   single: LANGUAGE; pragma
-   single: pragma; LANGUAGE
+.. pragma:: LANGUAGE ⟨ext⟩, ⟨ext⟩, ...
+
+    :where: file header
+
+    Enable or disable a set of language extensions.
 
 The ``LANGUAGE`` pragma allows language extensions to be enabled in a
 portable way. It is the intention that all Haskell compilers support the
@@ -13246,9 +14397,9 @@ if any of the requested extensions are not supported.
 ``OPTIONS_GHC`` pragma
 ----------------------
 
-.. index::
-   single: OPTIONS_GHC
-   single: pragma; OPTIONS_GHC
+.. pragma:: OPTIONS_GHC ⟨flags⟩
+
+    :where: file header
 
 The ``OPTIONS_GHC`` pragma is used to specify additional options that
 are given to the compiler when compiling this source file. See
@@ -13274,14 +14425,21 @@ other compilers.
 ``WARNING`` and ``DEPRECATED`` pragmas
 --------------------------------------
 
-.. index::
-   single: WARNING
-   single: DEPRECATED
+.. pragma:: WARNING
+
+    :where: declaration
+
+    The ``WARNING`` pragma allows you to attach an arbitrary warning to a
+    particular function, class, or type.
+
+.. pragma:: DEPRECATED
 
-The ``WARNING`` pragma allows you to attach an arbitrary warning to a
-particular function, class, or type. A ``DEPRECATED`` pragma lets you
-specify that a particular function, class, or type is deprecated. There
-are two ways of using these pragmas.
+    :where: declaration
+
+    A ``DEPRECATED`` pragma lets you specify that a particular function, class,
+    or type is deprecated.
+
+There are two ways of using these pragmas.
 
 -  You can work on an entire module thus: ::
 
@@ -13332,9 +14490,11 @@ You can suppress the warnings with the flag
 ``MINIMAL`` pragma
 ------------------
 
-.. index::
-   single: MINIMAL
-   single: pragma; MINIMAL
+.. pragma:: MINIMAL ⟨name⟩ | ⟨name⟩ , ...
+
+    :where: in class body
+
+    Define the methods needed for a minimal complete instance of a class.
 
 The ``MINIMAL`` pragma is used to specify the minimal complete definition of
 a class, i.e. specify which methods must be implemented by all
@@ -13365,9 +14525,8 @@ Conjunction binds stronger than disjunction.
 
 If no ``MINIMAL`` pragma is given in the class declaration, it is just as if
 a pragma ``{-# MINIMAL op1, op2, ..., opn #-}`` was given, where the
-``opi`` are the methods (a) that lack a default method in the class
-declaration, and (b) whose name that does not start with an underscore
-(c.f. :ghc-flag:`-Wmissing-methods`, :ref:`options-sanity`).
+``opi`` are the methods that lack a default method in the class
+declaration (c.f. :ghc-flag:`-Wmissing-methods`, :ref:`options-sanity`).
 
 This warning can be turned off with the flag
 :ghc-flag:`-Wno-missing-methods <-Wmissing-methods>`.
@@ -13384,9 +14543,11 @@ These pragmas control the inlining of function definitions.
 ``INLINE`` pragma
 ~~~~~~~~~~~~~~~~~
 
-.. index::
-   single: INLINE
-   single: pragma; INLINE
+.. pragma:: INLINE ⟨name⟩
+
+    :where: top-level
+
+    Force GHC to inline a value.
 
 GHC (with :ghc-flag:`-O`, as always) tries to inline (or "unfold")
 functions/values that are "small enough," thus avoiding the call
@@ -13450,7 +14611,7 @@ has a number of other effects:
    which will optimise better than the corresponding use of ``comp2``.
 
 -  It is useful for GHC to optimise the definition of an INLINE function
-   ``f`` just like any other non-INLINE function, in case the
+   ``f`` just like any other non-``INLINE`` function, in case the
    non-inlined version of ``f`` is ultimately called. But we don't want
    to inline the *optimised* version of ``f``; a major reason for ``INLINE``
    pragmas is to expose functions in ``f``\'s RHS that have rewrite
@@ -13463,7 +14624,7 @@ has a number of other effects:
    usual. For externally-visible functions the inline-RHS (not the
    optimised RHS) is recorded in the interface file.
 
--  An INLINE function is not worker/wrappered by strictness analysis.
+-  An ``INLINE`` function is not worker/wrappered by strictness analysis.
    It's going to be inlined wholesale instead.
 
 GHC ensures that inlining cannot go on forever: every mutually-recursive
@@ -13494,6 +14655,12 @@ See also the ``NOINLINE`` (:ref:`noinline-pragma`) and ``INLINABLE``
 ``INLINABLE`` pragma
 ~~~~~~~~~~~~~~~~~~~~
 
+.. pragma:: INLINABLE ⟨name⟩
+
+    :where: top-level
+
+    Suggest that the compiler always consider inlining ``name``.
+
 An ``{-# INLINABLE f #-}`` pragma on a function ``f`` has the following
 behaviour:
 
@@ -13533,10 +14700,15 @@ The alternative spelling ``INLINEABLE`` is also accepted by GHC.
 ~~~~~~~~~~~~~~~~~~~
 
 .. index::
-   single: NOINLINE
    single: NOTINLINE
 
-The ``NOINLINE`` pragma does exactly what you'd expect: it stops the
+.. pragma:: NOINLINE ⟨name⟩
+
+    :where: top-level
+
+    Instructs the compiler not to inline a value.
+
+The :pragma:`NOINLINE` pragma does exactly what you'd expect: it stops the
 named function from being inlined by the compiler. You shouldn't ever
 need to do this, unless you're very cautious about code size.
 
@@ -13549,23 +14721,26 @@ used if you want your code to be portable).
 ``CONLIKE`` modifier
 ~~~~~~~~~~~~~~~~~~~~
 
-.. index::
-   single: CONLIKE
+.. pragma:: CONLINE
+
+    :where: modifies :pragma:`INLINE` or :pragma:`NOINLINE` pragma
 
-An ``INLINE`` or ``NOINLINE`` pragma may have a ``CONLIKE`` modifier, which affects
-matching in RULEs (only). See :ref:`conlike`.
+    Instructs GHC to consider a value to be especially cheap to inline.
+
+An :pragma:`INLINE` or :pragma:`NOINLINE` pragma may have a :pragma:`CONLIKE` modifier, which affects
+matching in :pragma:`RULE`\s (only). See :ref:`conlike`.
 
 .. _phase-control:
 
 Phase control
 ~~~~~~~~~~~~~
 
-Sometimes you want to control exactly when in GHC's pipeline the ``INLINE``
+Sometimes you want to control exactly when in GHC's pipeline the :pragma:`INLINE`
 pragma is switched on. Inlining happens only during runs of the
 *simplifier*. Each run of the simplifier has a different *phase number*;
 the phase number decreases towards zero. If you use
-``-dverbose-core2core`` you'll see the sequence of phase numbers for
-successive runs of the simplifier. In an ``INLINE`` pragma you can
+:ghc-flag:`-dverbose-core2core` you will see the sequence of phase numbers for
+successive runs of the simplifier. In an :pragma:`INLINE` pragma you can
 optionally specify a phase number, thus:
 
 -  "``INLINE[k] f``" means: do not inline ``f`` until phase ``k``, but
@@ -13583,7 +14758,7 @@ optionally specify a phase number, thus:
 
 The same information is summarised here:
 
-::
+.. code-block:: none
 
                                -- Before phase 2     Phase 2 and later
       {-# INLINE   [2]  f #-}  --      No                 Yes
@@ -13598,14 +14773,14 @@ By "Maybe" we mean that the usual heuristic inlining rules apply (if the
 function body is small, or it is applied to interesting-looking
 arguments etc). Another way to understand the semantics is this:
 
--  For both ``INLINE`` and ``NOINLINE``, the phase number says when inlining is
-   allowed at all.
+-  For both :pragma:`INLINE` and :pragma:`NOINLINE`, the phase number says when
+   inlining is allowed at all.
 
--  The ``INLINE`` pragma has the additional effect of making the function
+-  The :pragma:`INLINE` pragma has the additional effect of making the function
    body look small, so that when inlining is allowed it is very likely
    to happen.
 
-The same phase-numbering control is available for RULES
+The same phase-numbering control is available for :pragma:`RULE`\s
 (:ref:`rewrite-rules`).
 
 .. _line-pragma:
@@ -13613,9 +14788,12 @@ The same phase-numbering control is available for RULES
 ``LINE`` pragma
 ---------------
 
-.. index::
-   single: LINE; pragma
-   single: pragma; LINE
+.. pragma:: LINE ⟨lineno⟩ "⟨file⟩"
+
+    :where: anywhere
+
+    Generated by preprocessors to convey source line numbers of the original
+    source.
 
 This pragma is similar to C's ``#line`` pragma, and is mainly for use in
 automatically generated Haskell code. It lets you specify the line
@@ -13663,7 +14841,7 @@ diagnostics and does not change the syntax of the code itself.
 ``RULES`` pragma
 ----------------
 
-The ``RULES`` pragma lets you specify rewrite rules. It is described in
+The :pragma:`RULES` pragma lets you specify rewrite rules. It is described in
 :ref:`rewrite-rules`.
 
 .. _specialize-pragma:
@@ -13676,8 +14854,12 @@ The ``RULES`` pragma lets you specify rewrite rules. It is described in
    single: pragma, SPECIALIZE
    single: overloading, death to
 
+.. pragma:: SPECIALIZE ⟨name⟩ :: ⟨type⟩
+
+    Ask that GHC specialize a polymorphic value to a particular type.
+
 (UK spelling also accepted.) For key overloaded functions, you can
-create extra versions (NB: more code space) specialised to particular
+create extra versions (NB: at the cost of larger code) specialised to particular
 types. Thus, if you have an overloaded function:
 
 ::
@@ -13774,6 +14956,10 @@ specialise it as follows:
 ``SPECIALIZE INLINE``
 ~~~~~~~~~~~~~~~~~~~~~
 
+.. pragma:: SPECIALIZE INLINE ⟨name⟩ :: ⟨type⟩
+
+    :where: top-level
+
 A ``SPECIALIZE`` pragma can optionally be followed with a ``INLINE`` or
 ``NOINLINE`` pragma, optionally followed by a phase, as described in
 :ref:`inline-noinline-pragma`. The ``INLINE`` pragma affects the
@@ -13799,9 +14985,9 @@ fire the first specialisation, whose body is also inlined. The result is
 a type-based unrolling of the indexing function.
 
 You can add explicit phase control (:ref:`phase-control`) to
-``SPECIALISE INLINE`` pragma, just like on an ``INLINE`` pragma; if you
-do so, the same phase is used for the rewrite rule and the INLINE
-control of the specialised function.
+``SPECIALISE INLINE`` pragma, just like on an :pragma:`INLINE` pragma; if you do
+so, the same phase is used for the rewrite rule and the INLINE control of the
+specialised function.
 
 .. warning:: You can make GHC diverge by using ``SPECIALISE INLINE`` on an
              ordinarily-recursive function.
@@ -13809,9 +14995,9 @@ control of the specialised function.
 ``SPECIALIZE`` for imported functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Generally, you can only give a ``SPECIALIZE`` pragma for a function
+Generally, you can only give a :pragma:`SPECIALIZE` pragma for a function
 defined in the same module. However if a function ``f`` is given an
-``INLINABLE`` pragma at its definition site, then it can subsequently be
+:pragma:`INLINABLE` pragma at its definition site, then it can subsequently be
 specialised by importing modules (see :ref:`inlinable-pragma`). For example ::
 
     module Map( lookup, blah blah ) where
@@ -13825,7 +15011,7 @@ specialised by importing modules (see :ref:`inlinable-pragma`). For example ::
       data T = T1 | T2 deriving( Eq, Ord )
       {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a
 
-Here, ``lookup`` is declared ``INLINABLE``, but it cannot be specialised
+Here, ``lookup`` is declared :pragma:`INLINABLE`, but it cannot be specialised
 for type ``T`` at its definition site, because that type does not exist
 yet. Instead a client module can define ``T`` and then specialise
 ``lookup`` at that type.
@@ -13833,13 +15019,13 @@ yet. Instead a client module can define ``T`` and then specialise
 Moreover, every module that imports ``Client`` (or imports a module that
 imports ``Client``, transitively) will "see", and make use of, the
 specialised version of ``lookup``. You don't need to put a
-``SPECIALIZE`` pragma in every module.
+:pragma:`SPECIALIZE` pragma in every module.
 
-Moreover you often don't even need the ``SPECIALIZE`` pragma in the
+Moreover you often don't even need the :pragma:`SPECIALIZE` pragma in the
 first place. When compiling a module ``M``, GHC's optimiser (when given the
 :ghc-flag:`-O` flag) automatically considers each top-level overloaded function declared
 in ``M``, and specialises it for the different types at which it is called in
-``M``. The optimiser *also* considers each *imported* ``INLINABLE``
+``M``. The optimiser *also* considers each *imported* :pragma:`INLINABLE`
 overloaded function, and specialises it for the different types at which
 it is called in ``M``. So in our example, it would be enough for ``lookup``
 to be called at type ``T``:
@@ -13857,28 +15043,19 @@ to be called at type ``T``:
 However, sometimes there are no such calls, in which case the pragma can
 be useful.
 
-Obsolete ``SPECIALIZE`` syntax
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In earlier versions of GHC, it was possible to provide your own
-specialised function for a given type:
-
-::
-
-    {-# SPECIALIZE hammeredLookup :: [(Int, value)] -> Int -> value = intLookup #-}
-
-This feature has been removed, as it is now subsumed by the ``RULES``
-pragma (see :ref:`rule-spec`).
-
 .. _specialize-instance-pragma:
 
 ``SPECIALIZE`` instance pragma
 ------------------------------
 
 .. index::
-   single: SPECIALIZE pragma
+   single: instance, specializing
    single: overloading, death to
 
+.. pragma:: SPECIALIZE instance ⟨instance head⟩
+
+   :where: instance body
+
 Same idea, except for instance declarations. For example:
 
 ::
@@ -13896,8 +15073,12 @@ declaration.
 ``UNPACK`` pragma
 -----------------
 
-.. index::
-   single: UNPACK
+.. pragma:: UNPACK
+
+    :where: data constructor field
+
+    Instructs the compiler to unpack the contents of a constructor field into
+    the constructor itself.
 
 The ``UNPACK`` indicates to the compiler that it should unpack the
 contents of a constructor field into the constructor itself, removing a
@@ -13938,19 +15119,19 @@ See also the :ghc-flag:`-funbox-strict-fields` flag, which essentially has the
 effect of adding ``{-# UNPACK #-}`` to every strict constructor field.
 
 .. [1]
-   in fact, UNPACK has no effect without
-   -O
-   , for technical reasons (see
-   tick 5252
-   )
+   In fact, :pragma:`UNPACK` has no effect without :ghc-flag:`-O`, for technical
+   reasons (see :ghc-ticket:`5252`).
 
 .. _nounpack-pragma:
 
 ``NOUNPACK`` pragma
 -------------------
 
-.. index::
-   single: NOUNPACK
+.. pragma:: NOUNPACK
+
+    :where: top-level
+
+    Instructs the compiler not to unpack a constructor field.
 
 The ``NOUNPACK`` pragma indicates to the compiler that it should not
 unpack the contents of a constructor field. Example: ::
@@ -13965,9 +15146,11 @@ field of the constructor ``T`` is not unpacked.
 ``SOURCE`` pragma
 -----------------
 
-.. index::
-   single: SOURCE
-   single: pragma; SOURCE
+.. pragma:: SOURCE
+
+    :where: after ``import`` statement
+
+    Import a module by ``hs-boot`` file to break a module loop.
 
 The ``{-# SOURCE #-}`` pragma is used only in ``import`` declarations,
 to break a module loop. It is described in detail in
@@ -13978,6 +15161,13 @@ to break a module loop. It is described in detail in
 ``COMPLETE`` pragmas
 --------------------
 
+.. pragma:: COMPLETE
+
+    :where: at top level
+
+    Specify the set of constructors or pattern synonyms which constitute a total
+    match.
+
 The ``COMPLETE`` pragma is used to inform the pattern match checker that a
 certain set of patterns is complete and that any function which matches
 on all the specified patterns is total.
@@ -14024,7 +15214,7 @@ modules. ``COMPLETE`` pragmas should be thought of as asserting a
 universal truth about a set of patterns and as a result, should not be
 used to silence context specific incomplete match warnings.
 
-When specifing a ``COMPLETE`` pragma, the result types of all patterns must
+When specifying a ``COMPLETE`` pragma, the result types of all patterns must
 be consistent with each other. This is a sanity check as it would be impossible
 to match on all the patterns if the types were inconsistent.
 
@@ -14047,6 +15237,49 @@ the user must provide a type signature. ::
     foo :: [a] -> Int
     foo T = 5
 
+.. _multiple-complete-pragmas:
+
+Disambiguating between multiple ``COMPLETE`` pragmas
+----------------------------------------------------
+
+What should happen if there are multiple ``COMPLETE`` sets that apply to a
+single set of patterns? Consider this example: ::
+
+  data T = MkT1 | MkT2 | MkT2Internal
+  {-# COMPLETE MkT1, MkT2 #-}
+  {-# COMPLETE MkT1, MkT2Internal #-}
+
+  f :: T -> Bool
+  f MkT1 = True
+  f MkT2 = False
+
+Which ``COMPLETE`` pragma should be used when checking the coverage of the
+patterns in ``f``? If we pick the ``COMPLETE`` set that covers ``MkT1`` and
+``MkT2``, then ``f`` is exhaustive, but if we pick the other ``COMPLETE`` set
+that covers ``MkT1`` and ``MkT2Internal``, then ``f`` is *not* exhaustive,
+since it fails to match ``MkT2Internal``. An intuitive way to solve this
+dilemma is to recognize that picking the former ``COMPLETE`` set produces the
+fewest number of uncovered pattern clauses, and thus is the better choice.
+
+GHC disambiguates between multiple ``COMPLETE`` sets based on this rationale.
+To make things more formal, when the pattern-match checker requests a set of
+constructors for some data type constructor ``T``, the checker returns:
+
+* The original set of data constructors for ``T``
+* Any ``COMPLETE`` sets of type ``T``
+
+GHC then checks for pattern coverage using each of these sets. If any of these
+sets passes the pattern coverage checker with no warnings, then we are done. If
+each set produces at least one warning, then GHC must pick one of the sets of
+warnings depending on how good the results are. The results are prioritized in
+this order:
+
+1. Fewest uncovered clauses
+2. Fewest redundant clauses
+3. Fewest inaccessible clauses
+4. Whether the match comes from the original set of data constructors or from a
+   ``COMPLETE`` pragma (prioritizing the former over the latter)
+
 .. _overlap-pragma:
 
 ``OVERLAPPING``, ``OVERLAPPABLE``, ``OVERLAPS``, and ``INCOHERENT`` pragmas
@@ -14062,6 +15295,13 @@ the user must provide a type signature. ::
    single: INCOHERENT
    single: pragma; INCOHERENT
 
+.. pragma:: OVERLAPPING
+.. pragma:: OVERLAPPABLE
+.. pragma:: OVERLAPS
+.. pragma:: INCOHERENT
+
+    :where: on instance head
+
 The pragmas ``OVERLAPPING``, ``OVERLAPPABLE``, ``OVERLAPS``,
 ``INCOHERENT`` are used to specify the overlap behavior for individual
 instances, as described in Section :ref:`instance-overlap`. The pragmas
@@ -14077,15 +15317,19 @@ Rewrite rules
 =============
 
 .. index::
-   single: RULES pragma
-   single: pragma; RULES
    single: rewrite rules
 
+.. pragma:: RULES "⟨name⟩" forall ⟨binder⟩ ... . ⟨expr⟩ = ⟨expr⟩ ...
+
+    :where: top-level
+
+    Define a rewrite rule to be used to optimize a source program.
+
 The programmer can specify rewrite rules as part of the source program
 (in a pragma). Here is an example: ::
 
       {-# RULES
-      "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
+            "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
         #-}
 
 Use the debug flag :ghc-flag:`-ddump-simpl-stats` to see what rules fired. If
@@ -14108,7 +15352,7 @@ Syntax
 
 From a syntactic point of view:
 
--  There may be zero or more rules in a ``RULES`` pragma, separated by
+-  There may be zero or more rules in a :pragma:`RULES` pragma, separated by
    semicolons (which may be generated by the layout rule).
 
 -  The layout rule applies in a pragma. Currently no new indentation
@@ -14117,8 +15361,8 @@ From a syntactic point of view:
    the same column as the enclosing definitions. ::
 
          {-# RULES
-         "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
-         "map/append" forall f xs ys. map f (xs ++ ys) = map f xs ++ map f ys
+               "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
+               "map/append" forall f xs ys. map f (xs ++ ys) = map f xs ++ map f ys
            #-}
 
    Furthermore, the closing ``#-}`` should start in a column to the
@@ -14145,7 +15389,7 @@ From a syntactic point of view:
    is never run by GHC, but is nevertheless parsed, typechecked etc, so
    that it is available to the plugin.
 
--  Each variable mentioned in a rule must either be in scope (e.g.
+-  Each (term) variable mentioned in a rule must either be in scope (e.g.
    ``map``), or bound by the ``forall`` (e.g. ``f``, ``g``, ``xs``). The
    variables bound by the ``forall`` are called the *pattern* variables.
    They are separated by spaces, just like in a type ``forall``.
@@ -14159,6 +15403,25 @@ From a syntactic point of view:
 
    Since ``g`` has a polymorphic type, it must have a type signature.
 
+-  If :extension:`ExplicitForAll` is enabled, type/kind variables can also be
+   explicitly bound. For example: ::
+
+       {-# RULES "id" forall a. forall (x :: a). id @a x = x #-}
+
+   When a type-level explicit ``forall`` is present, each type/kind variable
+   mentioned must now also be either in scope or bound by the ``forall``. In
+   particular, unlike some other places in Haskell, this means free kind
+   variables will not be implicitly bound. For example: ::
+
+       "this_is_bad" forall (c :: k). forall (x :: Proxy c) ...
+       "this_is_ok"  forall k (c :: k). forall (x :: Proxy c) ...
+
+   When bound type/kind variables are needed, both foralls must always be
+   included, though if no pattern variables are needed, the second can be left
+   empty. For example: ::
+
+       {-# RULES "map/id" forall a. forall. map (id @a) = id @[a] #-}
+
 -  The left hand side of a rule must consist of a top-level variable
    applied to arbitrary expressions. For example, this is *not* OK: ::
 
@@ -14179,12 +15442,12 @@ From a syntactic point of view:
    then C's rules are in force when compiling A.) The situation is very
    similar to that for instance declarations.
 
--  Inside a RULE "``forall``" is treated as a keyword, regardless of any
+-  Inside a :pragma:`RULE` "``forall``" is treated as a keyword, regardless of any
    other flag settings. Furthermore, inside a RULE, the language
-   extension :ghc-flag:`-XScopedTypeVariables` is automatically enabled; see
+   extension :extension:`ScopedTypeVariables` is automatically enabled; see
    :ref:`scoped-type-variables`.
 
--  Like other pragmas, ``RULE`` pragmas are always checked for scope errors,
+-  Like other pragmas, :pragma:`RULE` pragmas are always checked for scope errors,
    and are typechecked. Typechecking means that the LHS and RHS of a
    rule are typechecked, and must have the same type. However, rules are
    only *enabled* if the :ghc-flag:`-fenable-rewrite-rules` flag is on (see
@@ -14273,12 +15536,12 @@ give ::
 
     g y = y
 
-Now ``g`` is inlined into ``h``, but ``f``\'s RULE has no chance to fire.
-If instead GHC had first inlined ``g`` into ``h`` then there would have
-been a better chance that ``f``\'s RULE might fire.
+Now ``g`` is inlined into ``h``, but ``f``\'s :pragma:`RULE` has no chance to
+fire. If instead GHC had first inlined ``g`` into ``h`` then there would have
+been a better chance that ``f``\'s :pragma:`RULE` might fire.
 
-The way to get predictable behaviour is to use a ``NOINLINE`` pragma, or an
-``INLINE[⟨phase⟩]`` pragma, on ``f``, to ensure that it is not inlined until
+The way to get predictable behaviour is to use a :pragma:`NOINLINE` pragma, or an
+INLINE[⟨phase⟩] pragma, on ``f``, to ensure that it is not inlined until
 its RULEs have had a chance to fire. The warning flag
 :ghc-flag:`-Winline-rule-shadowing` (see :ref:`options-sanity`) warns about
 this situation.
@@ -14311,9 +15574,9 @@ an application of ``f`` to one argument (in general, the number of arguments
 to the left of the ``=`` sign) should be considered cheap enough to
 duplicate, if such a duplication would make rule fire. (The name
 "CONLIKE" is short for "constructor-like", because constructors
-certainly have such a property.) The ``CONLIKE`` pragma is a modifier to
-INLINE/NOINLINE because it really only makes sense to match ``f`` on the
-LHS of a rule if you are sure that ``f`` is not going to be inlined
+certainly have such a property.) The :pragma:`CONLIKE` pragma is a modifier to
+:pragma:`INLINE`/:pragma:`NOINLINE` because it really only makes sense to match
+``f`` on the LHS of a rule if you are sure that ``f`` is not going to be inlined
 before the rule has a chance to fire.
 
 .. _rules-class-methods:
@@ -14346,7 +15609,7 @@ The solution is to define the instance-specific function yourself, with
 a pragma to prevent it being inlined too early, and give a RULE for it: ::
 
     instance C Bool where
-      op x y = opBool
+      op = opBool
 
     opBool :: Bool -> Bool -> Bool
     {-# NOINLINE [1] opBool #-}
@@ -14508,7 +15771,7 @@ Controlling what's going on in rewrite rules
                {-# INLINE build #-}
                build g = g (:) []
 
-   Notice the ``INLINE``! That prevents ``(:)`` from being inlined when
+   Notice the :pragma:`INLINE`! That prevents ``(:)`` from being inlined when
    compiling ``PrelBase``, so that an importing module will “see” the
    ``(:)``, and can match it on the LHS of a rule. ``INLINE`` prevents
    any inlining happening in the RHS of the ``INLINE`` thing. I regret
@@ -14549,8 +15812,8 @@ programming <#generic-programming>`__.
 Generic programming
 ===================
 
-Using a combination of :ghc-flag:`-XDeriveGeneric`,
-:ghc-flag:`-XDefaultSignatures`, and :ghc-flag:`-XDeriveAnyClass`, you can
+Using a combination of :extension:`DeriveGeneric`,
+:extension:`DefaultSignatures`, and :extension:`DeriveAnyClass`, you can
 easily do datatype-generic programming using the :base-ref:`GHC.Generics.`
 framework. This section gives a very brief overview of how to do it.
 
@@ -14570,7 +15833,7 @@ Haskell datatypes: ::
     -- | Unit: used for constructors without arguments
     data U1 p = U1
 
-    -- | Constants, additional parameters and recursion of kind *
+    -- | Constants, additional parameters and recursion of kind Type
     newtype K1 i c p = K1 { unK1 :: c }
 
     -- | Meta-information (constructor names, etc.)
@@ -14589,25 +15852,33 @@ datatypes and their internal representation as a sum-of-products: ::
 
     class Generic a where
       -- Encode the representation of a user datatype
-      type Rep a :: * -> *
+      type Rep a :: Type -> Type
       -- Convert from the datatype to its representation
       from  :: a -> (Rep a) x
       -- Convert from the representation to the datatype
       to    :: (Rep a) x -> a
 
-    class Generic1 (f :: k -> *) where
-      type Rep1 f :: k -> *
+    class Generic1 (f :: k -> Type) where
+      type Rep1 f :: k -> Type
 
       from1  :: f a -> Rep1 f a
       to1    :: Rep1 f a -> f a
 
 ``Generic1`` is used for functions that can only be defined over type
 containers, such as ``map``. Note that ``Generic1`` ranges over types of kind
-``* -> *`` by default, but if the :ghc-flag:`-XPolyKinds` extension is enabled,
-then it can range of types of kind ``k -> *``, for any kind ``k``.
+``Type -> Type`` by default, but if the :extension:`PolyKinds` extension is
+enabled, then it can range of types of kind ``k -> Type``, for any kind ``k``.
+
+.. extension:: DeriveGeneric
+    :shortdesc: Enable deriving for the Generic class.
+
+    :since: 7.2.1
+
+    Allow automatic deriving of instances for the ``Generic`` typeclass.
+
 
 Instances of these classes can be derived by GHC with the
-:ghc-flag:`-XDeriveGeneric` extension, and are necessary to be able to define
+:extension:`DeriveGeneric` extension, and are necessary to be able to define
 generic instances automatically.
 
 For example, a user-defined datatype of trees ::
@@ -14759,7 +16030,7 @@ write: ::
 
 The default method for ``put`` is then used, corresponding to the
 generic implementation of serialization. If you are using
-:ghc-flag:`-XDeriveAnyClass`, the same instance is generated by simply attaching
+:extension:`DeriveAnyClass`, the same instance is generated by simply attaching
 a ``deriving Serialize`` clause to the ``UserTree`` datatype
 declaration. For more examples of generic functions please refer to the
 `generic-deriving <http://hackage.haskell.org/package/generic-deriving>`__
@@ -14786,8 +16057,8 @@ Roles
 .. index::
    single: roles
 
-Using :ghc-flag:`-XGeneralizedNewtypeDeriving`
-(:ref:`generalized-newtype-deriving`), a programmer can take existing
+Using :extension:`GeneralizedNewtypeDeriving`
+(:ref:`newtype-deriving`), a programmer can take existing
 instances of classes and "lift" these into instances of that class for a
 newtype. However, this is not always safe. For example, consider the
 following:
@@ -14873,8 +16144,8 @@ Here are some examples: ::
 The type ``Simple`` has its parameter at role representational, which is
 generally the most common case. ``Simple Age`` would have the same
 representation as ``Simple Int``. The type ``Complex``, on the other
-hand, has its parameter at role nominal, because ``Simple Age`` and
-``Simple Int`` are *not* the same. Lastly, ``Phant Age`` and
+hand, has its parameter at role nominal, because ``Complex Age`` and
+``Complex Int`` are *not* the same. Lastly, ``Phant Age`` and
 ``Phant Bool`` have the same representation, even though ``Age`` and
 ``Bool`` are unrelated.
 
@@ -14927,11 +16198,8 @@ role nominal for ``b``.
 Role annotations
 ----------------
 
-.. ghc-flag:: -XRoleAnnotations
-    :shortdesc: Enable :ref:`role annotations <role-annotations>`.
-    :type: dynamic
-    :reverse: -XNoRoleAnnotations
-    :category:
+.. extension:: RoleAnnotations
+    :shortdesc: Enable role annotations.
 
     :since: 7.8.1
 
@@ -14951,7 +16219,7 @@ a pointer to a ``Bool``. But, that's not at all how we want to use
       type role Ptr representational
       data Ptr a = Ptr Addr#
 
-The ``type role`` (enabled with :ghc-flag:`-XRoleAnnotations`) declaration
+The ``type role`` (enabled with :extension:`RoleAnnotations`) declaration
 forces the parameter ``a`` to be at role representational, not role
 phantom. GHC then checks the user-supplied roles to make sure they don't
 break any promises. It would be bad, for example, if the user could make
@@ -14971,7 +16239,7 @@ This would be done with a declaration ::
 Role annotations can also be used should a programmer wish to write a
 class with a representational (or phantom) role. However, as a class
 with non-nominal roles can quickly lead to class instance incoherence,
-it is necessary to also specify :ghc-flag:`-XIncoherentInstances` to allow
+it is necessary to also specify :extension:`IncoherentInstances` to allow
 non-nominal roles for classes.
 
 The other place where role annotations may be necessary are in
@@ -15018,28 +16286,67 @@ HasCallStack
 ``GHC.Stack.HasCallStack`` is a lightweight method of obtaining a
 partial call-stack at any point in the program.
 
-A function can request its call-site with the ``HasCallStack`` constraint.
-For example, we can define ::
+A function can request its call-site with the ``HasCallStack`` constraint
+and access it as a Haskell value by using ``callStack``.
+
+One can then use functions from ``GHC.Stack`` to inspect or pretty
+print (as is done in ``f`` below) the call stack.
+
+   f :: HasCallStack => IO ()
+   f = putStrLn (prettyCallStack callStack)
+
+   g :: HasCallStack => IO ()
+   g = f
+
+Evaluating ``f`` directly shows a call stack with a single entry,
+while evaluating ``g``, which also requests its call-site, shows
+two entries, one for each computation "annotated" with
+``HasCallStack``.
+
+.. code-block:: none
+
+   ghci> f
+   CallStack (from HasCallStack):
+     f, called at <interactive>:19:1 in interactive:Ghci1
+   ghci> g
+   CallStack (from HasCallStack):
+     f, called at <interactive>:17:5 in main:Main
+     g, called at <interactive>:20:1 in interactive:Ghci2
+
+The ``error`` function from the Prelude supports printing the call stack that
+led to the error in addition to the usual error message:
+
+.. code-block:: none
+
+   ghci> error "bad"
+   *** Exception: bad
+   CallStack (from HasCallStack):
+     error, called at <interactive>:25:1 in interactive:Ghci5
 
-   errorWithCallStack :: HasCallStack => String -> a
+The call stack here consists of a single entry, pinpointing the source
+of the call to ``error``. However, by annotating several computations
+with ``HasCallStack``, figuring out the exact circumstances and sequences
+of calls that lead to a call to ``error`` becomes a lot easier, as demonstrated
+with the simple example below. ::
 
-as a variant of ``error`` that will get its call-site (as of GHC 8.0,
-``error`` already gets its call-site, but let's assume for the sake of
-demonstration that it does not). We can access the call-stack inside
-``errorWithCallStack`` with ``GHC.Stack.callStack``. ::
+   f :: HasCallStack => IO ()
+   f = error "bad bad bad"
 
-   errorWithCallStack :: HasCallStack => String -> a
-   errorWithCallStack msg = error (msg ++ "\n" ++ prettyCallStack callStack)
+   g :: HasCallStack => IO ()
+   g = f
 
-Thus, if we call ``errorWithCallStack`` we will get a formatted call-stack
-alongside our error message.
+   h :: HasCallStack => IO ()
+   h = g
 
 .. code-block:: none
 
-   ghci> errorWithCallStack "die"
-   *** Exception: die
+   ghci> h
+   *** Exception: bad bad bad
    CallStack (from HasCallStack):
-     errorWithCallStack, called at <interactive>:2:1 in interactive:Ghci1
+     error, called at call-stack.hs:4:5 in main:Main
+     f, called at call-stack.hs:7:5 in main:Main
+     g, called at call-stack.hs:10:5 in main:Main
+     h, called at <interactive>:28:1 in interactive:Ghci1
 
 The ``CallStack`` will only extend as far as the types allow it, for
 example ::