Fix more documentation wibbles

Fixes #14020, #14016, #14015, #14019

21 files changed, 165 insertions, 119 deletions

diff --git a/docs/users_guide/8.0.2-notes.rst b/docs/users_guide/8.0.2-notes.rst
index 11e15405ed..7212f06ba8 100644
--- a/docs/users_guide/8.0.2-notes.rst
+++ b/docs/users_guide/8.0.2-notes.rst
@@ -158,7 +158,7 @@ Compiler
    (:ghc-ticket:`4012`)
 
 - Nearly two-hundred more bugs. See `Trac
-   <https://ghc.haskell.org/trac/ghc/query?status=closed&milestone=8.0.2&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority>`_
+   <https://ghc.haskell.org/trac/ghc/query?status=closed&milestone=8.0.2&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority>`__
    for a complete list.
 
 Runtime system
diff --git a/docs/users_guide/8.2.1-notes.rst b/docs/users_guide/8.2.1-notes.rst
index d3ec4476c2..43134faeba 100644
--- a/docs/users_guide/8.2.1-notes.rst
+++ b/docs/users_guide/8.2.1-notes.rst
@@ -187,7 +187,7 @@ Compiler
     -- uses of `Monoid MyMonoid` here are improved
     bar :: MonadWriter MyMonoid m => ...
 
-- GHC now derives the definition of ``<$`` when using :ghc-flag:`DeriveFunctor`
+- GHC now derives the definition of ``<$`` when using :ghc-flag:`-XDeriveFunctor`
   rather than using the default definition. This prevents unnecessary
   allocation and a potential space leak when deriving ``Functor`` for
   a recursive type.
@@ -231,8 +231,8 @@ Compiler
     instance Foo (Either a b) where
       type Bar (Either a b) = b -> a
 
-  See the section on `associated type family instances <assoc-data-inst>` for
-  more information.
+  See the section on :ref:`associated type family instances <assoc-data-inst>`
+  for more information.
 
 - A bug involving the interaction between :ghc-flag:`-XMonoLocalBinds` and
   :ghc-flag:`-XPolyKinds` has been fixed. This can cause some programs to fail
@@ -311,7 +311,7 @@ Runtime system
 
 - Heap overflow throws a catchable exception, provided that it was detected
   by the RTS during a GC cycle due to the program exceeding a limit set by
-  ``+RTS -M`` (see :rts-flag:`-M`), and not due to an allocation being refused
+  ``+RTS -M`` (see :rts-flag:`-M ⟨size⟩`), and not due to an allocation being refused
   by the operating system. This exception is thrown to the same thread that
   receives ``UserInterrupt`` exceptions, and may be caught by user programs.
 
@@ -346,12 +346,13 @@ Runtime system
   threads to all cores in systems which have multiple processor groups.
   (e.g. > 64 cores, see :ghc-ticket:`11054`)
 
-- Output of :ref:`Event log <rts-eventlog>` data can now be configured.
-  Enabling external tools to collect and analyze the event log data while the
+- Output of :ref:`Event log <rts-eventlog>` data can now be configured,
+  enabling external tools to collect and analyze the event log data while the
   application is still running.
 
-- advapi32, shell32 and user32 are now automatically loaded in GHCi. libGCC is also
-  loaded when a depencency requires it. See :ghc-ticket:`13189`.
+- ``advapi32``, ``shell32`` and ``user32`` are now automatically loaded in GHCi.
+  ``libGCC`` is also loaded when a dependency requires it. See
+  :ghc-ticket:`13189`.
 
 hsc2hs
 ~~~~~~
diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py
index 12ecee9beb..3af6ac109e 100644
--- a/docs/users_guide/conf.py
+++ b/docs/users_guide/conf.py
@@ -12,7 +12,7 @@ import os
 sys.path.insert(0, os.path.abspath('.'))
 from ghc_config import extlinks, version
 
-extensions = ['sphinx.ext.extlinks']
+extensions = ['sphinx.ext.extlinks', 'sphinx.ext.mathjax']
 
 templates_path = ['.templates']
 source_suffix = '.rst'
diff --git a/docs/users_guide/editing-guide.rst b/docs/users_guide/editing-guide.rst
index cf2ebdd9d3..b57a5d12b9 100644
--- a/docs/users_guide/editing-guide.rst
+++ b/docs/users_guide/editing-guide.rst
@@ -222,6 +222,8 @@ commands for referring to documentation for the following core GHC packages,
 * ``cabal``: ``:cabal-ref:``
 * ``ghc-prim``: ``:ghc-prim-ref:``
 
