users-guide: Fix various warnings

11 files changed, 109 insertions, 82 deletions

diff --git a/docs/users_guide/8.10.1-notes.rst b/docs/users_guide/8.10.1-notes.rst
index e5909c95fa..77c1469639 100644
--- a/docs/users_guide/8.10.1-notes.rst
+++ b/docs/users_guide/8.10.1-notes.rst
@@ -147,7 +147,7 @@ Compiler
 - Add new flag :ghc-flag:`-fkeep-going` which makes the compiler
   continue as far as it can despite errors.
 
-- Deprecated flag :ghc-flag:`-fwarn-hi-shadowing` because it was not
+- Deprecated flag ``-fwarn-hi-shadowing`` because it was not
   implemented correctly, and appears to be largely unused. This flag
   will be removed in a later version of GHC.
 
diff --git a/docs/users_guide/8.6.1-notes.rst b/docs/users_guide/8.6.1-notes.rst
index 341f3b8955..45c2b10b06 100644
--- a/docs/users_guide/8.6.1-notes.rst
+++ b/docs/users_guide/8.6.1-notes.rst
@@ -143,7 +143,7 @@ Compiler
 ~~~~~~~~
 
 - GHC now no longer adds the current file's directory as a general include path
-  calling the C compiler. Instead we use :ghc-flag:`-iquote` to only add it as
+  calling the C compiler. Instead we use ``-iquote`` to only add it as
   an include path for `#include ""`. See :ghc-ticket:`14312`.
 
 - GHC now supports British spelling of :extension:`GeneralizedNewtypeDeriving`.
diff --git a/docs/users_guide/8.8.1-notes.rst b/docs/users_guide/8.8.1-notes.rst
index 59b8bf6b74..71061ed5a3 100644
--- a/docs/users_guide/8.8.1-notes.rst
+++ b/docs/users_guide/8.8.1-notes.rst
@@ -138,7 +138,7 @@ Runtime system
   See :ghc-ticket:`13617`. Note that committed memory may be slightly higher.
 
 - The output filename used for :ref:`eventlog output <rts-eventlog>` can now be
-  specified with the :rts-flag:`-ol` flag.
+  specified with the :rts-flag:`-ol ⟨filename⟩` flag.
 
 - Add support for generating a new type of output: extended interfaces files.
   Generation of these files, which sport a ``.hie`` suffix, is enabled via the
diff --git a/docs/users_guide/ffi-chap.rst b/docs/users_guide/ffi-chap.rst
index ecfece9dc6..a34b0286dd 100644
--- a/docs/users_guide/ffi-chap.rst
+++ b/docs/users_guide/ffi-chap.rst
@@ -424,9 +424,10 @@ reliably re-initialise after this has happened; see :ref:`infelicities-ffi`.
 
 To use ``+RTS`` flags with ``hs_init()``, we have to modify the example
 slightly. By default, GHC's RTS will only accept "safe" ``+RTS`` flags (see
-:ref:`options-linker`), and the :ghc-flag:`-rtsopts[=⟨none|some|all⟩]`
-link-time flag overrides this. However, :ghc-flag:`-rtsopts[=⟨none|some|all⟩]`
-has no effect when :ghc-flag:`-no-hs-main` is in use (and the same goes for
+:ref:`options-linker`), and the :ghc-flag:`-rtsopts[=⟨none|some|all|ignore|ignoreAll⟩]`
+link-time flag overrides this. However,
+:ghc-flag:`-rtsopts[=⟨none|some|all|ignore|ignoreAll⟩]` has no effect when
+:ghc-flag:`-no-hs-main` is in use (and the same goes for
 :ghc-flag:`-with-rtsopts=⟨opts⟩`). To set these options we have to call a
 GHC-specific API instead of ``hs_init()``:
 
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst
index 10a9358a6f..857a03aecd 100644
--- a/docs/users_guide/ghci.rst
+++ b/docs/users_guide/ghci.rst
@@ -1434,9 +1434,14 @@ triggered (see :ref:`nested-breakpoints`). Rather than forcing thunks,
 :ghci-cmd:`:print` binds each thunk to a fresh variable beginning with an
 underscore, in this case ``_t1``.
 