+These are defined in :file:`docs/users_guide/ghc_config.py.in`.
+
 For instance,
 
 .. code-block:: rest
@@ -229,6 +231,19 @@ For instance,
     See the documentation for :base-ref:`Control.Applicative <Control-Applicative.html>`
     for details.
 
+Math
+^^^^
+
+You can insert type-set equations using ``:math:``. For instance,
+
+.. code-block:: rest
+
+    Fick's law of diffusion, :math:`J = -D \frac{d \varphi}{d x}`, ...
+
+will render as,
+
+    Fick's law of diffusion, :math:`J = -D \frac{d \varphi}{d x}`, ...
+
 
 Index entries
 ~~~~~~~~~~~~~
diff --git a/docs/users_guide/ffi-chap.rst b/docs/users_guide/ffi-chap.rst
index c40b623800..c653596646 100644
--- a/docs/users_guide/ffi-chap.rst
+++ b/docs/users_guide/ffi-chap.rst
@@ -4,10 +4,13 @@ Foreign function interface (FFI)
 ================================
 
 .. index::
-   single: -XForeignFunctionInterface
    single: Foreign function interface
    single: interfacing with native code
 
+.. ghc-flag:: -XForeignFunctionInterface
+
+    Allow use of the Haskell foreign function interface.
+
 GHC (mostly) conforms to the Haskell Foreign Function Interface, whose
 definition is part of the Haskell Report on
 `http://www.haskell.org/ <http://www.haskell.org/>`__.
diff --git a/docs/users_guide/ghc_config.py.in b/docs/users_guide/ghc_config.py.in
index 6711c6b560..7be8783dcf 100644
--- a/docs/users_guide/ghc_config.py.in
+++ b/docs/users_guide/ghc_config.py.in
@@ -1,10 +1,12 @@
 extlinks = {
     'base-ref': ('../libraries/base-@LIBRARY_base_VERSION@/%s', ''),
     'cabal-ref': ('../libraries/Cabal-@LIBRARY_Cabal_VERSION@/%s', ''),
-    'compact-ref': ('../libraries/ghc-compact-@LIBRARY_compact_VERSION@/%s', ''),
+    'compact-ref': ('../libraries/ghc-compact-@LIBRARY_ghc_compact_VERSION@/%s', ''),
     'ghc-prim-ref': ('../libraries/ghc-prim-@LIBRARY_ghc_prim_VERSION@/%s', ''),
-    'ghc-ticket': ('http://ghc.haskell.org/trac/ghc/ticket/%s', 'Trac #'),
-    'ghc-wiki': ('http://ghc.haskell.org/trac/ghc/wiki/%s', 'Trac #'),
+    'th-ref': ('../libraries/template-haskell-@LIBRARY_template_haskell_VERSION@/%s', ''),
+
+    'ghc-ticket': ('https://ghc.haskell.org/trac/ghc/ticket/%s', 'Trac #'),
+    'ghc-wiki': ('https://ghc.haskell.org/trac/ghc/wiki/%s', 'Trac #'),
 }
 
 version = '@ProjectVersion@'
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst
index 8405af163e..dce790416a 100644
--- a/docs/users_guide/ghci.rst
+++ b/docs/users_guide/ghci.rst
@@ -480,6 +480,11 @@ instead of layout:
     6
     Prelude>
 
+.. ghci-cmd:: :{
+              :}
+
+    Begin or end a multi-line GHCi command block.
+
 To alleviate this issue, GHCi commands can be split over multiple lines,
 by wrapping them in ``:{`` and ``:}`` (each on a single line of its
 own):
diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index 78b39924be..fddf993485 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -4643,6 +4643,10 @@ Note the following details
 Deriving strategies
 -------------------
 
+.. ghc-flag:: -XDerivingStrategies
+
+    Allow multiple ``deriving``, each optionally qualified with a *strategy*.
+
 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
@@ -4693,8 +4697,8 @@ Currently, the deriving strategies are:
 
 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 at
-:ghc-wiki:`Wiki page <DerivingStrategies>`.
+is omitted here. You can read the full algorithm on the
+:ghc-wiki:`GHC Wiki <Commentary/Compiler/DerivingStrategies>`.
 
 .. _pattern-synonyms:
 
@@ -7119,6 +7123,7 @@ Decidability of type synonym instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. ghc-flag:: -XUndecidableInstances
+    :noindex:
 
     Relax restrictions on the decidability of type synonym family instances.
 
@@ -9969,7 +9974,7 @@ Here we do not need to give a type signature to ``w``, because it is an
 argument of constructor ``T1`` and that tells GHC all it needs to know.
 
 
-.. _implicit-quant:
+.. _implicit-quantification:
 
 Implicit quantification
 -----------------------
@@ -10126,14 +10131,15 @@ Here are some more details:
    containing holes, by using the :ghc-flag:`-fdefer-typed-holes` flag. This
    flag defers errors produced by typed holes until runtime, and
    converts them into compile-time warnings. These warnings can in turn
-   be suppressed entirely by :ghc-flag:`-fno-warn-typed-holes`.
+   be suppressed entirely by :ghc-flag:`-Wno-typed-holes <-Wtyped-holes>`.
 
    The same behaviour for "``Variable out of scope``" errors, it terminates
    compilation by default. You can defer such errors by using the
    :ghc-flag:`-fdefer-out-of-scope-variables` flag. This flag defers errors
    produced by out of scope variables until runtime, and
    converts them into compile-time warnings. These warnings can in turn
-   be suppressed entirely by :ghc-flag:`-fno-warn-deferred-out-of-scope-variables`.
+   be suppressed entirely by :ghc-flag:`-Wno-deferred-out-of-scope-variables
+   <-Wdeferred-out-of-scope-variables>`.
 
    The result is that a hole or a variable will behave like ``undefined``, but with
    the added benefits that it shows a warning at compile time, and will
@@ -10662,17 +10668,18 @@ 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-deferred-type-errors <-Wdeferred-type-errors>` to suppress these
-warnings.
+will not prevent compilation. You can use :ghc-flag:`-Wno-type-errors
+<-Wtype-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 for `typed holes <#typed-holes>`__ and variables. Should you so wish, it is
+:ghc-flag:`-fdefer-out-of-scope-variables` flags, which enables this behaviour
+for `typed holes <#typed-holes>`__ and variables. Should you so wish, it is
 possible to enable :ghc-flag:`-fdefer-type-errors` without enabling
 :ghc-flag:`-fdefer-typed-holes` or :ghc-flag:`-fdefer-out-of-scope-variables`,
-by explicitly specifying :ghc-flag:`-fno-defer-typed-holes` or :ghc-flag:`-fno-defer-out-of-scope-variables`
-on the command-line after the :ghc-flag:`-fdefer-type-errors` flag.
+by explicitly specifying :ghc-flag:`-fno-defer-typed-holes
+<-fdefer-typed-holes>` or :ghc-flag:`-fno-defer-out-of-scope-variables
+<-fdefer-out-of-scope-variables>` on the command-line after the
+:ghc-flag:`-fdefer-type-errors` flag.
 
 At runtime, whenever a term containing a type error would need to be
 evaluated, the error is converted into a runtime exception of type
@@ -10713,7 +10720,9 @@ Otherwise, in the common case of a simple type error such as typing
 immediately-following type error when the expression is evaluated.
 
 This exception doesn't apply to statements, as the following example
-demonstrates: ::
+demonstrates:
+
+.. code-block:: none
 
     Prelude> let x = (True, 1 == 'a')
 
@@ -10737,12 +10746,10 @@ in "`Template Meta-programming for
 Haskell <http://research.microsoft.com/~simonpj/papers/meta-haskell/>`__"
 (Proc Haskell Workshop 2002).
 