-The flag :ghc-flag:`-fprint-evld-with-show` instructs :ghci-cmd:`:print` to reuse
-available ``Show`` instances when possible. This happens only when the
-contents of the variable being inspected are completely evaluated.
+.. ghc-flag:: -fprint-evld-with-show
+    :shortdesc: Instruct :ghci-cmd:`:print` to use ``Show`` instances where possible.
+    :category: interactive
+    :type: dynamic
+
+    The flag :ghc-flag:`-fprint-evld-with-show` instructs :ghci-cmd:`:print` to reuse
+    available ``Show`` instances when possible. This happens only when the
+    contents of the variable being inspected are completely evaluated.
 
 If we aren't concerned about preserving the evaluatedness of a variable, we can
 use :ghci-cmd:`:force` instead of :ghci-cmd:`:print`. The :ghci-cmd:`:force`
@@ -2572,7 +2577,7 @@ commonly used commands.
     The command will match ⟨type⟩ with the first parameter of every
     instance and then check that all constraints are satisfiable.
 
-    When combined with ``-XPartialTypeSignatures``, a user can insert
+    When combined with :extension:`PartialTypeSignatures`, a user can insert
     wildcards into a query and learn the constraints required of each
     wildcard for ⟨type⟩ match with an instance.
 
@@ -3399,13 +3404,14 @@ providing it with a temporary folder (where it will copy the
 necessary libraries to load to) and port it will listen for
 the proxy to connect.
 
-Providing :ghc-flag:`-pgmi /path/to/iserv-proxy`, :ghc-flag:`-pgmo ⟨option⟩`
-and :ghc-flag:`-pgmo ⟨port⟩` in addition to :ghc-flag:`-fexternal-interpreter`
-will then make ghc go through the proxy instead.
+Providing :ghc-flag:`-pgmi /path/to/iserv-proxy <-pgmi ⟨cmd⟩>`,
+:ghc-flag:`-pgmo ⟨option⟩` and :ghc-flag:`-pgmo ⟨port⟩` in addition to
+:ghc-flag:`-fexternal-interpreter` will then make ghc go through the proxy
+instead.
 
 There are some limitations when using this. File and process IO
-will be executed on the target. As such packages like git-embed,
-file-embed and others might not behave as expected if the target
+will be executed on the target. As such packages like ``git-embed``,
+``file-embed`` and others might not behave as expected if the target
 and host do not share the same filesystem.
 
 .. _ghci-faq:
diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index 4323bee042..142509a4c8 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -2307,7 +2307,9 @@ 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)::
+the ``lexp`` nonterminal thus (``*`` indicates a rule of interest)
+
+.. code-block:: none
 
     lexp  →  \ apat1 … apatn -> exp            (lambda abstraction, n ≥ 1)  *
           |  let decls in exp                  (let expression)             *
@@ -2327,7 +2329,9 @@ the ``lexp`` nonterminal thus (``*`` indicates a rule of interest)::
           |  …
 
 The :extension:`BlockArguments` extension moves these production rules under
-``aexp``::
+``aexp``
+
+.. code-block:: none
 
     lexp  →  fexp
 
@@ -3962,12 +3966,9 @@ GHC extends this mechanism along several axes:
 Deriving instances for empty data types
 ---------------------------------------
 
-.. ghc-flag:: -XEmptyDataDeriving
+.. extension:: EmptyDataDeriving
     :shortdesc: Allow deriving instances of standard type classes for
                 empty data types.
-    :type: dynamic
-    :reverse: -XNoEmptyDataDeriving
-    :category:
 
     :since: 8.4.1
 
@@ -4617,8 +4618,8 @@ Deriving ``Data`` instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. extension:: DeriveDataTypeable
-    :shortdesc: Enable deriving for the Data class.
-       Implied by (deprecated) :extension:`AutoDeriveTypeable`.
+    :shortdesc: Enable deriving for the ``Data`` class.
+       Implied by (deprecated) ``AutoDeriveTypeable``.
 
     :since: 6.8.1
 
@@ -10446,7 +10447,7 @@ The ``context =>`` part is optional.  That is the only syntactic change to the l
 
 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