-There is a Wiki page about Template Haskell at
-http://www.haskell.org/haskellwiki/Template_Haskell, and that is the
-best place to look for further details. You may also consult the `online
-Haskell library reference
-material <http://www.haskell.org/ghc/docs/latest/html/libraries/index.html>`__
-(look for module ``Language.Haskell.TH``). Many changes to the original
+The `Template Haskell <http://www.haskell.org/haskellwiki/Template_Haskell>`__
+page on the GHC Wiki has a wealth of information. You may also consult the
+:th-ref:`Haddock reference documentation <Language-Haskell-TH.html>`.
+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>`__.
 Not all of these changes are in GHC, however.
diff --git a/docs/users_guide/packages.rst b/docs/users_guide/packages.rst
index 3ed9455857..de7cc464d8 100644
--- a/docs/users_guide/packages.rst
+++ b/docs/users_guide/packages.rst
@@ -825,7 +825,7 @@ in ``list``, ``describe``, and ``field``, where a ``'*'`` indicates open
 substring ends (``prefix*``, ``*suffix``, ``*infix*``). Examples (output
 omitted):
 
-::
+.. code-block:: none
 
     -- list all regex-related packages
     ghc-pkg list '*regex*' --ignore-case
diff --git a/docs/users_guide/parallel.rst b/docs/users_guide/parallel.rst
index bac7754a29..68cbebf0d6 100644
--- a/docs/users_guide/parallel.rst
+++ b/docs/users_guide/parallel.rst
@@ -80,10 +80,10 @@ Parallel Haskell
 GHC includes support for running Haskell programs in parallel on
 symmetric, shared-memory multi-processor (SMP). By default GHC runs
 your program on one processor; if you want it to run in parallel you
-must link your program with the ``-threaded``, and run it with the RTS
-``-N`` option; see :ref:`using-smp`). The runtime will schedule the
-running Haskell threads among the available OS threads, running as many
-in parallel as you specified with the ``-N`` RTS option.
+must link your program with the :ghc-flag:`-threaded`, and run it with the RTS
+:rts-flag:`-N ⟨x⟩` option; see :ref:`using-smp`). The runtime will schedule the
+running Haskell threads among the available OS threads, running as many in
+parallel as you specified with the :rts-flag:`-N ⟨x⟩` RTS option.
 
 Annotating pure code for parallelism
 ------------------------------------
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index 18742627be..cefaa8a6d1 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -163,12 +163,15 @@ Options affecting the C pre-processor
 
 .. ghc-flag:: -D⟨symbol⟩[=⟨value⟩]
 
-    Define macro ⟨symbol⟩ in the usual way. NB: does *not* affect ``-D``
-    macros passed to the C compiler when compiling with :ghc-flag:`-fvia-C`! For
-    those, use the ``-optc-Dfoo`` hack… (see :ref:`forcing-options-through`).
+    Define macro ⟨symbol⟩ in the usual way. When no value is given, the value is
+    taken to be ``1``. For instance, ``-DUSE_MYLIB`` is equivalent to
+    ``-DUSE_MYLIB=1``.
 
-    When no value is given, the value is taken to be ``1``. For instance,
-    ``-DUSE_MYLIB`` is equivalent to ``-DUSE_MYLIB=1``.
+    .. note::
+
+        :ghc-flag:`-D⟨symbol⟩[=⟨value⟩]` does *not* affect ``-D``
+        macros passed to the C compiler when compiling an unregisterised build! In
+        this case use the ``-optc-Dfoo`` hack… (see :ref:`forcing-options-through`).
 
 .. ghc-flag:: -U⟨symbol⟩
 
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index e3796ed7a6..4107db2ebf 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -571,7 +571,6 @@ For instance, a simple profile might look like this,
           "src_loc": "<entire-module>",
           "is_caf": true
         }
-        ...
       ],
       "profile": {
         "id": 162,
@@ -1312,9 +1311,13 @@ case :file:`Recip.tix`, which contains the coverage data for this run of the
 program. The program may be run multiple times (e.g. with different test
 data), and the coverage data from the separate runs is accumulated in
 the ``.tix`` file. To reset the coverage data and start again, just
-remove the ``.tix`` file.  You can control where the ``.tix`` file
+remove the ``.tix`` file. You can control where the ``.tix`` file
 is generated using the environment variable :envvar:`HPCTIXFILE`.
 
+.. envvar:: HPCTIXFILE
+
+    Set the HPC ``.tix`` file output path.
+
 Having run the program, we can generate a textual summary of coverage:
 
 .. code-block:: none
@@ -1566,6 +1569,10 @@ Using “ticky-ticky” profiling (for implementors)
 .. index::
    single: ticky-ticky profiling
 
+.. ghc-flag:: -ticky
+
+   Enable ticky-ticky profiling.
+
 Because ticky-ticky profiling requires a certain familiarity with GHC
 internals, we have moved the documentation to the GHC developers wiki.
 Take a look at its
diff --git a/docs/users_guide/runghc.rst b/docs/users_guide/runghc.rst
index fcc8cf818d..8d1a086599 100644
--- a/docs/users_guide/runghc.rst
+++ b/docs/users_guide/runghc.rst
@@ -16,7 +16,7 @@ Usage
 
 The ``runghc`` command-line looks like:
 
-::
+.. code-block:: none
 
     runghc [runghc flags] [GHC flags] module [program args]
 
diff --git a/docs/users_guide/runtime_control.rst b/docs/users_guide/runtime_control.rst
index 682ced8197..b3ab08f20f 100644
--- a/docs/users_guide/runtime_control.rst
+++ b/docs/users_guide/runtime_control.rst
@@ -84,7 +84,7 @@ As always, for RTS options that take ⟨size⟩s: If the last character of
 or G, by 1,000,000,000. (And any wraparound in the counters is *your*
 fault!)
 
-Giving a ``+RTS -?`` ``-?``\ RTS option option will print out the RTS
+Giving a ``+RTS -?`` RTS option option will print out the RTS
 options actually available in your program (which vary, depending on how
 you compiled).
 
@@ -156,55 +156,51 @@ can override the defaults.
 Owing to the vagaries of DLL linking, these hooks don't work under
 Windows when the program is built dynamically.
 
+Runtime events
+##############
+
 You can change the messages printed when the runtime system "blows up,"
 e.g., on stack overflow. The hooks for these are as follows:
 
-``void OutOfHeapHook (unsigned long, unsigned long)``
-    .. index::
-       single: OutOfHeapHook
+.. c:function:: void OutOfHeapHook (unsigned long, unsigned long)
 
     The heap-overflow message.
 
-``void StackOverflowHook (long int)``
-    .. index::
-       single: StackOverflowHook
+.. c:function:: void StackOverflowHook (long int)
 
     The stack-overflow message.
 
-``void MallocFailHook (long int)``
-    .. index::
-       single: MallocFailHook
+.. c:function:: void MallocFailHook (long int)
 
     The message printed if ``malloc`` fails.
 
-Furthermore GHC lets you specify the way event log data (:rts-flag:`-l`)
-is written through a custom `EventLogWriter`:
+Event log output
+################
 
-``void initEventLogWriter(void)``
-    .. index::
-       single: initEventLogWriter
+Furthermore GHC lets you specify the way event log data (see :rts-flag:`-l`) is
+written through a custom :c:type:`EventLogWriter`:
 
-    Initializes your `EventLogWriter`. This is optional.
+.. c:type:: EventLogWriter
 
-``bool writeEventLog(void *eventlog, size_t eventlog_size)``
-    .. index::
-       single: writeEventLog
+    A sink of event-log data.
 
-    Hands buffered event log data to your event log writer.
-    Required for a custom `EventLogWriter`.
+    .. c:member:: void initEventLogWriter(void)
 
- ``void flushEventLog(void)``
-    .. index::
-       single: flushEventLog
+        Initializes your :c:type:`EventLogWriter`. This is optional.
 
-    Flush buffers (if any) of your custom `EventLogWriter`. This is
-    optional.
+    .. c:member:: bool writeEventLog(void *eventlog, size_t eventlog_size)
 
- ``void stopEventLogWriter(void)``
-    .. index::
-       single: stopEventLogWriter
+        Hands buffered event log data to your event log writer.
+        Required for a custom :c:type:`EventLogWriter`.
+
+    .. c:member:: void flushEventLog(void)
+
+        Flush buffers (if any) of your custom :c:type:`EventLogWriter`. This can
+        be ``NULL``.
+
+    .. c:member:: void stopEventLogWriter(void)
 
-    Called when event logging is about to stop. This is optional.
+        Called when event logging is about to stop. This can be ``NULL``.
 
 .. _rts-options-misc:
 
@@ -214,7 +210,7 @@ Miscellaneous RTS options
 .. rts-flag:: --install-signal-handlers=⟨yes|no⟩
 
     If yes (the default), the RTS installs signal handlers to catch
-    things like ctrl-C. This option is primarily useful for when you are
+    things like :kbd:`Ctrl-C`. This option is primarily useful for when you are
     using the Haskell code as a DLL, and want to set your own signal
     handlers.
 
@@ -294,7 +290,7 @@ performance.
 
 .. rts-flag:: -AL ⟨size⟩
 
-    :default: ``-A`` value
+    :default: :rts-flag:`-A <-A ⟨size⟩>` value
     :since: 8.2.1
 
     .. index::
@@ -302,7 +298,8 @@ performance.
 
     Sets the limit on the total size of "large objects" (objects
     larger than about 3KB) that can be allocated before a GC is
-    triggered.  By default this limit is the same as the ``-A`` value.
+    triggered. By default this limit is the same as the :rts-flag:`-A <-A
+    ⟨size⟩>` value.
 
     Large objects are not allocated from the normal allocation area
     set by the ``-A`` flag, which is why there is a separate limit for
@@ -334,7 +331,7 @@ performance.
 
 .. rts-flag:: -n ⟨size⟩
 
-    :default: 4m with ``-A16m`` or larger, otherwise 0.
+    :default: 4m with :rts-flag:`-A16m <-A ⟨size⟩>` or larger, otherwise 0.
 
     .. index::
        single: allocation area, chunk size
@@ -383,14 +380,13 @@ performance.
        requested using the ``-G1`` option.
 
 .. rts-flag:: -c ⟨n⟩
-    :noindex:
 
     :default: 30
 
     Automatically enable compacting collection when the live data exceeds ⟨n⟩%
     of the maximum heap size (see the :rts-flag:`-M ⟨size⟩` option). Note that
     the maximum heap size is unlimited by default, so this option has no effect
-    unless the maximum heap size is set with ``-M ⟨size⟩.``
+    unless the maximum heap size is set with :rts-flag:`-M ⟨size⟩`.
 
 .. rts-flag:: -F ⟨factor⟩
 
@@ -408,11 +404,10 @@ performance.
 
     The default seems to work well here. If you have plenty of memory, it is
     usually better to use ``-H ⟨size⟩`` (see :rts-flag:`-H [⟨size⟩]`) than to
-    increase ``-F ⟨factor⟩.``
+    increase :rts-flag:`-F ⟨factor⟩`.
 
-    The ``-F ⟨factor⟩`` setting will be automatically reduced by the garbage
-    collector when the maximum heap size (the ``-M ⟨size⟩`` setting, see
-    :rts-flag:`-M ⟨size⟩`) is approaching.
+    The :rts-flag:`-F ⟨factor⟩` setting will be automatically reduced by the garbage
+    collector when the maximum heap size (the :rts-flag:`-M ⟨size⟩` setting) is approaching.
 
 .. rts-flag:: -G ⟨generations⟩
 
@@ -444,17 +439,17 @@ performance.
     parallel GC completely, reverting to sequential GC.
 
     The default parallel GC settings are usually suitable for parallel programs
-    (i.e. those using ``par``, Strategies, or with multiple threads). However,
-    it is sometimes beneficial to enable the parallel GC for a single-threaded
-    sequential program too, especially if the program has a large amount of
-    heap data and GC is a significant fraction of runtime. To use the parallel
-    GC in a sequential program, enable the parallel runtime with a suitable
-    :rts-flag:`-N ⟨x⟩` option, and additionally it might be beneficial to
-    restrict parallel GC to the old generation with ``-qg1``.
+    (i.e. those using :base-ref:`par <GHC-Conc.html#v:par>`, Strategies, or with
+    multiple threads). However, it is sometimes beneficial to enable the
+    parallel GC for a single-threaded sequential program too, especially if the
+    program has a large amount of heap data and GC is a significant fraction of
+    runtime. To use the parallel GC in a sequential program, enable the parallel
+    runtime with a suitable :rts-flag:`-N ⟨x⟩` option, and additionally it might
+    be beneficial to restrict parallel GC to the old generation with ``-qg1``.
 
 .. rts-flag:: -qb ⟨gen⟩
 
-    :default: 1 for ``-A`` < 32M, 0 otherwise
+    :default: 1 for :rts-flag:`-A <-A ⟨size⟩>` < 32M, 0 otherwise
     :since: 6.12.1
 
     Use load-balancing in the parallel GC in generation ⟨gen⟩ and higher.
@@ -472,7 +467,7 @@ performance.
 
 .. rts-flag:: -qn ⟨x⟩
 
-    :default: the value of ``-N`` or the number of CPU cores,
+    :default: the value of :rts-flag:`-N <-N ⟨x⟩>` or the number of CPU cores,
               whichever is smaller.
     :since: 8.2.1
 
@@ -758,7 +753,7 @@ RTS options to produce runtime statistics
        data during a major GC, which is why the number of samples
        corresponds to the number of major GCs (and is usually relatively
        small). To get a better picture of the heap profile of your
-       program, use the ``-hT`` RTS option (:ref:`rts-profiling`).
+       program, use the :rts-flag:`-hT` RTS option (:ref:`rts-profiling`).
 
     -  The peak memory the RTS has allocated from the OS.
 
@@ -917,13 +912,14 @@ one profiling option that is available for ordinary non-profiled
 executables:
 
 .. rts-flag:: -hT
+              -h
 
     Generates a basic heap profile, in the file :file:`prog.hp`. To produce the
     heap profile graph, use :command:`hp2ps` (see :ref:`hp2ps`). The basic heap
     profile is broken down by data constructor, with other types of closures
     (functions, thunks, etc.) grouped into broad categories (e.g. ``FUN``,
     ``THUNK``). To get a more detailed profile, use the full profiling support