+- Where GHC allows extensions instance declarations we allow exactly the same extensions to this new form of ``class``.  Specifically, with :extension:`ExplicitForAll` and :extension:`MultiParamTypeClasses` the syntax becomes
 
   .. code-block:: none
 
@@ -11246,7 +11247,7 @@ assumptions", and a related `blog post
 
 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
+:extension:`NoMonoLocalBinds <MonoLocalBinds>` but type inference becomes
 less predictable if you do so. (Read the papers!)
 
 .. _visible-type-application:
@@ -11704,11 +11705,9 @@ monomorphic. This is important because by default GHC will not
 instantiate type variables to a polymorphic type
 (:ref:`impredicative-polymorphism`).
 
-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.)
+The obsolete language option :extension:`Rank2Types` is a synonym for
+:extension:`RankNTypes`. They used to specify finer distinctions that GHC no
+longer makes.
 
 .. _univ:
 
@@ -12493,6 +12492,7 @@ Sorting can be toggled with :ghc-flag:`-fsort-valid-hole-fits`
     :shortdesc: Disables the sorting of the list of valid hole fits for typed holes
         in type error messages.
     :type: dynamic
+    :reverse: -fsort-valid-hole-fits
     :category: verbosity
 
     :default: off
@@ -12957,8 +12957,8 @@ Enabling deferring of type errors
 
 The flag :ghc-flag:`-fdefer-type-errors` controls whether type errors are
 deferred to runtime. Type errors will still be emitted as warnings, but
-will not prevent compilation. You can use :ghc-flag:`-Wno-type-errors
-<-Wtype-errors>` to suppress these warnings.
+will not prevent compilation. You can use :ghc-flag:`-Wno-deferred-type-errors`
+to suppress these warnings.
 
 This flag implies the :ghc-flag:`-fdefer-typed-holes` and
 :ghc-flag:`-fdefer-out-of-scope-variables` flags, which enables this behaviour
@@ -15264,7 +15264,7 @@ used if you want your code to be portable).
     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`.
+matching in :pragma:`RULE <RULES>`\s (only). See :ref:`conlike`.
 
 .. _phase-control:
 
@@ -15316,7 +15316,7 @@ arguments etc). Another way to understand the semantics is this:
    body look small, so that when inlining is allowed it is very likely
    to happen.
 
-The same phase-numbering control is available for :pragma:`RULE`\s
+The same phase-numbering control is available for :pragma:`RULE <RULES>`\s
 (:ref:`rewrite-rules`).
 
 .. _line-pragma:
@@ -15521,9 +15521,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 :pragma:`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.
@@ -15935,12 +15935,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 :pragma:`RULE` "``forall``" is treated as a keyword, regardless of any
-   other flag settings. Furthermore, inside a RULE, the language
+-  Inside a :pragma:`RULES` "``forall``" is treated as a keyword, regardless of any
+   other flag settings. Furthermore, inside a :pragma:`RULES`, the language
    extension :extension:`ScopedTypeVariables` is automatically enabled; see
    :ref:`scoped-type-variables`.
 
--  Like other pragmas, :pragma:`RULE` pragmas are always checked for scope errors,
+-  Like other pragmas, :pragma:`RULES` 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
@@ -16029,13 +16029,13 @@ give ::
 
     g y = y
 
-Now ``g`` is inlined into ``h``, but ``f``\'s :pragma:`RULE` has no chance to
+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 :pragma:`RULE` might fire.
+been a better chance that ``f``\'s :pragma:`RULES` might fire.
 
 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
+``INLINE[⟨phase⟩]`` pragma, on ``f``, to ensure that it is not inlined until
+its :pragma:`RULES` have had a chance to fire. The warning flag
 :ghc-flag:`-Winline-rule-shadowing` (see :ref:`options-sanity`) warns about
 this situation.
 
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index fa28874473..f0479596c1 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -81,11 +81,11 @@ given compilation phase:
     Use ⟨cmd⟩ as the DLL generator.
 
 .. ghc-flag:: -pgmF ⟨cmd⟩