-    (:ref:`profiling`). Can be shortened to ``-h``.
+    (:ref:`profiling`). Can be shortened to :rts-flag:`-h`.
 
 .. rts-flag:: -L ⟨n⟩
 
diff --git a/docs/users_guide/safe_haskell.rst b/docs/users_guide/safe_haskell.rst
index cdd5228dd9..e1238a8e2c 100644
--- a/docs/users_guide/safe_haskell.rst
+++ b/docs/users_guide/safe_haskell.rst
@@ -375,7 +375,7 @@ Safe Imports
 Safe Haskell enables a small extension to the usual import syntax of
 Haskell, adding a ``safe`` keyword:
 
-::
+.. code-block:: none
 
     impdecl -> import [safe] [qualified] modid [as modid] [impspec]
 
diff --git a/docs/users_guide/sooner.rst b/docs/users_guide/sooner.rst
index 6851536cfb..d6bd2cc3c2 100644
--- a/docs/users_guide/sooner.rst
+++ b/docs/users_guide/sooner.rst
@@ -312,7 +312,7 @@ Use a bigger heap!
     to let GHC calculate a value based on the amount of live data.
 
 Compact your data:
-    The :compact-ref:`GHC.Compact <GHC-Compact.html>` module
+    The :ghc-compact-ref:`GHC.Compact <GHC-Compact.html>` module
     provides a way to make garbage collection more efficient for
     long-lived data structures. Compacting a data structure collects
     the objects together in memory, where they are treated as a single
diff --git a/docs/users_guide/using-concurrent.rst b/docs/users_guide/using-concurrent.rst
index f0236a3ced..270d0c1855 100644
--- a/docs/users_guide/using-concurrent.rst
+++ b/docs/users_guide/using-concurrent.rst
@@ -86,7 +86,7 @@ following compiler options affect parallelism:
     parallel program, because we can tell when a computation is already
     in progress.
 
-    The option ``-feager-blackholing`` causes each thunk to be
+    The option :ghc-flag:`-feager-blackholing` causes each thunk to be
     blackholed as soon as evaluation begins. The default is "lazy
     blackholing", whereby thunks are only marked as being under
     evaluation when a thread is paused for some reason. Lazy blackholing
@@ -96,7 +96,7 @@ following compiler options affect parallelism:
     turns out to be important for parallelism.
 
     We recommend compiling any code that is intended to be run in
-    parallel with the ``-feager-blackholing`` flag.
+    parallel with the :ghc-flag:`-feager-blackholing` flag.
 
 .. _parallel-options:
 
@@ -104,8 +104,9 @@ RTS options for SMP parallelism
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There are two ways to run a program on multiple processors: call
-``Control.Concurrent.setNumCapabilities`` from your program, or use the
-RTS ``-N`` options.
+:base-ref:`Control.Concurrent.setNumCapabilities
+<Control.Concurrent.html#v:setNumCapabilities>` from your program, or
+use the RTS :rts-flag:`-N ⟨x⟩` options.
 
 .. rts-flag:: -N ⟨x⟩
               -maxN ⟨x⟩
@@ -155,10 +156,9 @@ CPUs:
     Use the OS's affinity facilities to try to pin OS threads to CPU
     cores.
 
-    When this option is enabled, the OS threads for a capability *i* are
-    bound to the CPU core *i* using the API provided by the OS for
-    setting thread affinity. e.g. on Linux GHC uses
-    ``sched_setaffinity()``.
+    When this option is enabled, the OS threads for a capability :math:`i` are
+    bound to the CPU core :math:`i` using the API provided by the OS for setting
+    thread affinity. e.g. on Linux GHC uses ``sched_setaffinity()``.
 
     Depending on your workload and the other activity on the machine,
     this may or may not result in a performance improvement. We
@@ -174,7 +174,7 @@ CPUs:
 
     This option is probably only of use for concurrent programs that
     explicitly schedule threads onto CPUs with
-    ``Control.Concurrent.forkOn``.
+    :base-ref:`Control.Concurrent.forkOn <Control-Concurrent.html#v:forkOn>`.
 
 Hints for using SMP parallelism
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index ce2de5c3ac..48a9296b1a 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -186,7 +186,7 @@ of ``-W(no-)*``.
 
 .. ghc-flag:: -fdefer-out-of-scope-variables
 
-    Defer variable out of scope errors (errors about names without a leading underscore)
+    Defer variable out-of-scope errors (errors about names without a leading underscore)
     until runtime. This will turn variable-out-of-scope errors into warnings.
     Using a value that depends on a typed hole produces a runtime error,
     the same as :ghc-flag:`-fdefer-type-errors` (which implies this option).
@@ -194,6 +194,10 @@ of ``-W(no-)*``.
 
     Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
 
+.. ghc-flag:: -Wdeferred-out-of-scope-variables
+
+    Warn when a deferred out-of-scope variable is encountered.
+
 .. ghc-flag:: -Wpartial-type-signatures
 
     Determines whether the compiler reports holes in partial type