-    :shortdesc: Use ⟨cmd⟩ as the pre-processor (with ``-F`` only)
+    :shortdesc: Use ⟨cmd⟩ as the pre-processor (with :ghc-flag:`-F` only)
     :type: dynamic
     :category: phase-programs
 
-    Use ⟨cmd⟩ as the pre-processor (with ``-F`` only).
+    Use ⟨cmd⟩ as the pre-processor (with :ghc-flag:`-F` only).
 
 .. ghc-flag:: -pgmwindres ⟨cmd⟩
     :shortdesc: Use ⟨cmd⟩ as the program for embedding manifests on Windows.
@@ -98,20 +98,20 @@ given compilation phase:
     :ref:`options-linker`.
 
 .. ghc-flag:: -pgmlibtool ⟨cmd⟩
-    :shortdesc: Use ⟨cmd⟩ as the command for libtool (with ``-staticlib`` only).
+    :shortdesc: Use ⟨cmd⟩ as the command for libtool (with :ghc-flag:`-staticlib` only).
     :type: dynamic
     :category: phase-programs
 
-    Use ⟨cmd⟩ as the libtool command (when using ``-staticlib`` only).
+    Use ⟨cmd⟩ as the libtool command (when using :ghc-flag:`-staticlib` only).
 
 .. ghc-flag:: -pgmi ⟨cmd⟩
     :shortdesc: Use ⟨cmd⟩ as the external interpreter command.
     :type: dynamic
     :category: phase-programs
 
-    Use ⟨cmd⟩ as the external interpreter command (see:
+    Use ⟨cmd⟩ as the external interpreter command (see
     :ref:`external-interpreter`).  Default: ``ghc-iserv-prof`` if
-    ``-prof`` is enabled, ``ghc-iserv-dyn`` if ``-dynamic`` is
+    :ghc-flag:`-prof` is enabled, ``ghc-iserv-dyn`` if :ghc-flag:`-dynamic` is
     enabled, or ``ghc-iserv`` otherwise.
 
 .. _forcing-options-through:
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index 1a083eb711..b6db42ace1 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -658,7 +658,7 @@ To generate a heap profile from your program:
    :rts-flag:`-h` for a basic producer profile). This generates the file
    :file:`{prog}.hp`.
 