@@ -472,7 +476,7 @@ of ``-W(no-)*``.
     declaration.
 
     This option is on by default. As usual you can suppress it on a
-    per-module basis with :ghc-flag:`-Wno-redundant-constraints`.
+    per-module basis with :ghc-flag:`-Wno-redundant-constraints <-Wredundant-constraints>`.
     Occasionally you may specifically want a function to have a more
     constrained signature than necessary, perhaps to leave yourself
     wiggle-room for changing the implementation without changing the
@@ -791,7 +795,8 @@ of ``-W(no-)*``.
        f :: Eq a => a -> a
 
     This option is on by default. As usual you can suppress it on a
-    per-module basis with :ghc-flag:`-Wno-simplifiable-class-constraints`.
+    per-module basis with :ghc-flag:`-Wno-simplifiable-class-constraints
+    <-Wsimplifiable-class-constraints>`.
 
 .. ghc-flag:: -Wtabs
 
@@ -996,7 +1001,7 @@ of ``-W(no-)*``.
 
         type instance F _x _y = []
 
-    Unlike :ghc-flag:`-Wunused-matches`, :ghc-flag:`-Wunused-type-variables` is
+    Unlike :ghc-flag:`-Wunused-matches`, :ghc-flag:`-Wunused-type-patterns` is
     not implied by :ghc-flag:`-Wall`. The rationale for this decision is that
     unlike term-level pattern names, type names are often chosen expressly for
     documentation purposes, so using underscores in type names can make the
diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index 822199a436..dff9603b66 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -93,7 +93,7 @@ to the files ``Foo.hs`` and ``Bar.hs``.
     Note that command-line options are *order-dependent*, with arguments being
     evaluated from left-to-right. This can have seemingly strange effects in the
     presence of flag implication. For instance, consider
-    :ghc-flag:`-fno-specialise` and :ghc-flag:`-O1` (which implies
+    :ghc-flag:`-fno-specialise <-fspecialise>` and :ghc-flag:`-O1` (which implies
     :ghc-flag:`-fspecialise`). These two command lines mean very different
     things:
 
@@ -620,9 +620,10 @@ See also the ``--help``, ``--version``, ``--numeric-version``, and
 
 .. ghc-flag:: -fhide-source-paths
 
-    Starting with minimal verbosity (see :ghc-flag:`-v1`), GHC displays the
-    name, the source path and the target path of each compiled module. This flag
-    can be used to reduce GHC's output by hiding source paths and target paths.
+    Starting with minimal verbosity (``-v1``, see :ghc-flag:`-v`), GHC
+    displays the name, the source path and the target path of each compiled
+    module. This flag can be used to reduce GHC's output by hiding source paths
+    and target paths.
 
 The following flags control the way in which GHC displays types in error
 messages and in GHCi:
@@ -818,7 +819,9 @@ messages and in GHCi:
     place:
 
     - ``message``
+
       - ``header``
+
         - ``warning``
         - ``error``
         - ``fatal``
@@ -906,7 +909,6 @@ Some flags only make sense for particular target platforms.
     SSE2 is unconditionally used on x86-64 platforms.
 
 .. ghc-flag:: -msse4.2
-    :noindex:
 
     (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to
     implement some floating point and bit operations when using the
diff --git a/utils/mkUserGuidePart/Options/Interactive.hs b/utils/mkUserGuidePart/Options/Interactive.hs
index 6bc413909d..0137fc8c86 100644
--- a/utils/mkUserGuidePart/Options/Interactive.hs
+++ b/utils/mkUserGuidePart/Options/Interactive.hs
@@ -30,7 +30,7 @@ interactiveOptions =
            "Set the number of entries GHCi keeps for ``:history``." ++
            " See :ref:`ghci-debugger`."
          , flagType = DynamicFlag
-         , flagReverse = "(default is 50)"
+         , flagReverse = ""
          }
   , flag { flagName = "-fprint-evld-with-show"
          , flagDescription =
diff --git a/utils/mkUserGuidePart/Options/Verbosity.hs b/utils/mkUserGuidePart/Options/Verbosity.hs
index ba58e6210a..aa608769b7 100644
--- a/utils/mkUserGuidePart/Options/Verbosity.hs
+++ b/utils/mkUserGuidePart/Options/Verbosity.hs
@@ -8,7 +8,7 @@ verbosityOptions =
          , flagDescription = "verbose mode (equivalent to ``-v3``)"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-v⟨n⟩"
+  , flag { flagName = "-v ⟨n⟩"
          , flagDescription = "set verbosity level"
          , flagType = DynamicFlag
          , flagReverse = ""