-   If the :ref:`event log <rts-eventlog>` is enabled (with the :rts-flag:`-l`
+   If the :ref:`event log <rts-eventlog>` is enabled (with the :rts-flag:`-l ⟨flags⟩`
    runtime system flag) heap samples will additionally be emitted to the GHC
    event log (see :ref:`heap-profiler-events` for details about event format).
 
diff --git a/docs/users_guide/runtime_control.rst b/docs/users_guide/runtime_control.rst
index 32d665da66..665c8c08e0 100644
--- a/docs/users_guide/runtime_control.rst
+++ b/docs/users_guide/runtime_control.rst
@@ -50,9 +50,9 @@ Setting RTS options on the command line
    single: -RTS
    single: --RTS
 
-If you set the :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` flag appropriately when
-linking (see :ref:`options-linker`), you can give RTS options on the command
-line when running your program.
+If you set the :ghc-flag:`-rtsopts[=⟨none|some|all|ignore|ignoreAll⟩]` flag
+appropriately when linking (see :ref:`options-linker`), you can give RTS
+options on the command line when running your program.
 
 When your Haskell program starts up, the RTS extracts command-line
 arguments bracketed between ``+RTS`` and ``-RTS`` as its own. For example:
@@ -177,8 +177,8 @@ e.g., on stack overflow. The hooks for these are as follows:
 Event log output
 ################
 
-Furthermore GHC lets you specify the way event log data (see :rts-flag:`-l`) is
-written through a custom :c:type:`EventLogWriter`:
+Furthermore GHC lets you specify the way event log data (see :rts-flag:`-l
+⟨flags⟩`) is written through a custom :c:type:`EventLogWriter`:
 
 .. c:type:: EventLogWriter
 
@@ -415,10 +415,10 @@ performance.
     The compaction algorithm is slower than the copying algorithm, but
     the savings in memory use can be considerable.
 
-    For a given heap size (using the :ghc-flag:`-H ⟨size⟩` option), compaction
-    can in fact reduce the GC cost by allowing fewer GCs to be performed. This
-    is more likely when the ratio of live data to heap size is high, say
-    greater than 30%.
+    For a given heap size (using the :rts-flag:`-H [⟨size⟩]` option),
+    compaction can in fact reduce the GC cost by allowing fewer GCs to be
+    performed. This is more likely when the ratio of live data to heap size is
+    high, say greater than 30%.
 
     .. note::
        Compaction doesn't currently work when a single generation is
@@ -1104,7 +1104,8 @@ When the program is linked with the :ghc-flag:`-eventlog` option
     :default: :file:`<program>.eventlog`
     :since: 8.8
 
-    Sets the destination for the eventlog produced with the :rts-flag:`-l` flag.
+    Sets the destination for the eventlog produced with the
+    :rts-flag:`-l ⟨flags⟩` flag.
 
 .. rts-flag:: -v [⟨flags⟩]
 
@@ -1173,8 +1174,8 @@ recommended for everyday use!
 .. rts-flag::  -DC  DEBUG: compact
 
     Debug messages will be sent to the binary event log file instead of
-    stdout if the :rts-flag:`-l` option is added. This might be useful for
-    reducing the overhead of debug tracing.
+    stdout if the :rts-flag:`-l ⟨flags⟩` option is added. This might be useful
+    for reducing the overhead of debug tracing.
 
     To figure out what exactly they do, the least bad way is to grep the rts/ directory in
     the ghc code for macros like ``DEBUG(scheduler`` or ``DEBUG_scheduler``.
diff --git a/docs/users_guide/sooner.rst b/docs/users_guide/sooner.rst
index 21b280f0dc..8edff579ac 100644
--- a/docs/users_guide/sooner.rst
+++ b/docs/users_guide/sooner.rst
@@ -31,10 +31,10 @@ Use more memory:
        single: -H; RTS option
 
     If it says you're using more than 20% of total time in garbage collecting,
-    then more memory might help: use the ``-H⟨size⟩`` (see :rts-flag:`-H
-    [⟨size⟩]`) option. Increasing the default allocation area size used by the
-    compiler's RTS might also help: use the ``+RTS -A⟨size⟩ -RTS`` option (see
-    :rts-flag:`-A ⟨size⟩`).
+    then more memory might help: use the ``-H⟨size⟩`` (see
+    :rts-flag:`-H [⟨size⟩]`) option. Increasing the default allocation area
+    size used by the compiler's RTS might also help: use the ``+RTS -A⟨size⟩
+    -RTS`` option (see :rts-flag:`-A ⟨size⟩`).
 
     .. index::
        single: -A⟨size⟩; RTS option
@@ -305,11 +305,12 @@ Use unboxed arrays (``UArray``)
 Use a bigger heap!
     If your program's GC stats (:rts-flag:`-S [⟨file⟩]` RTS option) indicate
     that it's doing lots of garbage-collection (say, more than 20% of execution
-    time), more memory might help — with the :rts-flag:`-H⟨size⟩` or :rts-flag:`-A⟨size⟩` RTS
-    options (see :ref:`rts-options-gc`). As a rule of thumb, try setting
-    :rts-flag:`-H ⟨size⟩` to the amount of memory you're willing to let your process
-    consume, or perhaps try passing :ghc-flag:`-H ⟨size⟩` without any argument
-    to let GHC calculate a value based on the amount of live data.
+    time), more memory might help — with the :rts-flag:`-H [⟨size⟩]` or
+    :rts-flag:`-A ⟨size⟩` RTS options (see :ref:`rts-options-gc`). As a rule
+    of thumb, try setting :rts-flag:`-H [⟨size⟩]` to the amount of memory
+    you're willing to let your process consume, or perhaps try passing
+    :rts-flag:`-H [⟨size⟩]` without any argument to let GHC calculate a value
+    based on the amount of live data.
 
 Compact your data:
     The :ghc-compact-ref:`GHC.Compact.` module
@@ -350,7 +351,7 @@ Thriftier: producing a program that gobbles less heap space
 
 "I think I have a space leak..."
 
-Re-run your program with :ghc-flag:`+RTS -S <-S [⟨file⟩]>`, and remove all
+Re-run your program with :rts-flag:`+RTS -S <-S [⟨file⟩]>`, and remove all
 doubt! (You'll see the heap usage get bigger and bigger...) (Hmmm... this might
 be even easier with the :rts-flag:`-G1 <-G ⟨generations⟩>` RTS option; so...
 ``./a.out +RTS -S -G1``)
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index cea8e9b780..30c86596d1 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -319,9 +319,8 @@ of ``-W(no-)*``.
 .. ghc-flag:: -Wpartial-type-signatures
     :shortdesc: warn about holes in partial type signatures when
         :extension:`PartialTypeSignatures` is enabled. Not applicable when
-        :extension:`PartialTypesignatures` is not enabled, in which case
-        errors are generated for such holes. See
-        :ref:`partial-type-signatures`.
+        :extension:`PartialTypeSignatures` is not enabled, in which case
+        errors are generated for such holes.
     :type: dynamic
     :reverse: -Wno-partial-type-signatures
     :category:
@@ -643,15 +642,15 @@ of ``-W(no-)*``.
 
 .. ghc-flag:: -Wderiving-defaults
     :shortdesc: warn about default deriving when using both
-        DeriveAnyClass and GeneralizedNewtypeDeriving
+        :extension:`DeriveAnyClass` and :extension:`GeneralizedNewtypeDeriving`
     :type: dynamic
     :reverse: -Wno-deriving-defaults
     :category:
 
     :since: 8.10
 
-    Causes a warning when both :ref:`DeriveAnyClass` and
-    :ref:`GeneralizedNewtypeDeriving` are enabled and no explicit
+    Causes a warning when both :extension:`DeriveAnyClass` and
+    :extension:`GeneralizedNewtypeDeriving` are enabled and no explicit
     deriving strategy is in use.  For example, this would result a
     warning: ::
 
@@ -756,6 +755,24 @@ of ``-W(no-)*``.
     probably no-ops and can be omitted. The functions checked for are:
     ``toInteger``, ``toRational``, ``fromIntegral``, and ``realToFrac``.
 
+.. ghc-flag:: -Wimplicit-kind-vars
+    :shortdesc: warn when kind variables are implicitly quantified over.
+    :type: dynamic
+    :reverse: -Wno-implicit-kind-vars
+    :category:
+
+    .. index::
+       single: implicit prelude, warning
+
+    Have the compiler warn if a kind variable is not explicitly quantified
+    over. For instance, the following would produce a warning: ::
+
+        f :: forall (a :: k). Proxy a
+
+    This can be fixed by explicitly quantifying over ``k``: ::
+
+        f :: forall k (a :: k). Proxy a
+
 .. ghc-flag:: -Wimplicit-prelude
     :shortdesc: warn when the Prelude is implicitly imported
     :type: dynamic
@@ -835,7 +852,7 @@ of ``-W(no-)*``.
     ``Just y`` but ``y`` is not ``4``.
 
     This can be exponential in the arity of the pattern and in the number of
-    guards in some cases. The :ghc-flag:`-fmax-pmcheck-models` limit makes sure
+    guards in some cases. The :ghc-flag:`-fmax-pmcheck-models=⟨n⟩` limit makes sure
     we scale polynomially in the number of patterns, by forgetting refined
     information gained from a partially successful match. For the above example,
     if we had a limit of 1, we would continue checking the next clause with the
@@ -1705,8 +1722,9 @@ of ``-W(no-)*``.
     :since: 8.8
 
     The option :ghc-flag:`-Wunused-packages` warns about packages, specified on
-    command line via :ghc-flag:`-package` or :ghc-flag:`-package-id`, but were not
-    loaded during compication. Usually it means that you have an unused dependency.
+    command line via :ghc-flag:`-package ⟨pkg⟩` or
+    :ghc-flag:`-package-id ⟨unit-id⟩`, but were not loaded during compication.
+    Usually it means that you have an unused dependency.
 
     You may want to enable this warning on a clean build or enable :ghc-flag:`-fforce-recomp`
     in order to get reliable results.