users_guide: Convert mkUserGuidePart generation to a Sphinx extension

This removes all dependencies the users guide had on `mkUserGuidePart`.
The generation of the flag reference table and the various pieces of the
man page is now entirely contained within the Spinx extension
`flags.py`. You can see the man page generation on the orphan page
https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ghc.html

The extension works by collecting all of the meta-data attached to the
`ghc-flag` directives and then formatting and displaying it at
`flag-print` directives. There is a single printing directive that can
be customized with two options, what format to display (table, list, or
block of flags) and an optional category to limit the output to
(verbosity, warnings, codegen, etc.).

New display formats can be added by creating a function
`generate_flag_xxx` (where `xxx` is a description of the format) which
takes a list of flags and a category and returns a new `xxx`. Then just
add a reference in the dispatch table `handlers`. That display can now
be run by passing `:type: xxx` to the `flag-print` directive.

`flags.py` contains two maps of settings that can be adjusted. The first
is a canonical list of flag categories, and the second sets default
categories for files.

The only functionality that Sphinx could not replace was the
`what_glasgow_exts_does.gen.rst` file. `mkUserGuidePart` actually just
reads the list of flags from `compiler/main/DynFlags.hs` which Sphinx
cannot do. As the flag is deprecated, I added the list as a static file
which can be updated manually.

Additionally, this patch updates every single documented flag with the
data from `mkUserGuidePart` to generate the reference table.

Fixes #11654 and, incidentally, #12155.

Reviewers: austin, bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #11654, #12155

Differential Revision: https://phabricator.haskell.org/D3839

22 files changed, 3224 insertions, 149 deletions

diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py
index 9c75d5bf97..41b446a47d 100644
--- a/docs/users_guide/conf.py
+++ b/docs/users_guide/conf.py
@@ -13,7 +13,7 @@ sys.path.insert(0, os.path.abspath('.'))
 from ghc_config import extlinks, version
 import ghc_config
 
-extensions = ['sphinx.ext.extlinks', 'sphinx.ext.mathjax']
+extensions = ['sphinx.ext.extlinks', 'sphinx.ext.mathjax', 'flags']
 
 templates_path = ['.templates']
 source_suffix = '.rst'
@@ -32,7 +32,7 @@ pygments_style = 'tango'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['.build', "*.gen.rst"]
+exclude_patterns = ['.build']
 
 # -- Options for HTML output ---------------------------------------------
 
@@ -72,6 +72,7 @@ latex_elements = {
 \setsansfont{DejaVu Sans}
 \setromanfont{DejaVu Serif}
 \setmonofont{DejaVu Sans Mono}
+\setlength{\\tymin}{45pt}
 ''',
 }
 
@@ -193,16 +194,6 @@ def setup(app):
                         objname='GHCi command',
                         indextemplate='pair: %s; GHCi command')
 
-    app.add_object_type('ghc-flag', 'ghc-flag',
-                        objname='GHC command-line option',
-                        parse_node=parse_flag,
-                        indextemplate='pair: %s; GHC option',
-                        doc_field_types=[
-                            Field('since', label='Introduced in GHC version', names=['since']),
-                            Field('default', label='Default value', names=['default']),
-                            Field('static')
-                        ])
-
     # Haddock references
     app.add_role('th-ref', haddock_role('template-haskell'))
     app.add_role('base-ref', haddock_role('base'))
diff --git a/docs/users_guide/debug-info.rst b/docs/users_guide/debug-info.rst
index 6a34431c84..558da594a0 100644
--- a/docs/users_guide/debug-info.rst
+++ b/docs/users_guide/debug-info.rst
@@ -7,6 +7,11 @@ useable by most UNIX debugging tools.
 
 .. ghc-flag:: -g
               -g⟨n⟩
+    :shortdesc: Produce DWARF debug information in compiled object files.
+        ⟨n⟩ can be 0, 1, or 2, with higher numbers producing richer
+        output. If ⟨n⟩ is omitted level 2 is assumed.
+    :type: dynamic
+    :category: debugging
 
     :since: 7.10, numeric levels since 8.0
 
diff --git a/docs/users_guide/debugging.rst b/docs/users_guide/debugging.rst
index bc155884c8..fc18e559ca 100644
--- a/docs/users_guide/debugging.rst
+++ b/docs/users_guide/debugging.rst
@@ -28,6 +28,9 @@ Dumping out compiler intermediate structures
     :ghc-flag:`-ddump-to-file`. Some of the most useful ones are:
 
     .. ghc-flag:: -ddump-to-file
+        :shortdesc: Dump to files instead of stdout
+        :type: dynamic
+        :category:
 
         Causes the output from all of the flags listed below to be dumped
         to a file. The file name depends upon the output produced; for instance,
@@ -35,39 +38,66 @@ Dumping out compiler intermediate structures
         :file:`{module}.dump-simpl`.
 
     .. ghc-flag:: -ddump-parsed
+        :shortdesc: Dump parse tree
+        :type: dynamic
+        :category:
 
         Dump parser output
 
     .. ghc-flag:: -ddump-parsed-ast
+        :shortdesc: Dump parser output as a syntax tree
+        :type: dynamic
+        :category:
 
         Dump parser output as a syntax tree
 
     .. ghc-flag:: -ddump-rn
+        :shortdesc: Dump renamer output
+        :type: dynamic
+        :category:
 
         Dump renamer output
 
     .. ghc-flag:: -ddump-rn-ast
+        :shortdesc: Dump renamer output as a syntax tree
+        :type: dynamic
+        :category:
 
         Dump renamer output as a syntax tree
 
     .. ghc-flag:: -ddump-tc
+        :shortdesc: Dump typechecker output
+        :type: dynamic
+        :category:
 
         Dump typechecker output
 
     .. ghc-flag:: -ddump-tc-ast
+        :shortdesc: Dump typechecker output as a syntax tree
+        :type: dynamic
+        :category:
 
         Dump typechecker output as a syntax tree
 
     .. ghc-flag:: -ddump-splices
+        :shortdesc: Dump TH spliced expressions, and what they evaluate to
+        :type: dynamic
+        :category:
 
         Dump Template Haskell expressions that we splice in, and what
         Haskell code the expression evaluates to.
 
     .. ghc-flag:: -dth-dec-file=⟨file⟩
+        :shortdesc: Show evaluated TH declarations in a .th.hs file
+        :type: dynamic
+        :category:
 
         Dump expansions of all top-level Template Haskell splices into ⟨file⟩.
 
     .. ghc-flag:: -ddump-types
+        :shortdesc: Dump type signatures
+        :type: dynamic
+        :category:
 
         Dump a type signature for each value defined at the top level of
         the module. The list is sorted alphabetically. Using
@@ -76,165 +106,277 @@ Dumping out compiler intermediate structures
         compiler.
 
     .. ghc-flag:: -ddump-deriv
+        :shortdesc: Dump deriving output
+        :type: dynamic
+        :category:
 
         Dump derived instances
 
     .. ghc-flag:: -ddump-ds
+        :shortdesc: Dump desugarer output
+        :type: dynamic
+        :category:
 
         Dump desugarer output
 
     .. ghc-flag:: -ddump-spec
+        :shortdesc: Dump specialiser output
+        :type: dynamic
+        :category:
 
         Dump output of specialisation pass
 
     .. ghc-flag:: -ddump-rules
+        :shortdesc: Dump rewrite rules
+        :type: dynamic
+        :category:
 
         Dumps all rewrite rules specified in this module; see
         :ref:`controlling-rules`.
 
     .. ghc-flag:: -ddump-rule-firings
+        :shortdesc: Dump rule firing info
+        :type: dynamic
+        :category:
 
         Dumps the names of all rules that fired in this module
 
     .. ghc-flag:: -ddump-rule-rewrites
+        :shortdesc: Dump detailed rule firing info
+        :type: dynamic
+        :category:
 
         Dumps detailed information about all rules that fired in this
         module
 
     .. ghc-flag:: -ddump-vect
+        :shortdesc: Dump vectoriser input and output
+        :type: dynamic
+        :category:
 
         Dumps the output of the vectoriser.
 
     .. ghc-flag:: -ddump-simpl
+        :shortdesc: Dump final simplifier output
+        :type: dynamic
+        :category:
 
         Dump simplifier output (Core-to-Core passes)
 
     .. ghc-flag:: -ddump-inlinings
+        :shortdesc: Dump inlining info
+        :type: dynamic
+        :category:
 
-        Dumps inlining info from the simplifier. Note that if used in conjunction with
-        :ghc-flag:`-dverbose-core2core` the compiler will also dump the inlinings that
-        it considers but passes up, along with its rationale.
+        Dumps inlining info from the simplifier. Note that if used in
+        conjunction with :ghc-flag:`-dverbose-core2core` the compiler will
+        also dump the inlinings that it considers but passes up, along with
+        its rationale.
 
     .. ghc-flag:: -ddump-stranal
+        :shortdesc: Dump strictness analyser output
+        :type: dynamic
+        :category:
 
         Dump strictness analyser output
 
     .. ghc-flag:: -ddump-str-signatures
+        :shortdesc: Dump strictness signatures
+        :type: dynamic
+        :category:
 
         Dump strictness signatures
 
     .. ghc-flag:: -ddump-cse
+        :shortdesc: Dump CSE output
+        :type: dynamic
+        :category:
 
         Dump common subexpression elimination (CSE) pass output
 
     .. ghc-flag:: -ddump-worker-wrapper
+        :shortdesc: Dump worker-wrapper output
+        :type: dynamic
+        :category:
 
         Dump worker/wrapper split output
 
     .. ghc-flag:: -ddump-occur-anal
+        :shortdesc: Dump occurrence analysis output
+        :type: dynamic
+        :category:
 
         Dump "occurrence analysis" output
 
     .. ghc-flag:: -ddump-prep
+        :shortdesc: Dump prepared core
+        :type: dynamic
+        :category:
 
         Dump output of Core preparation pass
 
     .. ghc-flag:: -ddump-stg
+        :shortdesc: Dump final STG
+        :type: dynamic
+        :category:
 
         Dump output of STG-to-STG passes
 
     .. ghc-flag:: -ddump-cmm
+        :shortdesc: Dump the final C-- output
+        :type: dynamic
+        :category:
 
         Dump the result of the C-- pipeline processing
 
     .. ghc-flag:: -ddump-cmm-from-stg
+        :shortdesc: Dump STG-to-C-- output
+        :type: dynamic
+        :category:
 
         Dump the result of STG-to-C-- conversion
 
     .. ghc-flag:: -ddump-cmm-verbose
+        :shortdesc: Show output from each C-- pipeline pass
+        :type: dynamic
+        :category:
 
         Dump output from all C-- pipeline stages. In case of
         ``.cmm`` compilation this also dumps the result of
         file parsing.
 
     .. ghc-flag:: -ddump-opt-cmm
+        :shortdesc: Dump the results of C-- to C-- optimising passes
+        :type: dynamic
+        :category:
 
         Dump the results of C-- to C-- optimising passes.
 
     .. ghc-flag:: -ddump-asm
+        :shortdesc: Dump assembly
+        :type: dynamic
+        :category:
 
         Dump assembly language produced by the :ref:`native code
         generator <native-code-gen>`
 
     .. ghc-flag:: -ddump-llvm
+        :shortdesc: Dump LLVM intermediate code.
+            Implies :ghc-flag:`-fllvm`.
+        :type: dynamic
+        :category:
 
         :implies: :ghc-flag:`-fllvm`
 
         LLVM code from the :ref:`LLVM code generator <llvm-code-gen>`
 
     .. ghc-flag:: -ddump-bcos
+        :shortdesc: Dump interpreter byte code
+        :type: dynamic
+        :category:
 
         Dump byte-code compiler output
 
     .. ghc-flag:: -ddump-foreign
+        :shortdesc: Dump ``foreign export`` stubs
+        :type: dynamic
+        :category:
 
         dump foreign export stubs
 
     .. ghc-flag:: -ddump-json
+        :shortdesc: Dump error messages as JSON documents
+        :type: dynamic
+        :category:
 
          Dump error messages as JSON documents. This is intended to be consumed
          by external tooling. A good way to use it is in conjunction with
          :ghc-flag:`-ddump-to-file`.
 
 .. ghc-flag:: -ddump-simpl-iterations
+    :shortdesc: Dump output from each simplifier iteration
+    :type: dynamic
+    :category:
 
     Show the output of each *iteration* of the simplifier (each run of
     the simplifier has a maximum number of iterations, normally 4). This
     outputs even more information than ``-ddump-simpl-phases``.
 
 .. ghc-flag:: -ddump-simpl-stats
+    :shortdesc: Dump simplifier stats
+    :type: dynamic
+    :category:
 
     Dump statistics about how many of each kind of transformation too
     place. If you add ``-dppr-debug`` you get more detailed information.
 
 .. ghc-flag:: -ddump-if-trace
+    :shortdesc: Trace interface files
+    :type: dynamic
+    :category:
 
     Make the interface loader be *real* chatty about what it is up to.
 
 .. ghc-flag:: -ddump-tc-trace
+    :shortdesc: Trace typechecker
+    :type: dynamic
+    :category:
 
     Make the type checker be *real* chatty about what it is up to.
 
 .. ghc-flag:: -ddump-vt-trace
+    :shortdesc: Trace vectoriser
+    :type: dynamic
+    :category:
 
     Make the vectoriser be *real* chatty about what it is up to.
 
 .. ghc-flag:: -ddump-rn-trace
+    :shortdesc: Trace renamer
+    :type: dynamic
+    :category:
 
     Make the renamer be *real* chatty about what it is up to.
 
 .. ghc-flag:: -ddump-ec-trace
+    :shortdesc: Trace exhaustiveness checker
+    :type: dynamic
+    :category:
 
     Make the pattern match exhaustiveness checker be *real* chatty about
     what it is up to.
 
 .. ghc-flag:: -ddump-rn-stats
+    :shortdesc: Renamer stats
+    :type: dynamic
+    :category:
 
     Print out summary of what kind of information the renamer had to
     bring in.
 
 .. ghc-flag:: -dverbose-core2core
-              -dverbose-stg2stg
+    :shortdesc: Show output from each core-to-core pass
+    :type: dynamic
+    :category:
 
-    Show the output of the intermediate Core-to-Core and STG-to-STG
-    passes, respectively. (*lots* of output!) So: when we're really
-    desperate:
+    Show the output of the intermediate Core-to-Core pass. (*lots* of output!)
+    So: when we're really desperate:
 
     .. code-block:: sh
 
         % ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs
 
+.. ghc-flag:: -dverbose-stg2stg
+    :shortdesc: Show output from each STG-to-STG pass
+    :type: dynamic
+    :category:
+
+    Show the output of the intermediate STG-to-STG pass. (*lots* of output!)
+
 .. ghc-flag:: -dshow-passes
+    :shortdesc: Print out each pass name as it happens
+    :type: dynamic
+    :category:
 
     Print out each pass name, its runtime and heap allocations as it happens.
     Note that this may come at a slight performance cost as the compiler will
@@ -247,15 +389,25 @@ Dumping out compiler intermediate structures
     runtime statistics.
 
 .. ghc-flag:: -ddump-core-stats
+    :shortdesc: Print a one-line summary of the size of the Core program at the
+        end of the optimisation pipeline
+    :type: dynamic
+    :category:
 
     Print a one-line summary of the size of the Core program at the end
     of the optimisation pipeline.
 
 .. ghc-flag:: -dfaststring-stats
+    :shortdesc: Show statistics for fast string usage when finished
+    :type: dynamic
+    :category:
 
     Show statistics on the usage of fast strings by the compiler.
 
 .. ghc-flag:: -dppr-debug
+    :shortdesc: Turn on debug printing (more verbose)
+    :type: dynamic
+    :category:
 
     Debugging output is in one of several "styles." Take the printing of
     types, for example. In the "user" style (the default), the
@@ -277,23 +429,35 @@ Formatting dumps
    single: formatting dumps
 
 .. ghc-flag:: -dppr-user-length
+    :shortdesc: Set the depth for printing expressions in error msgs
+    :type: dynamic
+    :category:
 
     In error messages, expressions are printed to a certain "depth",
     with subexpressions beyond the depth replaced by ellipses. This flag
     sets the depth. Its default value is 5.
 
 .. ghc-flag:: -dppr-cols=⟨n⟩
+    :shortdesc: Set the width of debugging output. For example ``-dppr-cols200``
+    :type: dynamic
+    :category:
 
     Set the width of debugging output. Use this if your code is wrapping
     too much. For example: ``-dppr-cols=200``.
 
 .. ghc-flag:: -dppr-case-as-let
+    :shortdesc: Print single alternative case expressions as strict lets.
+    :type: dynamic
+    :category:
 
     Print single alternative case expressions as though they were strict
     let expressions. This is helpful when your code does a lot of
     unboxing.
 
 .. ghc-flag:: -dno-debug-output
+    :shortdesc: Suppress unsolicited debugging output
+    :type: dynamic
+    :category:
 
     Suppress any unsolicited debugging output. When GHC has been built
     with the ``DEBUG`` option it occasionally emits debug output of
@@ -314,16 +478,27 @@ are doing, not all of it will be useful. Use these flags to suppress the
 parts that you are not interested in.
 
 .. ghc-flag:: -dsuppress-all
+    :shortdesc: In core dumps, suppress everything (except for uniques) that is
+        suppressible.
+    :type: dynamic
+    :category:
 
     Suppress everything that can be suppressed, except for unique ids as
     this often makes the printout ambiguous. If you just want to see the
     overall structure of the code, then start here.
 
 .. ghc-flag:: -dsuppress-ticks
+    :shortdesc: Suppress "ticks" in the pretty-printer output.
+    :type: dynamic
+    :category:
 
     Suppress "ticks" in the pretty-printer output.
 
 .. ghc-flag:: -dsuppress-uniques
+    :shortdesc: Suppress the printing of uniques in debug output (easier to use
+        ``diff``)
+    :type: dynamic
+    :category:
 
     Suppress the printing of uniques. This may make the printout
     ambiguous (e.g. unclear where an occurrence of 'x' is bound), but it
@@ -333,6 +508,10 @@ parts that you are not interested in.
     :ghc-flag:`-dsuppress-uniques`
 
 .. ghc-flag:: -dsuppress-idinfo
+    :shortdesc: Suppress extended information about identifiers where they
+        are bound
+    :type: dynamic
+    :category:
 
     Suppress extended information about identifiers where they are
     bound. This includes strictness information and inliner templates.
@@ -340,24 +519,41 @@ parts that you are not interested in.
     the lack of inliner templates
 
 .. ghc-flag:: -dsuppress-unfoldings
+    :shortdesc: Suppress the printing of the stable unfolding of a variable at
+        its binding site
+    :type: dynamic
+    :category:
 
     Suppress the printing of the stable unfolding of a variable at its
     binding site.
 
 .. ghc-flag:: -dsuppress-module-prefixes
+    :shortdesc: Suppress the printing of module qualification prefixes
+    :type: dynamic
+    :category:
 
     Suppress the printing of module qualification prefixes. This is the
     ``Data.List`` in ``Data.List.length``.
 
 .. ghc-flag:: -dsuppress-type-signatures
+    :shortdesc: Suppress type signatures
+    :type: dynamic
+    :category:
 
     Suppress the printing of type signatures.
 
 .. ghc-flag:: -dsuppress-type-applications
+    :shortdesc: Suppress type applications
+    :type: dynamic
+    :category:
 
     Suppress the printing of type applications.
 
 .. ghc-flag:: -dsuppress-coercions
+    :shortdesc: Suppress the printing of coercions in Core dumps to make them
+        shorter
+    :type: dynamic
+    :category:
 
     Suppress the printing of type coercions.
 
@@ -371,25 +567,41 @@ Checking for consistency
    single: lint
 
 .. ghc-flag:: -dcore-lint
+    :shortdesc: Turn on internal sanity checking
+    :type: dynamic
+    :category:
 
     Turn on heavyweight intra-pass sanity-checking within GHC, at Core
     level. (It checks GHC's sanity, not yours.)
 
 .. ghc-flag:: -dstg-lint
+    :shortdesc: STG pass sanity checking
+    :type: dynamic
+    :category:
 
     Ditto for STG level. (note: currently doesn't work).
 
 .. ghc-flag:: -dcmm-lint
+    :shortdesc: C-- pass sanity checking
+    :type: dynamic
+    :category:
 
     Ditto for C-- level.
 
 .. ghc-flag:: -fllvm-fill-undef-with-garbage
+    :shortdesc: Intruct LLVM to fill dead STG registers with garbage
+    :type: dynamic
+    :category:
 
     Instructs the LLVM code generator to fill dead STG registers with garbage
     instead of ``undef`` in calls. This makes it easier to catch subtle
     code generator and runtime system bugs (e.g. see :ghc-ticket:`11487`).
 
 .. ghc-flag:: -fcatch-bottoms
+    :shortdesc: Insert ``error`` expressions after bottoming expressions; useful
+        when debugging the compiler.
+    :type: dynamic
+    :category:
 
     Instructs the simplifier to emit ``error`` expressions in the continuation
     of empty case analyses (which should bottom and consequently not return).
@@ -405,10 +617,16 @@ Checking for determinism
    single: deterministic builds
 
 .. ghc-flag:: -dinitial-unique=⟨s⟩
+    :shortdesc: Start ``UniqSupply`` allocation from ⟨s⟩.
+    :type: dynamic
+    :category:
 
     Start ``UniqSupply`` allocation from ⟨s⟩.
 
 .. ghc-flag:: -dunique-increment=⟨i⟩
+    :shortdesc: Set the increment for the generated ``Unique``'s to ⟨i⟩.
+    :type: dynamic
+    :category:
 
     Set the increment for the generated ``Unique``'s to ⟨i⟩.
 
diff --git a/docs/users_guide/editing-guide.rst b/docs/users_guide/editing-guide.rst
index b57a5d12b9..ad49c8938c 100644
--- a/docs/users_guide/editing-guide.rst
+++ b/docs/users_guide/editing-guide.rst
@@ -347,11 +347,29 @@ Will be rendered as,
 
        Sets the context switch interval to ⟨s⟩ seconds.
 
-and will have an associated index entry generated automatically. Note that, as
-in Style Conventions below, we use ``⟨⟩`` instead of less-than/greater-than
-signs. To reference a ``ghc-flag`` or ``rts-flag``, you must match the
-definition exactly, including the arguments. A quick way to find the exact
-names and special characters is,
+and will have an associated index entry generated automatically.
+
+The ``ghc-flag`` directive requires a few extra parameters to be passed.
+This extra information is used to generate the :ref:`flag-reference` and the
+man page. A ``ghc-flag`` directive looks like this,
+
+.. code-block:: rest
+
+    .. ghc-flag:: -fasm
+        :shortdesc: Use the native code generator
+        :type: dynamic
+        :reverse: -fllvm
+        :category: codegen
+
+        Regular description...
+
+When rendered, the extra parameters will be hidden, and the data stored for
+later use. For more details, see the Sphinx extension ``flags.py``.
+
+Note that, as in Style Conventions below, we use ``⟨⟩`` instead of
+less-than/greater-than signs. To reference a ``ghc-flag`` or ``rts-flag``, you
+must match the definition exactly, including the arguments. A quick way to find
+the exact names and special characters is,
 
 .. code-block:: sh
     
diff --git a/docs/users_guide/extending_ghc.rst b/docs/users_guide/extending_ghc.rst
index 4a3e02e83e..e9543ebce5 100644
--- a/docs/users_guide/extending_ghc.rst
+++ b/docs/users_guide/extending_ghc.rst
@@ -196,13 +196,22 @@ module in a registered package that exports a plugin. Arguments can be given to
 plugins with the :ghc-flag:`-fplugin-opt=⟨module⟩:⟨args⟩` option.
 
 .. ghc-flag:: -fplugin=⟨module⟩
+    :shortdesc: Load a plugin exported by a given module
+    :type: dynamic
+    :category: plugins
 
     Load the plugin in the given module. The module must be a member of a
     package registered in GHC's package database.
 
 .. ghc-flag:: -fplugin-opt=⟨module⟩:⟨args⟩
+    :shortdesc: Give arguments to a plugin module; module must be specified with
+        :ghc-flag:`-fplugin=⟨module⟩`
+    :type: dynamic
+    :category: plugins
+
+    Give arguments to a plugin module; module must be specified with
+    :ghc-flag:`-fplugin=⟨module⟩`.
 
-    Pass arguments ⟨args⟩ to the given plugin.
 
 As an example, in order to load the plugin exported by ``Foo.Plugin`` in
 the package ``foo-ghc-plugin``, and give it the parameter "baz", we
@@ -227,6 +236,9 @@ the same; however, there are a few command line options which
 control specifically plugin packages:
 
 .. ghc-flag:: -plugin-package ⟨pkg⟩
+    :shortdesc: Expose ⟨pkg⟩ for plugins
+    :type: dynamic
+    :category: plugins
 
     This option causes the installed package ⟨pkg⟩ to be exposed for plugins,
     such as :ghc-flag:`-fplugin=⟨module⟩`. The package ⟨pkg⟩ can be specified
@@ -241,6 +253,9 @@ control specifically plugin packages:
     to be linked into the resulting executable or shared object.
 
 .. ghc-flag:: -plugin-package-id ⟨pkg-id⟩
+    :shortdesc: Expose ⟨pkg-id⟩ for plugins
+    :type: dynamic
+    :category: plugins
 
     Exposes a package in the plugin namespace like :ghc-flag:`-plugin-package
     ⟨pkg⟩`, but the package is named by its installed package ID rather than by
@@ -251,6 +266,9 @@ control specifically plugin packages:
     described in :ref:`package-thinning-and-renaming`.
 
 .. ghc-flag:: -hide-all-plugin-packages
+    :shortdesc: Hide all packages for plugins by default
+    :type: dynamic
+    :category: plugins
 
     By default, all exposed packages in the normal, source import namespace are
     also available for plugins.  This causes those packages to be hidden by
diff --git a/docs/users_guide/ffi-chap.rst b/docs/users_guide/ffi-chap.rst
index 320a3a6e70..6d41fa15d1 100644
--- a/docs/users_guide/ffi-chap.rst
+++ b/docs/users_guide/ffi-chap.rst
@@ -8,6 +8,12 @@ Foreign function interface (FFI)
    single: interfacing with native code
 
 .. ghc-flag:: -XForeignFunctionInterface
+    :shortdesc: Enable :ref:`foreign function interface <ffi>`.
+    :type: dynamic
+    :reverse: -XNoForeignFunctionInterface
+    :category: language
+
+    :since: 6.8.1
 
     Allow use of the Haskell foreign function interface.
 
@@ -118,6 +124,14 @@ come with GHC. For more details see the
 Interruptible foreign calls
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. ghc-flag:: -XInterruptibleFFI
+    :shortdesc: Enable interruptible FFI.
+    :type: dynamic
+    :reverse: -XNoInterruptibleFFI
+    :category: language
+
+    :since: 7.2.1
+
 This concerns the interaction of foreign calls with
 ``Control.Concurrent.throwTo``. Normally when the target of a
 ``throwTo`` is involved in a foreign call, the exception is not raised
@@ -167,6 +181,14 @@ it is not typically necessary to handle ``ERROR_OPERATION_ABORTED``.
 The CAPI calling convention
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. ghc-flag:: -XCApiFFI
+    :shortdesc: Enable :ref:`the CAPI calling convention <ffi-capi>`.
+    :type: dynamic
+    :reverse: -XNoCAPIFFI
+    :category: language
+
+    :since: 7.10.1
+
 The ``CApiFFI`` extension allows a calling convention of ``capi`` to be
 used in foreign declarations, e.g. ::
 
diff --git a/docs/users_guide/flags.py b/docs/users_guide/flags.py
new file mode 100644
index 0000000000..06223b599c
--- /dev/null
+++ b/docs/users_guide/flags.py
@@ -0,0 +1,400 @@
+# GHC User's Guide flag extension
+#
+# This file defines a Sphinx extension to document GHC flags.
+# It introduces a directive:
+#
+# .. ghc-flag::
+#     :shortdesc: A short description (REQUIRED)
+#     :type: dynamic, mode, dynamix/ ``:set`` (REQUIRED)
+#     :reverse: The reverse of the flag
+#     :category: The category to list the flag under (default: 'misc')
+#     :noindex: Do not list the flag anywhere (good for duplicates)
+#
+# That can be referenced using:
+#
+# :ghc-flag:`flag`
+#
+# As well as a directive to generate a display of flags:
+#
+# .. flag-print::
+#     :type: table/list/summary (REQUIRED)
+#     :category: Limit the output to a single category
+#
+# The two main functions in this extension are Flag.after_content() which adds
+# flag metadata into the environment, and flagprint.generate_output(), which
+# reads the metadata back out and formats it as desired.
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from sphinx import addnodes
+from sphinx.domains.std import GenericObject
+
+### Settings
+
+# Categories to titles as well as a canonical list of categories
+categories = {
+    '': 'All flags',
+    'codegen': 'Code generation',
+    'coverage': 'Program coverage',
+    'cpp': 'C pre-processor',
+    'debugging': 'Debugging the compiler',
+    'interactive': 'Interactive mode',
+    'interface-files': 'Interface files',
+    'keep-intermediates': 'Keeping intermediate files',
+    'language': 'Language options',
+    'linking': 'Linking options',
+    'misc': 'Miscellaneous options',
+    'modes': 'Modes of operation',
+    'optimization': 'Individual optimizations',
+    'optimization-levels': 'Optimization levels',
+    'packages': 'Package options',
+    'phases': 'Phases of compilation',
+    'phase-programs': 'Overriding external programs',
+    'phase-options': 'Phase-specific options',
+    'platform-options': 'Platform-specific options',
+    'plugins': 'Compiler plugins',
+    'profiling': 'Profiling',
+    'recompilation': 'Recompilation checking',
+    'redirect-output': 'Redirecting output',
+    'search-path': 'Finding imports',
+    'temp-files': 'Temporary files',
+    'verbosity': 'Verbosity options',
+    'warnings': 'Warnings',
+}
+
+# Map file names to default flag categories
+file_defaults = {
+    'debugging': 'debugging',
+    'ghci': 'interactive',
+    'glasgow_exts': 'language',
+    'packages': 'packages',
+    'profiling': 'profiling',
+    'safe_haskell': 'language',
+    'separate_compilation': 'redirect-output',
+    'using-warnings': 'warnings',
+    'using-optimisation': 'optimization'
+}
+
+
+### Flag declaration
+
+# This class inherits from Sphinx's internal GenericObject, which drives
+# the add_object_type() utility function. We want to keep that tooling,
+# but need to override some of the functionality.
+class Flag(GenericObject):
+
+    # The options that can be passed to our directive and their validators
+    option_spec = {
+        'shortdesc': directives.unchanged_required,
+        'type': directives.unchanged_required,
+        'reverse': directives.unchanged,
+        'category': directives.unchanged,
+        'noindex': directives.flag
+    }
+
+    # The index directive generated unless :noindex: is specified
+    indextemplate = 'pair: %s; GHC option'
+
+
+    # Generate docutils node from directive arguments
+    @staticmethod
+    def _parse_flag(env, sig, signode):
+
+        # Break flag into name and args
+        import re
+        parts = re.split(r'( |=|\[)', sig, 1)
+        flag = parts[0]
+        # Bold printed name
+        signode += addnodes.desc_name(flag, flag)
+        if len(parts) > 1:
+            args = ''.join(parts[1:])
+            # Smaller arguments
+            signode += addnodes.desc_addname(args, args)
+
+        # Reference name left unchanged
+        return sig
+
+    # Used in the GenericObject class
+    parse_node = _parse_flag
+
+    # Override the (empty) function that is called at the end of run()
+    # to append metadata about this flag into the environment
+    def after_content(self):
+
+        # If noindex, then do not include this flag in the table
+        if 'noindex' in self.options:
+            return
+
+        # Set the flag category (default: misc)
+        self.category = 'misc'
+        if not 'category' in self.options or self.options['category'] == '':
+            if self.env.docname in file_defaults:
+                self.category = file_defaults[self.env.docname]
+        else:
+            self.category = self.options['category']
+
+        # Manually create references
+        name_string = ", ".join([':ghc-flag:`'+n+'`' for n in self.names])
+        reverse_string = ''
+        if 'reverse' in self.options and self.options['reverse'] != '':
+            reverse_string = ':ghc-flag:`' + self.options['reverse'] + '`'
+
+        # Create nodes for each cell of the table
+        name_node = nodes.paragraph()
+        shortdesc_node = nodes.paragraph()
+        type_node = nodes.paragraph()
+        reverse_node = nodes.paragraph()
+
+
+        # Nodes expect an internal ViewList type for the content,
+        # we are just spoofing it here
+        from docutils.statemachine import ViewList
+        name_vl = ViewList(initlist=[name_string],
+                                source=self.env.docname, parent=[])
+        shortdesc_vl = ViewList(initlist=[self.options['shortdesc']],
+                                source=self.env.docname, parent=[])
+        type_vl = ViewList(initlist=[self.options['type']],
+                                source=self.env.docname, parent=[])
+        reverse_vl = ViewList(initlist=[reverse_string],
+                                source=self.env.docname, parent=[])
+
+
+        # Parse the content into the nodes
+        self.state.nested_parse(name_vl, 0, name_node)
+        self.state.nested_parse(shortdesc_vl, 0, shortdesc_node)
+        self.state.nested_parse(type_vl, 0, type_node)
+        self.state.nested_parse(reverse_vl, 0, reverse_node)
+
+
+        # The parsing adds extra layers that we don't need
+        name_node = name_node[0]
+        shortdesc_node = shortdesc_node[0]
+
+        # Append this flag to the environment, initializing if necessary
+        if not hasattr(self.env, 'all_flags'):
+            self.env.all_flags = []
+        self.env.all_flags.append({
+            'names': self.names,
+            'docname': self.env.docname,
+            'category': self.category,
+            'cells': [name_node, shortdesc_node, type_node, reverse_node],
+        })
+
+
+### Flag Printing
+
+# Taken from Docutils source inside the ListTable class. We must bypass
+# using the class itself, but this function comes in handy.
+def build_table_from_list(table_data, col_widths):
+    table = nodes.table()
+    tgroup = nodes.tgroup(cols=len(col_widths))
+    table += tgroup
+    for col_width in col_widths:
+        colspec = nodes.colspec(colwidth=col_width)
+        tgroup += colspec
+    rows = []
+    for row in table_data:
+        row_node = nodes.row()
+        for cell in row:
+            entry = nodes.entry()
+            entry += cell
+            row_node += entry
+        rows.append(row_node)
+    thead = nodes.thead()
+    thead.extend(rows[:1])
+    tgroup += thead
+    tbody = nodes.tbody()
+    tbody.extend(rows[1:])
+    tgroup += tbody
+    return table
+
+
+# Generate a table of flags
+def generate_flag_table(flags, category):
+
+    # Create column headers for table
+    header = []
+    for h in ["Flag", "Description", "Type", "Reverse"]:
+        inline = nodes.inline(text=h)
+        header.append(inline)
+
+    flags_list = [header]
+
+    for flag_info in flags:
+
+        flags_list.append(flag_info['cells'])
+
+    # The column width hints only apply to html,
+    # latex widths are set in file (see flags.rst)
+    table = build_table_from_list(flags_list, [28, 34, 10, 28])
+
+    # Flag tables have lots of content, so we need to set 'longtable'
+    # to allow for pagebreaks. (latex specific)
+    table['classes'].append('longtable')
+
+    return table
+
+
+# Generate a list of flags and their short descriptions
+def generate_flag_list(flags, category):
+
+    list_node = nodes.definition_list()
+
+    for flag_info in flags:
+
+        dl_item_node = nodes.definition_list_item()
+        term_node = nodes.term()
+        # The man writer is picky, so we have to remove the outer
+        # paragraph node to get just the flag name
+        term_node += flag_info['cells'][0][0]
+        dl_item_node += term_node
+        def_node = nodes.definition()
+        def_node += flag_info['cells'][1]
+        dl_item_node += def_node
+
+        list_node += dl_item_node
+
+    return list_node
+
+
+# Generate a block of flag names under a category
+def generate_flag_summary(flags, category):
+
+    summary_node = nodes.definition_list_item()
+    term_node = nodes.term(text=categories[category])
+    summary_node += term_node
+    block = nodes.definition()
+    summary_node += block
+
+    # Fill block with flags
+    for flag_info in flags:
+
+        for name in flag_info['names']:
+            block += nodes.literal(text=name)
+            block += nodes.inline(text=' ')
+
+    block += nodes.inline(text='\n')
+
+    return summary_node
+
+# Output dispatch table
+handlers = {
+    'table': generate_flag_table,
+    'list': generate_flag_list,
+    'summary': generate_flag_summary
+}
+
+
+# Generic node for printing flag output
+class flagprint(nodes.General, nodes.Element):
+
+    def __init__(self, output_type='', category='', **kwargs):
+
+        nodes.Element.__init__(self, rawsource='', **kwargs)
+
+        # Verify options
+        if category not in categories:
+            error = "flagprint: Unknown category: " + category
+            raise ValueError(error)
+        if output_type not in handlers:
+            error = "flagprint: Unknown output type: " + output_type
+            raise ValueError(error)
+
+        # Store the options
+        self.options = {
+            'type': output_type,
+            'category': category
+        }
+
+
+    # The man writer has a copy issue, so we explicitly override it here
+    def copy(self):
+        newnode = flagprint(output_type=self.options['type'],
+                category=self.options['category'], **self.attributes)
+        newnode.source = self.source
+        newnode.line = self.line
+        return newnode
+
+
+    def generate_output(self, app, fromdocname):
+        env = app.builder.env
+
+        # Filter flags before passing to handlers
+        flags = []
+
+        for flag_info in sorted(env.all_flags,
+                key=lambda fi: fi['names'][0].lower()):
+
+            if not (self.options['category'] == '' or
+                    self.options['category'] == flag_info['category']):
+                continue
+
+            # Resolve all references as if they were originated from this node.
+            # This fixes the relative uri.
+            for cell in flag_info['cells']:
+                for ref in cell.traverse(addnodes.pending_xref):
+                    ref['refdoc'] = fromdocname
+                env.resolve_references(cell, flag_info['docname'], app.builder)
+
+            flags.append(flag_info)
+
+        handler = handlers[self.options['type']]
+        self.replace_self(handler(flags, self.options['category']))
+
+
+# A directive to create flagprint nodes
+class FlagPrintDirective(Directive):
+
+    option_spec = {
+        'type': directives.unchanged_required,
+        'category': directives.unchanged
+    }
+
+    def run(self):
+
+        # Process options
+        category = ''
+        if 'category' in self.options:
+            category = self.options['category']
+
+        # Create a flagprint node
+        node = flagprint(output_type=self.options['type'], category=category)
+        return [node]
+
+
+### Additional processing
+
+# Convert every flagprint node into its output format
+def process_print_nodes(app, doctree, fromdocname):
+
+    for node in doctree.traverse(flagprint):
+        node.generate_output(app, fromdocname)
+
+
+# To avoid creating duplicates in the serialized environment, clear all
+# flags originating from a file before re-reading it.
+def purge_flags(app, env, docname):
+
+    if not hasattr(env, 'all_flags'):
+        return
+
+    env.all_flags = [flag for flag in env.all_flags
+                     if flag['docname'] != docname]
+
+### Initialization
+
+def setup(app):
+
+    # Add ghc-flag directive, and override the class with our own
+    app.add_object_type('ghc-flag', 'ghc-flag')
+    app.add_directive_to_domain('std', 'ghc-flag', Flag)
+
+    # Add new node and directive
+    app.add_node(flagprint)
+    app.add_directive('flag-print', FlagPrintDirective)
+
+    # Add our generator and cleanup functions as callbacks
+    app.connect('doctree-resolved', process_print_nodes)
+    app.connect('env-purge-doc', purge_flags)
+
+    return {'version': '1.0'}
diff --git a/docs/users_guide/flags.rst b/docs/users_guide/flags.rst
index 4064f46bdf..a3ec0f6f9e 100644
--- a/docs/users_guide/flags.rst
+++ b/docs/users_guide/flags.rst
@@ -12,63 +12,135 @@ Verbosity options
 
 More details in :ref:`options-help`
 
-.. include:: flags-verbosity.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.33\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.26\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: verbosity
 
 Alternative modes of operation
 ------------------------------
 
 More details in :ref:`modes`
 
-.. include:: flags-modes.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: modes
 
 Which phases to run
 -------------------
 
 More details in :ref:`options-order`
 
-.. include:: flags-phases.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: phases
 
 Redirecting output
 ------------------
 
 More details in :ref:`options-output`
 
-.. include:: flags-redirecting-output.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: redirect-output
 
 Keeping intermediate files
 --------------------------
 
 More details in :ref:`keeping-intermediates`
 
-.. include:: flags-keeping-intermediates.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: keep-intermediates
 
 Temporary files
 ---------------
 
 More details in :ref:`temp-files`
 
-.. include:: flags-temporary-files.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: temp-files
 
 Finding imports
 ---------------
 
 More details in :ref:`search-path`
 
-.. include:: flags-finding-imports.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: search-path
 
 Interface file options
 ----------------------
 
 More details in :ref:`hi-options`
 
-.. include:: flags-interface-files.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: interface-files
 
 Recompilation checking
 ----------------------
 
 More details in :ref:`recomp`
 
-.. include:: flags-recompilation-checking.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: recompilation
 
 .. _interactive-mode-options:
 
@@ -77,14 +149,30 @@ Interactive-mode options
 
 More details in :ref:`ghci-dot-files`
 
-.. include:: flags-interactive.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: interactive
 
 Packages
 --------
 
 More details in :ref:`packages`
 
-.. include:: flags-packages.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: packages
 
 Language options
 ----------------
@@ -94,14 +182,30 @@ Language options can be enabled either by a command-line option
 See :ref:`options-language`. Some options are enabled using ``-f*``
 flags.
 
-.. include:: flags-language.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.36\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.25\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: language
 
 Warnings
 --------
 
 More details in :ref:`options-sanity`
 
-.. include:: flags-warnings.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: warnings
 
 Optimisation levels
 -------------------
@@ -111,7 +215,15 @@ These options are described in more detail in :ref:`options-optimise`.
 See :ref:`options-f-compact` for a list of optimisations enabled on
 level 1 and level 2.
 
-.. include:: flags-optimization-levels.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: optimization-levels
 
 .. _options-f-compact:
 
@@ -123,90 +235,175 @@ flag is implied by ``-O`` then it is also implied by ``-O2`` (unless
 flag description explicitly says otherwise). If a flag is implied by
 ``-O0`` only then the flag is not implied by ``-O`` and ``-O2``.
 
-.. include:: flags-optimization.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: optimization
 
 Profiling options
 -----------------
 
 More details in :ref:`profiling`
 
-.. include:: flags-profiling.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: profiling
 
 Program coverage options
 ------------------------
 
 More details in :ref:`hpc`
 
-.. include:: flags-program-coverage.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: coverage
 
 C pre-processor options
 -----------------------
 
 More details in :ref:`c-pre-processor`
 
-.. include:: flags-cpp.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: cpp
 
 Code generation options
 -----------------------
 
 More details in :ref:`options-codegen`
 
-.. include:: flags-codegen.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: codegen
 
 Linking options
 ---------------
 
 More details in :ref:`options-linker`
 
-.. include:: flags-linking.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.35\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.44\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.10\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: linking
 
 Plugin options
 --------------
 
 More details in :ref:`compiler-plugins`
 
-.. include:: flags-plugin.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: plugins
 
 Replacing phases
 ----------------
 
 More details in :ref:`replacing-phases`
 
-.. include:: flags-phase-programs.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
 
-.. index::
-   single: -pgmL
-   single: -pgmP
-   single: -pgmc
-   single: -pgmlo
-   single: -pgmlc
-   single: -pgma
-   single: -pgml
-   single: -pgmdll
-   single: -pgmF
+.. flag-print::
+    :type: table
+    :category: phase-programs
 
 Forcing options to particular phases
 ------------------------------------
 
 More details in :ref:`forcing-options-through`
 
-.. include:: flags-phase-specific.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: phase-options
 
 Platform-specific options
 -------------------------
 
 More details in :ref:`options-platform`
 
-.. include:: flags-platform-specific.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.31\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.29\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: platform-options
 
 Compiler debugging options
 --------------------------
 
 More details in :ref:`options-debugging`
 
-.. include:: flags-compiler-debugging.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.35\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.44\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.10\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: debugging
 
 Miscellaneous compiler options
 ------------------------------
 
-.. include:: flags-misc.gen.rst
+.. tabularcolumns::
+    | p{\dimexpr 0.35\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.44\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.11\textwidth-2\tabcolsep} |
+      p{\dimexpr 0.10\textwidth-2\tabcolsep} |
+
+.. flag-print::
+    :type: table
+    :category: misc
diff --git a/docs/users_guide/ghc.mk b/docs/users_guide/ghc.mk
index 9144a0728e..c2e20ebc03 100644
--- a/docs/users_guide/ghc.mk
+++ b/docs/users_guide/ghc.mk
@@ -11,9 +11,7 @@
 # -----------------------------------------------------------------------------
 
 
-docs/users_guide_RST_SOURCES := \
-		$(utils/mkUserGuidePart_GENERATED_RST_SOURCES) \
-		$(wildcard docs/users_guide/*.rst)
+docs/users_guide_RST_SOURCES := $(wildcard docs/users_guide/*.rst)
 
 $(eval $(call sphinx,docs/users_guide,users_guide))
 
@@ -26,7 +24,7 @@ MAN_SECTION := 1
 MAN_PAGES := docs/users_guide/build-man/ghc.1
 
 ifneq "$(BINDIST)" "YES"
-$(MAN_PAGES): $(docs/users_guide_MAN_RST_SOURCES) $(utils/mkUserGuidePart_GENERATED_RST_SOURCES)
+$(MAN_PAGES): $(docs/users_guide_MAN_RST_SOURCES)
 	$(SPHINXBUILD) -b man -d docs/users_guide/.doctrees-man docs/users_guide docs/users_guide/build-man
 endif
 
diff --git a/docs/users_guide/ghc.rst b/docs/users_guide/ghc.rst
index a44c9d94f6..7e20069396 100644
--- a/docs/users_guide/ghc.rst
+++ b/docs/users_guide/ghc.rst
@@ -62,7 +62,317 @@ Common suffixes of file names for Haskell are:
 Options
 -------
 
-.. include:: all-flags.gen.rst
+.. flag-print::
+    :type: summary
+    :category: codegen
+
+
+.. flag-print::
+    :type: summary
+    :category: debugging
+
+
+.. flag-print::
+    :type: summary
+    :category: cpp
+
+
+.. flag-print::
+    :type: summary
+    :category: search-path
+
+
+.. flag-print::
+    :type: summary
+    :category: interactive
+
+
+.. flag-print::
+    :type: summary
+    :category: interface-files
+
+
+.. flag-print::
+    :type: summary
+    :category: keep-intermediates
+
+
+.. flag-print::
+    :type: summary
+    :category: language
+
+
+.. flag-print::
+    :type: summary
+    :category: linking
+
+
+.. flag-print::
+    :type: summary
+    :category: misc
+
+
+.. flag-print::
+    :type: summary
+    :category: modes
+
+
+.. flag-print::
+    :type: summary
+    :category: optimization
+
+
+.. flag-print::
+    :type: summary
+    :category: optimization-levels
+
+
+.. flag-print::
+    :type: summary
+    :category: packages
+
+
+.. flag-print::
+    :type: summary
+    :category: phases
+
+
+.. flag-print::
+    :type: summary
+    :category: phase-programs
+
+
+.. flag-print::
+    :type: summary
+    :category: phase-options
+
+
+.. flag-print::
+    :type: summary
+    :category: platform-options
+
+
+.. flag-print::
+    :type: summary
+    :category: plugins
+
+
+.. flag-print::
+    :type: summary
+    :category: profiling
+
+
+.. flag-print::
+    :type: summary
+    :category: coverage
+
+
+.. flag-print::
+    :type: summary
+    :category: recompilation
+
+
+.. flag-print::
+    :type: summary
+    :category: redirect-output
+
+
+.. flag-print::
+    :type: summary
+    :category: temp-files
+
+
+.. flag-print::
+    :type: summary
+    :category: verbosity
+
+
+.. flag-print::
+    :type: summary
+    :category: warnings
+
+
+Code generation
+~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: codegen
+
+Debugging the compiler
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: debugging
+
+C pre-processor
+~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: cpp
+
+Finding imports
+~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: search-path
+
+Interactive mode
+~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: interactive
+
+Interface files
+~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: interface-files
+
+Keeping intermediate files
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: keep-intermediates
+
+Language options
+~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: language
+
+Linking options
+~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: linking
+
+Miscellaneous options
+~~~~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: misc
+
+Modes of operation
+~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: modes
+
+Individual optimizations
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: optimization
+
+Optimization levels
+~~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: optimization-levels
+
+Package options
+~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: packages
+
+Phases of compilation
+~~~~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: phases
+
+Overriding external programs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: phase-programs
+
+Phase-specific options
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: phase-options
+
+Platform-specific options
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: platform-options
+
+Compiler plugins
+~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: plugins
+
+Profiling
+~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: profiling
+
+Program coverage
+~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: coverage
+
+Recompilation checking
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: recompilation
+
+Redirecting output
+~~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: redirect-output
+
+Temporary files
+~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: temp-files
+
+Verbosity options
+~~~~~~~~~~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: verbosity
+
+Warnings
+~~~~~~~~
+
+.. flag-print::
+    :type: list
+    :category: warnings
 
 Copyright
 ---------
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst
index 52fbf6e323..fa8609d47b 100644
--- a/docs/users_guide/ghci.rst
+++ b/docs/users_guide/ghci.rst
@@ -434,6 +434,10 @@ The statement ``x <- return 42`` means “execute ``return 42`` in the
 future statements, for example to print it as we did above.
 
 .. ghc-flag:: -fprint-bind-result
+    :shortdesc: :ref:`Turn on printing of binding results in GHCi <ghci-stmts>`
+    :type: dynamic
+    :reverse: -fno-print-bind-result
+    :category:
 
     If :ghc-flag:`-fprint-bind-result` is set then GHCi will print the result of a
     statement if and only if:
@@ -1020,6 +1024,14 @@ Type defaulting in GHCi
    single: Show class
 
 .. ghc-flag:: -XExtendedDefaultRules
+    :shortdesc: Use GHCi's
+        :ref:`extended default rules <extended-default-rules>` in a normal
+        module.
+    :type: dynamic
+    :reverse: -XNoExtendedDefaultRules
+    :category: language
+
+    :since: 6.8.1
 
     Allow defaulting to take place for more than just numeric classes.
 
@@ -1155,6 +1167,10 @@ it survive a :ghci-cmd:`:cd`, :ghci-cmd:`:add`, :ghci-cmd:`:load`,
 :ghci-cmd:`:reload` or, :ghci-cmd:`:set`.
 
 .. ghc-flag:: -interactive-print ⟨expr⟩
+    :shortdesc: :ref:`Select the function to use for printing evaluated
+        expressions in GHCi <ghci-interactive-print>`
+    :type: dynamic
+    :category:
 
     Set the function used by GHCi to print evaluation results. Expression
     must be of type ``C a => a -> IO ()``.
@@ -1744,6 +1760,10 @@ is we found that logging each breakpoint in the history cuts performance
 by a factor of 2 or more.
 
 .. ghc-flag:: -fghci-hist-size=⟨n⟩
+    :shortdesc: Set the number of entries GHCi keeps for ``:history``.
+        See :ref:`ghci-debugger`.
+    :type: dynamic
+    :category:
 
     :default: 50
 
@@ -1808,12 +1828,26 @@ program was doing when it was in an infinite loop. Just hit Control-C,
 and examine the history to find out what was going on.
 
 .. ghc-flag:: -fbreak-on-exception
-              -fbreak-on-error
+    :shortdesc: :ref:`Break on any exception thrown <ghci-debugger-exceptions>`
+    :type: dynamic
+    :reverse: -fno-break-on-exception
+    :category:
 
     Causes GHCi to halt evaluation and return to the interactive prompt
-    in the event of an exception. While :ghc-flag:`-fbreak-on-exception` breaks
-    on all exceptions, :ghc-flag:`-fbreak-on-error` breaks on only those which
-    would otherwise be uncaught.
+    in the event of an exception. :ghc-flag:`-fbreak-on-exception` breaks
+    on all exceptions.
+
+.. ghc-flag:: -fbreak-on-error
+    :shortdesc: :ref:`Break on uncaught exceptions and errors
+        <ghci-debugger-exceptions>`
+    :type: dynamic
+    :reverse: -fno-break-on-error
+    :category:
+
+    Causes GHCi to halt evaluation and return to the interactive prompt in the
+    event of an exception.  :ghc-flag:`-fbreak-on-error` breaks on only those
+    exceptions which would otherwise be uncaught.
+
 
 Example: inspecting functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1954,15 +1988,20 @@ also make sense in interactive mode. The ones that don't make sense are
 mostly obvious.
 
 .. ghc-flag:: -flocal-ghci-history
+    :shortdesc: Use current directory for the GHCi command history
+        file ``.ghci-history``.
+    :type: dynamic
+    :reverse: -fno-local-ghci-history
+    :category:
 
-  By default, GHCi keeps global history in ``~/.ghc/ghci_history`` or
-  ``%APPDATA%/<app>/ghci_history``, but you can use current directory, e.g.:
+    By default, GHCi keeps global history in ``~/.ghc/ghci_history`` or
+    ``%APPDATA%/<app>/ghci_history``, but you can use current directory, e.g.:
 
-  .. code-block:: none
+    .. code-block:: none
 
-      $ ghci -flocal-ghci-history
+        $ ghci -flocal-ghci-history
 
-  It will create ``.ghci-history`` in current folder where GHCi is launched.
+    It will create ``.ghci-history`` in current folder where GHCi is launched.
 
 Packages
 ~~~~~~~~
@@ -3063,11 +3102,17 @@ Two command-line options control whether the startup files files are
 read:
 
 .. ghc-flag:: -ignore-dot-ghci
+    :shortdesc: Disable reading of ``.ghci`` files
+    :type: dynamic
+    :category:
 
     Don't read either :file:`./.ghci` or the other startup files when
     starting up.
 
 .. ghc-flag:: -ghci-script
+    :shortdesc: Read additional ``.ghci`` files
+    :type: dynamic
+    :category:
 
     Read a specific file after the usual startup files. Maybe be
     specified repeatedly for multiple inputs.
@@ -3156,6 +3201,9 @@ separate process for running interpreted code, and communicate with it
 using messages over a pipe.
 
 .. ghc-flag:: -fexternal-interpreter
+    :shortdesc: Run interpreted code in a separate process
+    :type: dynamic
+    :category: misc
 
     :since: 8.0.1
 
diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index ac64153dfa..3083d43666 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -49,10 +49,15 @@ Although not recommended, the deprecated :ghc-flag:`-fglasgow-exts` flag enables
 a large swath of the extensions supported by GHC at once.
 
 .. ghc-flag:: -fglasgow-exts
+    :shortdesc: Deprecated. Enable most language extensions;
+        see :ref:`options-language` for exactly which ones.
+    :type: dynamic
+    :reverse: -fno-glasgow-exts
+    :category:
 
     The flag ``-fglasgow-exts`` is equivalent to enabling the following extensions:
 
-    .. include:: what_glasgow_exts_does.gen.rst
+    .. include:: what_glasgow_exts_does.rst
 
     Enabling these options is the *only* effect of ``-fglasgow-exts``. We are trying
     to move away from this portmanteau flag, and towards enabling features
@@ -201,6 +206,12 @@ Unboxed tuples
 --------------
 
 .. ghc-flag:: -XUnboxedTuples
+    :shortdesc: Enable :ref:`unboxed tuples <unboxed-tuples>`.
+    :type: dynamic
+    :reverse: -XNoUnboxedTuples
+    :category:
+
+    :since: 6.8.1
 
     Enable the use of unboxed tuple syntax.
 
@@ -262,6 +273,12 @@ Unboxed sums
 ------------
 
 .. ghc-flag:: -XUnboxedSums
+    :shortdesc: Enable :ref: `unboxed sums <unboxed-sums>`.
+    :type: dynamic
+    :reverse: -XNoUnboxedSums
+    :category:
+
+    :since: 8.2.1
 
     Enable the use of unboxed sum syntax.
 
@@ -344,6 +361,12 @@ Unicode syntax
 --------------
 
 .. ghc-flag:: -XUnicodeSyntax
+    :shortdesc: Enable :ref:`unicode syntax <unicode-syntax>`.
+    :type: dynamic
+    :reverse: -XNoUnicodeSyntax
+    :category:
+
+    :since: 6.8.1
 
     Enable the use of Unicode characters in place of their equivalent ASCII
     sequences.
@@ -391,6 +414,12 @@ The magic hash
 --------------
 
 .. ghc-flag:: -XMagicHash
+    :shortdesc: Allow ``#`` as a :ref:`postfix modifier on identifiers <magic-hash>`.
+    :type: dynamic
+    :reverse: -XNoMagicHash
+    :category:
+
+    :since: 6.8.1
 
     Enable the use of the hash character (``#``) as an identifier suffix.
 
@@ -433,6 +462,10 @@ Negative literals
 -----------------
 
 .. ghc-flag:: -XNegativeLiterals
+    :shortdesc: Enable support for :ref:`negative literals <negative-literals>`.
+    :type: dynamic
+    :reverse: -XNoNegativeLiterals
+    :category:
 
     :since: 7.8.1
 
@@ -454,6 +487,10 @@ Fractional looking integer literals
 -----------------------------------
 
 .. ghc-flag:: -XNumDecimals
+    :shortdesc: Enable support for 'fractional' integer literals.
+    :type: dynamic
+    :reverse: -XNoNumDecimals
+    :category:
 
     :since: 7.8.1
 
@@ -472,6 +509,10 @@ Binary integer literals
 -----------------------
 
 .. ghc-flag:: -XBinaryLiterals
+    :shortdesc: Enable support for :ref:`binary literals <binary-literals>`.
+    :type: dynamic
+    :reverse: -XNoBinaryLiterals
+    :category:
 
     :since: 7.10.1
 
@@ -492,6 +533,11 @@ Pattern guards
 --------------
 
 .. ghc-flag:: -XNoPatternGuards
+    :shortdesc: Disable :ref:`pattern guards <pattern-guards>`.
+        Implied by :ghc-flag:`-XHaskell98`.
+    :type: dynamic
+    :reverse: -XPatternGuards
+    :category:
 
     :implied by: :ghc-flag:`-XHaskell98`
     :since: 6.8.1
@@ -505,6 +551,12 @@ View patterns
 -------------
 
 .. ghc-flag:: -XViewPatterns
+    :shortdesc: Enable :ref:`view patterns <view-patterns>`.
+    :type: dynamic
+    :reverse: -XNoViewPatterns
+    :category:
+
+    :since: 6.10.1
 
     Allow use of view pattern syntax.
 
@@ -643,9 +695,14 @@ n+k patterns
 ------------
 
 .. ghc-flag:: -XNPlusKPatterns
+    :shortdesc: Enable support for ``n+k`` patterns.
+        Implied by :ghc-flag:`-XHaskell98`.
+    :type: dynamic
+    :reverse: -XNoNPlusKPatterns
+    :category:
 
     :implied by: :ghc-flag:`-XHaskell98`
-    :since: 6.12
+    :since: 6.12.1
 
     Enable use of ``n+k`` patterns.
 
@@ -655,6 +712,12 @@ The recursive do-notation
 -------------------------
 
 .. ghc-flag:: -XRecursiveDo
+    :shortdesc: Enable :ref:`recursive do (mdo) notation <recursive-do-notation>`.
+    :type: dynamic
+    :reverse: -XNoRecursiveDo
+    :category:
+
+    :since: 6.8.1
 
     Allow the use of recursive ``do`` notation.
 
@@ -867,6 +930,10 @@ Applicative do-notation
    single: do-notation; Applicative
 
 .. ghc-flag:: -XApplicativeDo
+    :shortdesc: Enable :ref:`Applicative do-notation desugaring <applicative-do>`
+    :type: dynamic
+    :reverse: -XNoApplicativeDo
+    :category:
 
     :since: 8.0.1
 
@@ -957,6 +1024,10 @@ cases it might miss an opportunity.  There is an algorithm that finds
 the optimal solution, provided as an option:
 
 .. ghc-flag:: -foptimal-applicative-do
+    :shortdesc: Use a slower but better algorithm for ApplicativeDo
+    :type: dynamic
+    :reverse: -fno-optimal-applicative-do
+    :category: optimization
 
     :since: 8.0.1
 
@@ -1093,6 +1164,14 @@ Parallel List Comprehensions
    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:
+
+    :since: 6.8.1
 
     Allow parallel list comprehension syntax.
 
@@ -1142,6 +1221,13 @@ Generalised (SQL-like) List Comprehensions
    single: SQL
 
 .. ghc-flag:: -XTransformListComp
+    :shortdesc: Enable :ref:`generalised list comprehensions
+        <generalised-list-comprehensions>`.
+    :type: dynamic
+    :reverse: -XNoTransformListComp
+    :category:
+
+    :since: 6.10.1
 
     Allow use of generalised list (SQL-like) comprehension syntax. This
     introduces the ``group``, ``by``, and ``using`` keywords.
@@ -1280,8 +1366,12 @@ Monad comprehensions
    single: monad comprehensions
 
 .. ghc-flag:: -XMonadComprehensions
+    :shortdesc: Enable :ref:`monad comprehensions <monad-comprehensions>`.
+    :type: dynamic
+    :reverse: -XNoMonadComprehensions
+    :category:
 
-    :since: 7.2
+    :since: 7.2.1
 
     Enable list comprehension syntax for arbitrary monads.
 
@@ -1442,6 +1532,10 @@ New monadic failure desugaring mechanism
 ----------------------------------------
 
 .. ghc-flag:: -XMonadFailDesugaring
+    :shortdesc: Enable :ref:`monadfail desugaring <monadfail-desugaring>`.
+    :type: dynamic
+    :reverse: -XNoMonadFailDesugaring
+    :category:
 
     :since: 8.0.1
 
@@ -1464,6 +1558,13 @@ Rebindable syntax and the implicit Prelude import
 -------------------------------------------------
 
 .. ghc-flag:: -XNoImplicitPrelude
+    :shortdesc: Don't implicitly ``import Prelude``.
+        Implied by :ghc-flag:`-XRebindableSyntax`.
+    :type: dynamic
+    :reverse: -XImplicitPrelude
+    :category:
+
+    :since: 6.8.1
 
     Don't import ``Prelude`` by default.
 
@@ -1474,6 +1575,11 @@ 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:
 
     :implies: :ghc-flag:`-XNoImplicitPrelude`
     :since: 7.0.1
@@ -1574,6 +1680,12 @@ Postfix operators
 -----------------
 
 .. ghc-flag:: -XPostfixOperators
+    :shortdesc: Enable :ref:`postfix operators <postfix-operators>`.
+    :type: dynamic
+    :reverse: -XNoPostfixOperators
+    :category:
+
+    :since: 7.10.1
 
     Allow the use of post-fix operators
 
@@ -1606,6 +1718,10 @@ Tuple sections
 --------------
 
 .. ghc-flag:: -XTupleSections
+    :shortdesc: Enable :ref:`tuple sections <tuple-sections>`.
+    :type: dynamic
+    :reverse: -XNoTupleSections
+    :category:
 
     :since: 6.12
 
@@ -1647,6 +1763,10 @@ Lambda-case
 -----------
 
 .. ghc-flag:: -XLambdaCase
+    :shortdesc: Enable :ref:`lambda-case expressions <lambda-case>`.
+    :type: dynamic
+    :reverse: -XNoLambdaCase
+    :category:
 
     :since: 7.6.1
 
@@ -1673,6 +1793,10 @@ Empty case alternatives
 -----------------------
 
 .. ghc-flag:: -XEmptyCase
+    :shortdesc: Allow :ref:`empty case alternatives <empty-case>`.
+    :type: dynamic
+    :reverse: -XNoEmptyCase
+    :category:
 
     :since: 7.8.1
 
@@ -1720,6 +1844,10 @@ Multi-way if-expressions
 ------------------------
 
 .. ghc-flag:: -XMultiWayIf
+    :shortdesc: Enable :ref:`multi-way if-expressions <multi-way-if>`.
+    :type: dynamic
+    :reverse: -XNoMultiWayIf
+    :category:
 
     :since: 7.6.1
 
@@ -1836,6 +1964,12 @@ Package-qualified imports
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. ghc-flag:: -XPackageImports
+    :shortdesc: Enable :ref:`package-qualified imports <package-imports>`.
+    :type: dynamic
+    :reverse: -XNoPackageImports
+    :category:
+
+    :since: 6.10.1
 
     Allow the use of package-qualified ``import`` syntax.
 
@@ -1867,11 +2001,32 @@ Safe imports
 ~~~~~~~~~~~~
 
 .. ghc-flag:: -XSafe
-              -XTrustworthy
-              -XUnsafe
+    :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
+    :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:
     :noindex:
 
-    :since: 7.2
+    :since: 7.4.1
 
     Declare the Safe Haskell state of the current module.
 
@@ -1892,6 +2047,12 @@ Explicit namespaces in import/export
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. ghc-flag:: -XExplicitNamespaces
+    :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:
 
     :since: 7.6.1
 
@@ -2027,6 +2188,12 @@ Data types with no constructors
 -------------------------------
 
 .. ghc-flag:: -XEmptyDataDecls
+    :shortdesc: Allow definition of empty ``data`` types.
+    :type: dynamic
+    :reverse: -XNoEmptyDataDecls
+    :category:
+
+    :since: 6.8.1
 
     Allow definition of empty ``data`` types.
 
@@ -2049,6 +2216,10 @@ Data type contexts
 ------------------
 
 .. ghc-flag:: -XDatatypeContexts
+    :shortdesc: Allow contexts on ``data`` types.
+    :type: dynamic
+    :reverse: -XNoEmptyDataDecls
+    :category:
 
     :since: 7.0.1
 
@@ -2121,8 +2292,14 @@ Type operators
 --------------
 
 .. ghc-flag:: -XTypeOperators
+    :shortdesc: Enable :ref:`type operators <type-operators>`.
+        Implies :ghc-flag:`-XExplicitNamespaces`.
+    :type: dynamic
+    :reverse: -XNoTypeOperators
+    :category:
 
     :implies: :ghc-flag:`-XExplicitNamespaces`
+    :since: 6.8.1
 
     Allow the use and definition of types with operator names.
 
@@ -2172,8 +2349,13 @@ Liberalised type synonyms
 -------------------------
 
 .. ghc-flag:: -XLiberalTypeSynonyms
+    :shortdesc: Enable :ref:`liberalised type synonyms <type-synonyms>`.
+    :type: dynamic
+    :reverse: -XNoLiberalTypeSynonyms
+    :category:
 
     :implies: :ghc-flag:`-XExplicitForAll`
+    :since: 6.8.1
 
     Relax many of the Haskell 98 rules on type synonym definitions.
 
@@ -2250,8 +2432,13 @@ Existentially quantified data constructors
 ------------------------------------------
 
 .. ghc-flag:: -XExistentialQuantification
+    :shortdesc: Enable :ref:`liberalised type synonyms <type-synonyms>`.
+    :type: dynamic
+    :reverse: -XNoLiberalTypeSynonyms
+    :category:
 
     :implies: :ghc-flag:`-XExplicitForAll`
+    :since: 6.8.1
 
     Allow existentially quantified type variables in types.
 
@@ -2506,8 +2693,12 @@ 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:
 
-    :since: 7.2
+    :since: 7.2.1
 
     Allow the use of GADT syntax in data type definitions (but not GADTs
     themselves; for this see :ghc-flag:`-XGADTs`)
@@ -2758,8 +2949,14 @@ 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:
 
     :implies: :ghc-flag:`-XMonoLocalBinds`, :ghc-flag:`-XGADTSyntax`
+    :since: 6.8.1
 
     Allow use of Generalised Algebraic Data Types (GADTs).
 
@@ -2897,6 +3094,11 @@ Traditional record syntax
 -------------------------
 
 .. ghc-flag:: -XNoTraditionalRecordSyntax
+    :shortdesc: Disable support for traditional record syntax
+        (as supported by Haskell 98) ``C {f = x}``
+    :type: dynamic
+    :reverse: -XTraditionalRecordSyntax
+    :category:
 
     :since: 7.4.1
 
@@ -2911,6 +3113,13 @@ 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
 
     :since: 6.8.1
 
@@ -2984,6 +3193,10 @@ Duplicate record fields
 -----------------------
 
 .. ghc-flag:: -XDuplicateRecordFields
+    :shortdesc: Allow definition of record types with identically-named fields.
+    :type: dynamic
+    :reverse: -XNoDuplicateRecordFields
+    :category:
 
     :implies: :ghc-flag:`-XDisambiguateRecordFields`
     :since: 8.0.1
@@ -3118,6 +3331,12 @@ Record puns
 -----------
 
 .. ghc-flag:: -XNamedFieldPuns
+    :shortdesc: Enable :ref:`record puns <record-puns>`.
+    :type: dynamic
+    :reverse: -XNoNamedFieldPuns
+    :category:
+
+    :since: 6.10.1
 
     Allow use of record puns.
 
@@ -3179,8 +3398,14 @@ Record wildcards
 ----------------
 
 .. ghc-flag:: -XRecordWildCards
+    :shortdesc: Enable :ref:`record wildcards <record-wildcards>`.
+        Implies :ghc-flag:`-XDisambiguateRecordFields`.
+    :type: dynamic
+    :reverse: -XNoRecordWildCards
+    :category:
 
     :implies: :ghc-flag:`-XDisambiguateRecordFields`.
+    :since: 6.8.1
 
     Allow the use of wildcards in record construction and pattern matching.
 
@@ -3487,6 +3712,12 @@ Stand-alone deriving declarations
 ---------------------------------
 
 .. ghc-flag:: -XStandaloneDeriving
+    :shortdesc: Enable :ref:`standalone deriving <stand-alone-deriving>`.
+    :type: dynamic
+    :reverse: -XNoStandaloneDeriving
+    :category:
+
+    :since: 6.8.1
 
     Allow the use of stand-alone ``deriving`` declarations.
 
@@ -3588,28 +3819,46 @@ 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
+    :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: 6.12
+    :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: 6.12
+    :since: 7.10.1
 
     Allow automatic deriving of instances for the ``Foldable`` typeclass.
 
 .. ghc-flag:: -XDeriveTraversable
-
-    :since: 6.12
+    :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.
 
@@ -4048,6 +4297,13 @@ 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:
+
+    :since: 6.8.1
 
     Enable automatic deriving of instances for the ``Data`` typeclass
 
@@ -4100,8 +4356,12 @@ Deriving ``Lift`` instances
 ---------------------------
 
 .. ghc-flag:: -XDeriveLift
+    :shortdesc: Enable :ref:`deriving for the Lift class <deriving-lift>`
+    :type: dynamic
+    :reverse: -XNoDeriveLift
+    :category:
 
-    :since: 8.0.1
+    :since: 7.2.1
 
     Enable automatic deriving of instances for the ``Lift`` typeclass for
     Template Haskell.
@@ -4181,6 +4441,12 @@ Generalised derived instances for newtypes
 
 .. ghc-flag:: -XGeneralisedNewtypeDeriving
               -XGeneralizedNewtypeDeriving
+    :shortdesc: Enable :ref:`newtype deriving <newtype-deriving>`.
+    :type: dynamic
+    :reverse: -XNoGeneralizedNewtypeDeriving
+    :category:
+
+    :since: 6.8.1
 
     Enable GHC's cunning generalised deriving mechanism for ``newtype``\s
 
@@ -4499,6 +4765,10 @@ Deriving any other class
 ------------------------
 
 .. ghc-flag:: -XDeriveAnyClass
+    :shortdesc: Enable :ref:`deriving for any class <derive-any-class>`.
+    :type: dynamic
+    :reverse: -XNoDeriveAnyClass
+    :category:
 
     :since: 7.10.1
 
@@ -4645,6 +4915,12 @@ Deriving strategies
 -------------------
 
 .. ghc-flag:: -XDerivingStrategies
+    :shortdesc: Enables :ref:`deriving strategies <deriving-strategies>`.
+    :type: dynamic
+    :reverse: -XNoDerivingStrategies
+    :category:
+
+    :since: 8.2.1
 
     Allow multiple ``deriving``, each optionally qualified with a *strategy*.
 
@@ -4707,6 +4983,10 @@ Pattern synonyms
 ================
 
 .. ghc-flag:: -XPatternSynonyms
+    :shortdesc: Enable :ref:`pattern synonyms <pattern-synonyms>`.
+    :type: dynamic
+    :reverse: -XNoPatternSynonyms
+    :category:
 
     :since: 7.8.1
 
@@ -5157,8 +5437,15 @@ 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:
 
     :implies: :ghc-flag:`-XConstrainedClassMethods`
+    :since: 6.8.1
 
     Allow the definition of typeclasses with more than one parameter.
 
@@ -5175,6 +5462,13 @@ 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:
+
+    :since: 6.8.1
 
     Allow the use of complex constraints in class declaration contexts.
 
@@ -5225,6 +5519,12 @@ Constrained class method types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. ghc-flag:: -XConstrainedClassMethods
+    :shortdesc: Enable :ref:`constrained class methods <class-method-types>`.
+    :type: dynamic
+    :reverse: -XNoConstrainedClassMethods
+    :category:
+
+    :since: 6.8.1
 
     Allows the definition of further constraints on individual class methods.
 
@@ -5265,8 +5565,12 @@ Default method signatures
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. ghc-flag:: -XDefaultSignatures
+    :shortdesc: Enable :ref:`default signatures <class-default-signatures>`.
+    :type: dynamic
+    :reverse: -XNoDefaultSignatures
+    :category:
 
-    :since: 7.2
+    :since: 7.2.1
 
     Allows the definition of default method signatures in class definitions.
 
@@ -5358,6 +5662,12 @@ 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:
 
     :since: 7.8.1
 
@@ -5394,8 +5704,14 @@ Functional dependencies
 -----------------------
 
 .. ghc-flag:: -XFunctionalDependencies
+    :shortdesc: Enable :ref:`functional dependencies <functional-dependencies>`.
+        Implies :ghc-flag:`-XMultiParamTypeClasses`.
+    :type: dynamic
+    :reverse: -XNoFunctionalDependencies
+    :category:
 
     :implies: :ghc-flag:`-XMultiParamTypeClasses`
+    :since: 6.8.1
 
     Allow use of functional dependencies in class declarations.
 
@@ -5732,12 +6048,26 @@ 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:
+
+    :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:
 
     :implies: :ghc-flag:`-XTypeSynonymInstances`
+    :since: 6.8.1
 
     Allow definition of type class instances with arbitrary nested types in the
     instance head.
@@ -5809,6 +6139,12 @@ Instance termination rules
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. ghc-flag:: -XUndecidableInstances
+    :shortdesc: Enable :ref:`undecidable instances <undecidable-instances>`.
+    :type: dynamic
+    :reverse: -XNoUndecidableInstances
+    :category:
+
+    :since: 6.8.1
 
     Permit definition of instances which may lead to type-checker non-termination.
 
@@ -6002,9 +6338,24 @@ Overlapping instances
 ~~~~~~~~~~~~~~~~~~~~~
 
 .. ghc-flag:: -XOverlappingInstances
-              -XIncoherentInstances
+    :shortdesc: Enable :ref:`overlapping instances <instance-overlap>`.
+    :type: dynamic
+    :reverse: -XNoOverlappingInstances
+    :category:
+
+    Deprecated flag 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:
 
-    Deprecated flags to weaken checks intended to ensure instance resolution
+    :since: 6.8.1
+
+    Deprecated flag to weaken checks intended to ensure instance resolution
     termination.
 
 In general, as discussed in :ref:`instance-resolution`, *GHC requires
@@ -6219,6 +6570,10 @@ Instance signatures: type signatures in instance declarations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. ghc-flag:: -XInstanceSigs
+    :shortdesc: Enable :ref:`instance signatures <instance-sigs>`.
+    :type: dynamic
+    :reverse: -XNoInstanceSigs
+    :category:
 
     :since: 7.6.1
 
@@ -6276,6 +6631,12 @@ Overloaded string literals
 --------------------------
 
 .. ghc-flag:: -XOverloadedStrings
+    :shortdesc: Enable :ref:`overloaded string literals <overloaded-strings>`.
+    :type: dynamic
+    :reverse: -XNoOverloadedStrings
+    :category:
+
+    :since: 6.8.1
 
     Enable overloaded string literals (e.g. string literals desugared via the
     ``IsString`` class).
@@ -6356,6 +6717,10 @@ Overloaded labels
 -----------------
 
 .. ghc-flag:: -XOverloadedLabels
+    :shortdesc: Enable :ref:`overloaded labels <overloaded-labels>`.
+    :type: dynamic
+    :reverse: -XNoOverloadedLabels
+    :category:
 
     :since: 8.0.1
 
@@ -6448,6 +6813,10 @@ Overloaded lists
 ----------------
 
 .. ghc-flag:: -XOverloadedLists
+    :shortdesc: Enable :ref:`overloaded lists <overloaded-lists>`.
+    :type: dynamic
+    :reverse: -XNoOverloadedLists
+    :category:
 
     :since: 7.8.1
 
@@ -6615,6 +6984,11 @@ Undecidable (or recursive) superclasses
 ---------------------------------------
 
 .. ghc-flag:: -XUndecidableSuperClasses
+    :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
 
@@ -6673,9 +7047,16 @@ 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:
 
     :implies: :ghc-flag:`-XMonoLocalBinds`, :ghc-flag:`-XKindSignatures`,
               :ghc-flag:`-XExplicitNamespaces`
+    :since: 6.8.1
 
     Allow use and definition of indexed type and data families.
 
@@ -7569,6 +7950,11 @@ Injective type families
 -----------------------
 
 .. ghc-flag:: -XTypeFamilyDependencies
+    :shortdesc: Enable :ref:`injective type families <injective-ty-fams>`.
+        Implies :ghc-flag:`-XTypeFamilies`.
+    :type: dynamic
+    :reverse: -XNoTypeFamilyDependencies
+    :category:
 
     :implies: :ghc-flag:`-XTypeFamilies`
     :since: 8.0.1
@@ -7697,6 +8083,10 @@ Datatype promotion
 ==================
 
 .. ghc-flag:: -XDataKinds
+    :shortdesc: Enable :ref:`datatype promotion <promotion>`.
+    :type: dynamic
+    :reverse: -XNoDataKinds
+    :category:
 
     :since: 7.4.1
 
@@ -7915,6 +8305,14 @@ Kind polymorphism and Type-in-Type
 ==================================
 
 .. 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:
 
     :implies: :ghc-flag:`-XPolyKinds`, :ghc-flag:`-XDataKinds`, :ghc-flag:`-XKindSignatures`
     :since: 8.0.1
@@ -7924,6 +8322,11 @@ Kind polymorphism and Type-in-Type
     families in kinds, among other features.
 
 .. ghc-flag:: -XPolyKinds
+    :shortdesc: Enable :ref:`kind polymorphism <kind-polymorphism>`.
+        Implies :ghc-flag:`-XKindSignatures`.
+    :type: dynamic
+    :reverse: -XNoPolyKinds
+    :category:
 
     :implies: :ghc-flag:`-XKindSignatures`
     :since: 7.4.1
@@ -8590,9 +8993,14 @@ Printing levity-polymorphic types
 ---------------------------------
 
 .. ghc-flag:: -Wprint-explicit-runtime-rep
+    :shortdesc: Print ``RuntimeRep`` variables in types which are
+        runtime-representation polymorphic.
+    :type: dynamic
+    :reverse: -fno-print-explicit-runtime-reps
+    :category:
 
-  Print ``RuntimeRep`` parameters as they appear; otherwise, they are
-  defaulted to ``'LiftedRep``.
+    Print ``RuntimeRep`` parameters as they appear; otherwise, they are
+    defaulted to ``'LiftedRep``.
 
 Most GHC users will not need to worry about levity polymorphism
 or unboxed types. For these users, seeing the levity polymorphism
@@ -8810,6 +9218,10 @@ The ``Constraint`` kind
 -----------------------
 
 .. ghc-flag:: -XConstraintKinds
+    :shortdesc: Enable a :ref:`kind of constraints <constraint-kind>`.
+    :type: dynamic
+    :reverse: -XNoConstraintKinds
+    :category:
 
     :since: 7.4.1
 
@@ -8894,8 +9306,14 @@ 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:
 
-    :since: 6.12
+    :since: 6.12.1
 
     Allow use of the ``forall`` keyword in places where universal quantification
     is implicit.
@@ -8955,6 +9373,11 @@ Ambiguous types and the ambiguity check
 ---------------------------------------
 
 .. ghc-flag:: -XAllowAmbiguousTypes
+    :shortdesc: Allow the user to write :ref:`ambiguous types <ambiguity>`, and
+        the type inference engine to infer them.
+    :type: dynamic
+    :reverse: -XNoAllowAmbiguousTypes
+    :category:
 
     :since: 7.8.1
 
@@ -9080,6 +9503,13 @@ 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:
+
+    :since: 6.8.1
 
     Allow explicit kind signatures on type variables.
 
@@ -9144,8 +9574,14 @@ Lexically scoped type variables
 ===============================
 
 .. ghc-flag:: -XScopedTypeVariables
+    :shortdesc: Enable :ref:`lexically-scoped type variables
+        <scoped-type-variables>`.
+    :type: dynamic
+    :reverse: -XNoScopedTypeVariables
+    :category:
 
     :implies: :ghc-flag:`-XExplicitForAll`
+    :since: 6.8.1
 
     Enable lexical scoping of type variables explicitly introduced with
     ``forall``.
@@ -9367,8 +9803,13 @@ Switching off the dreaded Monomorphism Restriction
 --------------------------------------------------
 
 .. ghc-flag:: -XNoMonomorphismRestriction
+    :shortdesc: Disable the :ref:`monomorphism restriction <monomorphism>`.
+    :type: dynamic
+    :reverse: -XMonomorphismRestriction
+    :category:
 
     :default: on
+    :since: 6.8.1
 
     Prevents the compiler from applying the monomorphism restriction to
     bindings lacking explicit type signatures.
@@ -9386,8 +9827,13 @@ 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:
 
-    :since: 6.12
+    :since: 6.12.1
 
     Infer less polymorphic types for local bindings by default.
 
@@ -9493,6 +9939,10 @@ Visible type application
 ========================
 
 .. ghc-flag:: -XTypeApplications
+    :shortdesc: Enable :ref:`type application syntax <visible-type-application>`.
+    :type: dynamic
+    :reverse: -XNoTypeApplications
+    :category:
 
     :since: 8.0.1
 
@@ -9622,6 +10072,13 @@ 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:
+
+    :since: 6.8.1
 
     Allow definition of functions expecting implicit parameters.
 
@@ -9819,12 +10276,25 @@ Arbitrary-rank polymorphism
 ===========================
 
 .. ghc-flag:: -XRankNTypes
+    :shortdesc: Enable :ref:`rank-N types <universal-quantification>`.
+        Implied by :ghc-flag:`-XImpredicativeTypes`.
+    :type: dynamic
+    :reverse: -XNoRankNTypes
+    :category:
 
     :implies: :ghc-flag:`-XExplicitForAll`
+    :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:
+
+    :since: 6.8.1
 
     A deprecated alias of :ghc-flag:`-XRankNTypes`.
 
@@ -10085,8 +10555,14 @@ Impredicative polymorphism
 ==========================
 
 .. ghc-flag:: -XImpredicativeTypes
+    :shortdesc: Enable :ref:`impredicative types <impredicative-polymorphism>`.
+        Implies :ghc-flag:`-XRankNTypes`.
+    :type: dynamic
+    :reverse: -XNoImpredicativeTypes
+    :category:
 
     :implies: :ghc-flag:`-XRankNTypes`
+    :since: 6.10.1
 
     Allow impredicative polymorphic types.
 
@@ -10275,6 +10751,9 @@ There's a flag for controlling the amount of context information shown for
 typed holes:
 
 .. ghc-flag:: -fshow-hole-constraints
+    :shortdesc: Show constraints when reporting typed holes
+    :type: dynamic
+    :category: verbosity
 
     When reporting typed holes, also print constraints that are in scope.
     Example: ::
@@ -10305,6 +10784,10 @@ Partial Type Signatures
 =======================
 
 .. ghc-flag:: -XPartialTypeSignatures
+    :shortdesc: Enable :ref:`partial type signatures <partial-type-signatures>`.
+    :type: dynamic
+    :reverse: -XNoPartialTypeSignatures
+    :category:
 
     :since: 7.10.1
 
@@ -10418,6 +10901,10 @@ Named Wildcards
 ~~~~~~~~~~~~~~~
 
 .. ghc-flag:: -XNamedWildCards
+    :shortdesc: Enable :ref:`named wildcards <named-wildcards>`.
+    :type: dynamic
+    :reverse: -XNoNamedWildCards
+    :category:
 
     :since: 7.10.1
 
@@ -10819,13 +11306,22 @@ Syntax
 ------
 
 .. ghc-flag:: -XTemplateHaskell
+    :shortdesc: Enable :ref:`Template Haskell <template-haskell>`.
+    :type: dynamic
+    :reverse: -XNoTemplateHaskell
+    :category:
 
-    :since: 6.0. Typed splices introduced in GHC 7.8.1.
     :implies: :ghc-flag:`-XTemplateHaskellQuotes`
+    :since: 6.0. Typed splices introduced in GHC 7.8.1.
 
     Enable Template Haskell's splice and quotation syntax.
 
 .. ghc-flag:: -XTemplateHaskellQuotes
+    :shortdesc: Enable quotation subset of
+        :ref:`Template Haskell <template-haskell>`.
+    :type: dynamic
+    :reverse: -XNoTemplateHaskellQuotes
+    :category:
 
     :since: 8.0.1
 
@@ -11333,6 +11829,12 @@ Template Haskell Quasi-quotation
 --------------------------------
 
 .. ghc-flag:: -XQuasiQuotes
+    :shortdesc: Enable :ref:`quasiquotation <th-quasiquotation>`.
+    :type: dynamic
+    :reverse: -XNoQuasiQuotes
+    :category:
+
+    :since: 6.10.1
 
     Enable Template Haskell Quasi-quotation syntax.
 
@@ -11510,6 +12012,12 @@ Arrow notation
 ==============
 
 .. ghc-flag:: -XArrows
+    :shortdesc: Enable :ref:`arrow notation <arrow-notation>` extension
+    :type: dynamic
+    :reverse: -XNoArrows
+    :category:
+
+    :since: 6.8.1
 
     Enable arrow notation.
 
@@ -11951,6 +12459,12 @@ Bang patterns
 -------------
 
 .. ghc-flag:: -XBangPatterns
+    :shortdesc: Enable :ref:`bang patterns <bang-patterns>`.
+    :type: dynamic
+    :reverse: -XNoBangPatterns
+    :category:
+
+    :since: 6.8.1
 
     Allow use of bang pattern syntax.
 
@@ -12047,6 +12561,10 @@ Strict-by-default data types
 ----------------------------
 
 .. ghc-flag:: -XStrictData
+    :shortdesc: Enable :ref:`default strict datatype fields <strict-data>`.
+    :type: dynamic
+    :reverse: -XNoStrictData
+    :category:
 
     :since: 8.0.1
 
@@ -12075,6 +12593,10 @@ Strict-by-default pattern bindings
 ----------------------------------
 
 .. ghc-flag:: -XStrict
+    :shortdesc: Make bindings in the current module strict by default.
+    :type: dynamic
+    :reverse: -XNoStrict
+    :category:
 
     :implies: :ghc-flag:`-XStrictData`
     :since: 8.0.1
@@ -12450,6 +12972,10 @@ Static pointers
    single: Static pointers
 
 .. ghc-flag:: -XStaticPointers
+    :shortdesc: Enable :ref:`static pointers <static-pointers>`.
+    :type: dynamic
+    :reverse: -XNoStaticPointers
+    :category:
 
     :since: 7.10.1
 
@@ -13493,6 +14019,12 @@ individual rule firing and :ghc-flag:`-ddump-rule-rewrites` also shows what the
 code looks like before and after the rewrite.
 
 .. ghc-flag:: -fenable-rewrite-rules
+    :shortdesc: Switch on all rewrite rules (including rules generated by
+        automatic specialisation of overloaded functions). Implied by
+        :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-enable-rewrite-rules
+    :category: optimization
 
     Allow the compiler to apply rewrite rules to the source program.
 
@@ -14321,6 +14853,10 @@ Role annotations
 ----------------
 
 .. ghc-flag:: -XRoleAnnotations
+    :shortdesc: Enable :ref:`role annotations <role-annotations>`.
+    :type: dynamic
+    :reverse: -XNoRoleAnnotations
+    :category:
 
     :since: 7.8.1
 
diff --git a/docs/users_guide/packages.rst b/docs/users_guide/packages.rst
index c728acbd08..e31abc06a6 100644
--- a/docs/users_guide/packages.rst
+++ b/docs/users_guide/packages.rst
@@ -128,6 +128,9 @@ command (see :ref:`package-management`):
 The GHC command line options that control packages are:
 
 .. ghc-flag:: -package ⟨pkg⟩
+    :shortdesc: Expose package ⟨pkg⟩
+    :type: dynamic/ ``:set``
+    :category:
 
     This option causes the installed package ⟨pkg⟩ to be exposed. The
     package ⟨pkg⟩ can be specified in full with its version number (e.g.
@@ -177,6 +180,9 @@ The GHC command line options that control packages are:
         $ ghc -o myprog Foo.hs Main.hs -package network
 
 .. ghc-flag:: -package-id ⟨unit-id⟩
+    :shortdesc: Expose package by id ⟨unit-id⟩
+    :type: dynamic/ ``:set``
+    :category:
 
     Exposes a package like :ghc-flag:`-package ⟨pkg⟩`, but the package is named
     by its unit ID (i.e. the value of ``id`` in its entry in the installed
@@ -187,6 +193,9 @@ The GHC command line options that control packages are:
     renaming described in :ref:`package-thinning-and-renaming`.
 
 .. ghc-flag:: -hide-all-packages
+    :shortdesc: Hide all packages by default
+    :type: dynamic
+    :category:
 
     Ignore the exposed flag on installed packages, and hide them all by
     default. If you use this flag, then any packages you require
@@ -199,6 +208,9 @@ The GHC command line options that control packages are:
     ``-hide-all-packages`` flag to GHC, for exactly this reason.
 
 .. ghc-flag:: -hide-package ⟨pkg⟩
+    :shortdesc: Hide package ⟨pkg⟩
+    :type: dynamic/ ``:set``
+    :category:
 
     This option does the opposite of :ghc-flag:`-package ⟨pkg⟩`: it causes the
     specified package to be hidden, which means that none of its modules
@@ -209,6 +221,9 @@ The GHC command line options that control packages are:
     exposed package.
 
 .. ghc-flag:: -ignore-package ⟨pkg⟩
+    :shortdesc: Ignore package ⟨pkg⟩
+    :type: dynamic/ ``:set``
+    :category:
 
     Causes the compiler to behave as if package ⟨pkg⟩, and any packages
     that depend on ⟨pkg⟩, are not installed at all.
@@ -220,11 +235,18 @@ The GHC command line options that control packages are:
     :ghc-flag:`-ignore-package ⟨pkg⟩` flag can be useful.
 
 .. ghc-flag:: -no-auto-link-packages
+    :shortdesc: Don't automatically link in the base and rts packages.
+    :type: dynamic
+    :category:
 
     By default, GHC will automatically link in the ``base`` and ``rts``
     packages. This flag disables that behaviour.
 
 .. ghc-flag:: -this-unit-id ⟨unit-id⟩
+    :shortdesc: Compile to be part of unit (i.e. package)
+        ⟨unit-id⟩
+    :type: dynamic
+    :category:
 
     Tells GHC that the module being compiled forms part of unit ID
     ⟨unit-id⟩; internally, these keys are used to determine type equality
@@ -234,6 +256,10 @@ The GHC command line options that control packages are:
     way in later releases.
 
 .. ghc-flag:: -trust ⟨pkg⟩
+    :shortdesc: Expose package ⟨pkg⟩ and set it to be trusted
+    :type: dynamic/ ``:set``
+    :category:
+    :noindex:
 
     This option causes the install package ⟨pkg⟩ to be both exposed and
     trusted by GHC. This command functions in a very similar way
@@ -242,6 +268,10 @@ The GHC command line options that control packages are:
     package database. (see :ref:`safe-haskell`).
 
 .. ghc-flag:: -distrust ⟨pkg⟩
+    :shortdesc: Expose package ⟨pkg⟩ and set it to be distrusted
+    :type: dynamic/ ``:set``
+    :category:
+    :noindex:
 
     This option causes the install package ⟨pkg⟩ to be both exposed and
     distrusted by GHC. This command functions in a very similar way to the
@@ -249,7 +279,11 @@ The GHC command line options that control packages are:
     packages to be distrusted by GHC, regardless of the contents of the package
     database. (see :ref:`safe-haskell`).
 
-.. ghc-flag:: -distrust-all
+.. ghc-flag:: -distrust-all-packages
+    :shortdesc: Distrust all packages by default
+    :type: dynamic/ ``:set``
+    :category:
+    :noindex:
 
     Ignore the trusted flag on installed packages, and distrust them by
     default. If you use this flag and Safe Haskell then any packages you
@@ -397,19 +431,31 @@ You can control GHC's package database stack using the following
 options:
 
 .. ghc-flag:: -package-db ⟨file⟩
+    :shortdesc: Add ⟨file⟩ to the package db stack.
+    :type: dynamic
+    :category:
 
     Add the package database ⟨file⟩ on top of the current stack.
 
 .. ghc-flag:: -no-global-package-db
+    :shortdesc: Remove the global package db from the stack.
+    :type: dynamic
+    :category:
 
     Remove the global package database from the package database stack.
 
 .. ghc-flag:: -no-user-package-db
+    :shortdesc: Remove the user's package db from the stack.
+    :type: dynamic
+    :category:
 
     Prevent loading of the user's local package database in the initial
     stack.
 
 .. ghc-flag:: -clear-package-db
+    :shortdesc: Clear the package db stack.
+    :type: dynamic
+    :category:
 
     Reset the current package database stack. This option removes every
     previously specified package database (including those read from the
@@ -417,6 +463,9 @@ options:
     stack.
 
 .. ghc-flag:: -global-package-db
+    :shortdesc: Add the global package db to the stack.
+    :type: dynamic
+    :category:
 
     Add the global package database on top of the current stack. This
     option can be used after :ghc-flag:`-no-global-package-db` to specify the
@@ -424,6 +473,9 @@ options:
     loaded.
 
 .. ghc-flag:: -user-package-db
+    :shortdesc: Add the user's package db to the stack.
+    :type: dynamic
+    :category:
 
     Add the user's package database on top of the current stack. This
     option can be used after :ghc-flag:`-no-user-package-db` to specify the
@@ -521,6 +573,9 @@ Note that for the ``package-db`` directive, if a relative path is given it
 must be relative to the location of the package environment file.
 
 .. ghc-flag:: -package-env ⟨file⟩|⟨name⟩
+    :shortdesc: Use the specified package environment.
+    :type: dynamic
+    :category:
 
     Use the package environment in ⟨file⟩, or in
     ``$HOME/.ghc/arch-os-version/environments/⟨name⟩``
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index 074b9499f5..92e308db15 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -18,46 +18,79 @@ following options allow you to change the external program used for a
 given compilation phase:
 
 .. ghc-flag:: -pgmL ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the literate pre-processor
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the literate pre-processor.
 
 .. ghc-flag:: -pgmP ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the C pre-processor (with ``-cpp`` only)
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the C pre-processor (with ``-cpp`` only).
 
 .. ghc-flag:: -pgmc ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the C compiler
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the C compiler.
 
 .. ghc-flag:: -pgmlo ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the LLVM optimiser
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the LLVM optimiser.
 
 .. ghc-flag:: -pgmlc ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the LLVM compiler
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the LLVM compiler.
 
 .. ghc-flag:: -pgms ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the splitter
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the splitter.
 
 .. ghc-flag:: -pgma ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the assembler
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the assembler.
 
 .. ghc-flag:: -pgml ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the linker
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the linker.
 
 .. ghc-flag:: -pgmdll ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the DLL generator
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the DLL generator.
 
 .. ghc-flag:: -pgmF ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the pre-processor (with ``-F`` only)
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the pre-processor (with ``-F`` only).
 
 .. ghc-flag:: -pgmwindres ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the program for embedding manifests on Windows.
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the program to use for embedding manifests on Windows.
     Normally this is the program ``windres``, which is supplied with a
@@ -65,10 +98,16 @@ given compilation phase:
     :ref:`options-linker`.
 
 .. ghc-flag:: -pgmlibtool ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the command for libtool (with ``-staticlib`` only).
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the libtool command (when using ``-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:
     :ref:`external-interpreter`).  Default: ``ghc-iserv-prof`` if
@@ -87,48 +126,81 @@ Options can be forced through to a particular compilation phase, using
 the following flags:
 
 .. ghc-flag:: -optL ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the literate pre-processor
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the literate pre-processor
 
 .. ghc-flag:: -optP ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to cpp (with ``-cpp`` only)
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to CPP (makes sense only if ``-cpp`` is also on).
 
 .. ghc-flag:: -optF ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the custom pre-processor
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the custom pre-processor (see
     :ref:`pre-processor`).
 
 .. ghc-flag:: -optc ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the C compiler
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the C compiler.
 
 .. ghc-flag:: -optlo ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the LLVM optimiser
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the LLVM optimiser.
 
 .. ghc-flag:: -optlc ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the LLVM compiler
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the LLVM compiler.
 
 .. ghc-flag:: -opta ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the assembler
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the assembler.
 
 .. ghc-flag:: -optl ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the linker
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the linker.
 
 .. ghc-flag:: -optdll ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the DLL generator
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the DLL generator.
 
 .. ghc-flag:: -optwindres ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to ``windres``.
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to ``windres`` when embedding manifests on Windows.
     See ``-fno-embed-manifest`` in :ref:`options-linker`.
 
 .. ghc-flag:: -opti ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the interpreter sub-process.
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the interpreter sub-process (see
     :ref:`external-interpreter`).  A common use for this is to pass
@@ -149,12 +221,23 @@ to GHC's runtime system you can enclose them in ``+RTS ... -RTS`` (see
 Options affecting the C pre-processor
 -------------------------------------
 
+.. ghc-flag:: -XCPP
+    :shortdesc: Enable the :ref:`C preprocessor <c-pre-processor>`.
+    :type: dynamic
+    :reverse: -XNoCPP
+    :category: language
+
+    :since: 6.8.1
+
 .. index::
    single: pre-processing: cpp
    single: C pre-processor options
    single: cpp, pre-processing with
 
 .. ghc-flag:: -cpp
+    :shortdesc: Run the C pre-processor on Haskell source files
+    :type: dynamic
+    :category: cpp
 
     The C pre-processor :command:`cpp` is run over your Haskell code only if
     the ``-cpp`` option -cpp option is given. Unless you are building a
@@ -162,6 +245,10 @@ Options affecting the C pre-processor
     really shouldn't need it.
 
 .. ghc-flag:: -D⟨symbol⟩[=⟨value⟩]
+    :shortdesc: Define a symbol in the C pre-processor
+    :type: dynamic
+    :reverse: -U⟨symbol⟩
+    :category: cpp
 
     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
@@ -174,10 +261,16 @@ Options affecting the C pre-processor
         this case use the ``-optc-Dfoo`` hack… (see :ref:`forcing-options-through`).
 
 .. ghc-flag:: -U⟨symbol⟩
+    :shortdesc: Undefine a symbol in the C pre-processor
+    :type: dynamic
+    :category: cpp
 
     Undefine macro ⟨symbol⟩ in the usual way.
 
 .. ghc-flag:: -I⟨dir⟩
+    :shortdesc: Add ⟨dir⟩ to the directory search list for ``#include`` files
+    :type: dynamic
+    :category: cpp
 
     Specify a directory in which to look for ``#include`` files, in the
     usual C way.
@@ -363,6 +456,10 @@ Options affecting a Haskell pre-processor
    single: pre-processor options
 
 .. ghc-flag:: -F
+    :shortdesc: Enable the use of a :ref:`pre-processor <pre-processor>`
+        (set with :ghc-flag:`-pgmF ⟨cmd⟩`)
+    :type: dynamic
+    :category: phases
 
     A custom pre-processor is run over your Haskell source file only if
     the ``-F`` option is given.
@@ -412,11 +509,19 @@ Options affecting code generation
 ---------------------------------
 
 .. ghc-flag:: -fasm
+    :shortdesc: Use the :ref:`native code generator <native-code-gen>`
+    :type: dynamic
+    :reverse: -fllvm
+    :category: codegen
 
     Use GHC's :ref:`native code generator <native-code-gen>` rather than
     compiling via LLVM. ``-fasm`` is the default.
 
 .. ghc-flag:: -fllvm
+    :shortdesc: Compile using the :ref:`LLVM code generator <llvm-code-gen>`
+    :type: dynamic
+    :reverse: -fasm
+    :category: codegen
 
     Compile via :ref:`LLVM <llvm-code-gen>` instead of using the native
     code generator. This will generally take slightly longer than the
@@ -426,11 +531,17 @@ Options affecting code generation
     in :envvar:`PATH`.
 
 .. ghc-flag:: -fno-code
+    :shortdesc: Omit code generation
+    :type: dynamic
+    :category: codegen
 
     Omit code generation (and all later phases) altogether. This is
     useful if you're only interested in type checking code.
 
 .. ghc-flag:: -fwrite-interface
+    :shortdesc: Always write interface files
+    :type: dynamic
+    :category: codegen
 
     Always write interface files. GHC will normally write interface
     files automatically, but this flag is useful with :ghc-flag:`-fno-code`,
@@ -439,12 +550,18 @@ Options affecting code generation
     compiling dependencies.
 
 .. ghc-flag:: -fobject-code
+    :shortdesc: Generate object code
+    :type: dynamic
+    :category: codegen
 
     Generate object code. This is the default outside of GHCi, and can
     be used with GHCi to cause object code to be generated in preference
     to bytecode.
 
 .. ghc-flag:: -fbyte-code
+    :shortdesc: Generate byte-code
+    :type: dynamic
+    :category: codegen
 
     Generate byte-code instead of object-code. This is the default in
     GHCi. Byte-code can currently only be used in the interactive
@@ -452,6 +569,9 @@ Options affecting code generation
     reversing the effect of :ghc-flag:`-fobject-code`.
 
 .. ghc-flag:: -fPIC
+    :shortdesc: Generate position-independent code (where available)
+    :type: dynamic
+    :category: codegen
 
     Generate position-independent code (code that can be put into shared
     libraries). This currently works on Linux x86 and x86-64. On
@@ -459,6 +579,9 @@ Options affecting code generation
     no-op on that platform.
 
 .. ghc-flag:: -dynamic
+    :shortdesc: Build dynamically-linked object files and executables
+    :type: dynamic
+    :category: codegen
     :noindex:
 
     When generating code, assume that entities imported from a different
@@ -472,6 +595,10 @@ Options affecting code generation
     shared libraries.
 
 .. ghc-flag:: -dynamic-too
+    :shortdesc: Build dynamic object files *as well as* static object files
+        during compilation
+    :type: dynamic
+    :category: codegen
 
     Generates both dynamic and static object files in a single run of
     GHC. This option is functionally equivalent to running GHC twice,
@@ -499,6 +626,9 @@ user-supplied, GHC-supplied, and system-supplied (``-lm`` math library,
 for example).
 
 .. ghc-flag:: -l ⟨lib⟩
+    :shortdesc: Link in library ⟨lib⟩
+    :type: dynamic
+    :category: linking
 
     Link in the ⟨lib⟩ library. On Unix systems, this will be in a file
     called :file:`lib{lib}.a` or :file:`lib{lib}.so` which resides somewhere on the
@@ -518,12 +648,18 @@ for example).
     and pass ``-no-hs-main``. See also :ref:`using-own-main`.
 
 .. ghc-flag:: -c
+    :shortdesc: Stop after generating object (``.o``) file
+    :type: mode
+    :category: linking
 
     Omits the link step. This option can be used with :ghc-flag:`--make` to
     avoid the automatic linking that takes place if the program contains
     a ``Main`` module.
 
 .. ghc-flag:: -package ⟨name⟩
+    :shortdesc: Expose package ⟨pkg⟩
+    :type: dynamic/ ``:set``
+    :category: linking
 
     If you are using a Haskell "package" (see :ref:`packages`), don't
     forget to add the relevant ``-package`` option when linking the
@@ -532,6 +668,10 @@ for example).
     result in several pages of link errors.
 
 .. ghc-flag:: -framework ⟨name⟩
+    :shortdesc: On Darwin/OS X/iOS only, link in the framework ⟨name⟩. This
+        option corresponds to the ``-framework`` option for Apple's Linker.
+    :type: dynamic
+    :category: linking
 
     On Darwin/OS X/iOS only, link in the framework ⟨name⟩. This option
     corresponds to the ``-framework`` option for Apple's Linker. Please
@@ -541,17 +681,31 @@ for example).
     for example, you'd use ``-framework Carbon``.
 
 .. ghc-flag:: -staticlib
+    :shortdesc: Generate a standalone static library (as opposed to an
+        executable). This is useful when cross compiling. The
+        library together with all its dependencies ends up in in a
+        single static library that can be linked against.
+    :type: dynamic
+    :category: linking
 
     Link all passed files into a static library suitable for linking.
     To control the name, use the :ghc-flag:`-o ⟨file⟩` option
     as usual. The default name is ``liba.a``.
 
 .. ghc-flag:: -L ⟨dir⟩
+    :shortdesc: Add ⟨dir⟩ to the list of directories searched for libraries
+    :type: dynamic
+    :category: linking
 
     Where to find user-supplied libraries… Prepend the directory ⟨dir⟩
     to the library directories path.
 
 .. ghc-flag:: -framework-path ⟨dir⟩
+    :shortdesc: On Darwin/OS X/iOS only, add ⟨dir⟩ to the list of directories
+        searched for frameworks. This option corresponds to the ``-F``
+        option for Apple's Linker.
+    :type: dynamic
+    :category: linking
 
     On Darwin/OS X/iOS only, prepend the directory ⟨dir⟩ to the
     framework directories path. This option corresponds to the ``-F``
@@ -559,6 +713,9 @@ for example).
     GHC).
 
 .. ghc-flag:: -split-objs
+    :shortdesc: Split objects (for libraries)
+    :type: dynamic
+    :category: linking
 
     Tell the linker to split the single object file that would normally
     be generated into multiple object files, one per top-level Haskell
@@ -571,6 +728,9 @@ for example).
     larger. We use this feature for building GHC's libraries.
 
 .. ghc-flag:: -split-sections
+    :shortdesc: Split sections for link-time dead-code stripping
+    :type: dynamic
+    :category: linking
 
     Place each generated function or data item into its own section in the
     output file if the target supports arbitrary sections. The name of the
@@ -583,11 +743,17 @@ for example).
     files are about 30% smaller than with :ghc-flag:`-split-objs`.
 
 .. ghc-flag:: -static
+    :shortdesc: Use static Haskell libraries
+    :type: dynamic
+    :category: linking
 
     Tell the linker to avoid shared Haskell libraries, if possible. This
     is the default.
 
 .. ghc-flag:: -dynamic
+    :shortdesc: Build dynamically-linked object files and executables
+    :type: dynamic
+    :category: linking
 
     This flag tells GHC to link against shared Haskell libraries. This
     flag only affects the selection of dependent libraries, not the form
@@ -598,6 +764,9 @@ for example).
     above).
 
 .. ghc-flag:: -shared
+    :shortdesc: Generate a shared library (as opposed to an executable)
+    :type: dynamic
+    :category: linking
 
     Instead of creating an executable, GHC produces a shared object with
     this linker flag. Depending on the operating system target, this
@@ -618,12 +787,18 @@ for example).
     when linked against this package. See shared object name mangling.
 
 .. ghc-flag:: -dynload
+    :shortdesc: Selects one of a number of modes for finding shared libraries at runtime.
+    :type: dynamic
+    :category: linking
 
     This flag selects one of a number of modes for finding shared
     libraries at runtime. See :ref:`finding-shared-libs` for a
     description of each mode.
 
 .. ghc-flag:: -main-is ⟨thing⟩
+    :shortdesc: Set main module and function
+    :type: dynamic
+    :category: linking
 
     .. index::
        single: specifying your own main function
@@ -655,6 +830,9 @@ for example).
     :ghc-flag:`-fforce-recomp` flag.
 
 .. ghc-flag:: -no-hs-main
+    :shortdesc: Don't assume this program contains ``main``
+    :type: dynamic
+    :category: linking
 
     .. index::
        single: linking Haskell libraries with foreign code
@@ -684,6 +862,9 @@ for example).
     :ghc-flag:`-with-rtsopts=⟨opts⟩` when using your own ``main``.
 
 .. ghc-flag:: -debug
+    :shortdesc: Use the debugging runtime
+    :type: dynamic
+    :category: linking
 
     Link the program with a debugging version of the runtime system. The
     debugging runtime turns on numerous assertions and sanity checks,
@@ -691,6 +872,9 @@ for example).
     (run the program with ``+RTS -?`` to see a list).
 
 .. ghc-flag:: -threaded
+    :shortdesc: Use the threaded runtime
+    :type: dynamic
+    :category: linking
 
     Link the program with the "threaded" version of the runtime system.
     The threaded runtime system is so-called because it manages multiple
@@ -716,6 +900,9 @@ for example).
        :ref:`ffi-threads`.
 
 .. ghc-flag:: -eventlog
+    :shortdesc: Enable runtime event tracing
+    :type: dynamic
+    :category: linking
 
     Link the program with the "eventlog" version of the runtime system.
     A program linked in this way can generate a runtime trace of events
@@ -727,6 +914,13 @@ for example).
     :ghc-flag:`-debug`.
 
 .. ghc-flag:: -rtsopts[=⟨none|some|all⟩]
+    :shortdesc: Control whether the RTS behaviour can be tweaked via command-line
+        flags and the ``GHCRTS`` environment variable. Using ``none``
+        means no RTS flags can be given; ``some`` means only a minimum
+        of safe options can be given (the default), and ``all`` (or no
+        argument at all) means that all RTS flags are permitted.
+    :type: dynamic
+    :category: linking
 
     :default: all
 
@@ -770,6 +964,9 @@ for example).
     see :ref:`using-own-main` for details.
 
 .. ghc-flag:: -with-rtsopts=⟨opts⟩
+    :shortdesc: Set the default RTS options to ⟨opts⟩.
+    :type: dynamic
+    :category: linking
 
     This option allows you to set the default RTS options at link-time.
     For example, ``-with-rtsopts="-H128m"`` sets the default heap size
@@ -783,6 +980,10 @@ for example).
     ``-no-hs-main``; see :ref:`using-own-main` for details.
 
 .. ghc-flag:: -no-rtsopts-suggestions
+    :shortdesc: Don't print RTS suggestions about linking with
+        :ghc-flag:`-rtsopts[=⟨none|some|all⟩]`.
+    :type: dynamic
+    :category: linking
 
     This option disables RTS suggestions about linking with
     :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` when they are not available. These
@@ -792,6 +993,9 @@ for example).
     build with either ``-rtsopts`` or ``-no-rtsopts-suggestions``.
 
 .. ghc-flag:: -fno-gen-manifest
+    :shortdesc: Do not generate a manifest file (Windows only)
+    :type: dynamic
+    :category: linking
 
     On Windows, GHC normally generates a manifestmanifest file when
     linking a binary. The manifest is placed in the file
@@ -823,6 +1027,9 @@ for example).
     below.
 
 .. ghc-flag:: -fno-embed-manifest
+    :shortdesc: Do not embed the manifest in the executable (Windows only)
+    :type: dynamic
+    :category: linking
 
     .. index::
        single: windres
@@ -838,6 +1045,9 @@ for example).
     :ghc-flag:`-optwindres ⟨option⟩` (:ref:`forcing-options-through`).
 
 .. ghc-flag:: -fno-shared-implib
+    :shortdesc: Don't generate an import library for a DLL (Windows only)
+    :type: dynamic
+    :category: linking
 
     DLLs on Windows are typically linked to by linking to a
     corresponding ``.lib`` or ``.dll.a`` — the so-called import library.
@@ -853,6 +1063,13 @@ for example).
     library entirely.
 
 .. ghc-flag:: -dylib-install-name ⟨path⟩
+    :shortdesc: Set the install name (via ``-install_name`` passed to Apple's
+        linker), specifying the full install path of the library file.
+        Any libraries or executables that link with it later will pick
+        up that path as their runtime search location for it.
+        (Darwin/OS X only)
+    :type: dynamic
+    :category: linking
 
     On Darwin/OS X, dynamic libraries are stamped at build time with an
     "install name", which is the ultimate install path of the library
@@ -864,6 +1081,13 @@ for example).
     on other platforms.
 
 .. ghc-flag:: -rdynamic
+    :shortdesc: This instructs the linker to add all symbols, not only used
+        ones, to the dynamic symbol table. Currently Linux and
+        Windows/MinGW32 only. This is equivalent to using
+        ``-optl -rdynamic`` on Linux, and ``-optl -export-all-symbols``
+        on Windows.
+    :type: dynamic
+    :category: linking
 
     This instructs the linker to add all symbols, not only used ones, to
     the dynamic symbol table. Currently Linux and Windows/MinGW32 only.
@@ -871,6 +1095,11 @@ for example).
     ``-optl -export-all-symbols`` on Windows.
 
 .. ghc-flag:: -fwhole-archive-hs-libs
+    :shortdesc: When linking a binary executable, this inserts the flag
+        ``-Wl,--whole-archive`` before any ``-l`` flags for Haskell
+        libraries, and ``-Wl,--no-whole-archive`` afterwards
+    :type: dynamic
+    :category: linking
 
     When linking a binary executable, this inserts the flag
     ``-Wl,--whole-archive`` before any ``-l`` flags for Haskell
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index 3f2e592944..ded667581f 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -309,6 +309,9 @@ Compiler options for profiling
    single: options; for profiling
 
 .. ghc-flag:: -prof
+    :shortdesc: Turn on profiling
+    :type: dynamic
+    :category:
 
     To make use of the profiling system *all* modules must be compiled
     and linked with the :ghc-flag:`-prof` option. Any ``SCC`` annotations you've
@@ -322,12 +325,20 @@ There are a few other profiling-related compilation options. Use them
 for all modules in a program.
 
 .. ghc-flag:: -fprof-auto
+    :shortdesc: Auto-add ``SCC``\\ s to all bindings not marked INLINE
+    :type: dynamic
+    :reverse: -fno-prof-auto
+    :category:
 
     *All* bindings not marked INLINE, whether exported or not, top level
     or nested, will be given automatic ``SCC`` annotations. Functions
     marked INLINE must be given a cost centre manually.
 
 .. ghc-flag:: -fprof-auto-top
+    :shortdesc: Auto-add ``SCC``\\ s to all top-level bindings not marked INLINE
+    :type: dynamic
+    :reverse: -fno-prof-auto
+    :category:
 
     .. index::
        single: cost centres; automatically inserting
@@ -337,6 +348,10 @@ for all modules in a program.
     function, you have to add it manually.
 
 .. ghc-flag:: -fprof-auto-exported
+    :shortdesc: Auto-add ``SCC``\\ s to all exported bindings not marked INLINE
+    :type: dynamic
+    :reverse: -fno-prof-auto
+    :category:
 
     .. index::
        single: cost centres; automatically inserting
@@ -346,6 +361,10 @@ for all modules in a program.
     function, you have to add it manually.
 
 .. ghc-flag:: -fprof-auto-calls
+    :shortdesc: Auto-add ``SCC``\\ s to all call sites
+    :type: dynamic
+    :reverse: -fno-prof-auto-calls
+    :category:
 
     Adds an automatic ``SCC`` annotation to all *call sites*. This is
     particularly useful when using profiling for the purposes of
@@ -354,21 +373,38 @@ for all modules in a program.
     details.
 
 .. ghc-flag:: -fprof-cafs
+    :shortdesc: Auto-add ``SCC``\\ s to all CAFs
+    :type: dynamic
+    :reverse: -fno-prof-cafs
+    :category:
 
     The costs of all CAFs in a module are usually attributed to one
     "big" CAF cost-centre. With this option, all CAFs get their own
     cost-centre. An “if all else fails” option…
 
 .. ghc-flag:: -fno-prof-auto
+    :shortdesc: Disables any previous :ghc-flag:`-fprof-auto`,
+        :ghc-flag:`-fprof-auto-top`, or :ghc-flag:`-fprof-auto-exported` options.
+    :type: dynamic
+    :reverse: -fprof-auto
+    :category:
 
     Disables any previous :ghc-flag:`-fprof-auto`, :ghc-flag:`-fprof-auto-top`, or
     :ghc-flag:`-fprof-auto-exported` options.
 
 .. ghc-flag:: -fno-prof-cafs
+    :shortdesc: Disables any previous :ghc-flag:`-fprof-cafs` option.
+    :type: dynamic
+    :reverse: -fprof-cafs
+    :category:
 
     Disables any previous :ghc-flag:`-fprof-cafs` option.
 
 .. ghc-flag:: -fno-prof-count-entries
+    :shortdesc: Do not collect entry counts
+    :type: dynamic
+    :reverse: -fprof-count-entries
+    :category:
 
     Tells GHC not to collect information about how often functions are
     entered at runtime (the "entries" column of the time profile), for
@@ -1345,6 +1381,9 @@ Options for instrumenting code for coverage
 .. program:: hpc
 
 .. ghc-flag:: -fhpc
+    :shortdesc: Turn on Haskell program coverage instrumentation
+    :type: dynamic
+    :category: coverage
 
     Enable code coverage for the current module or modules being
     compiled.
@@ -1564,8 +1603,11 @@ Using “ticky-ticky” profiling (for implementors)
    single: ticky-ticky profiling
 
 .. ghc-flag:: -ticky
+    :shortdesc: :ref:`Turn on ticky-ticky profiling <ticky-ticky>`
+    :type: dynamic
+    :category:
 
-   Enable ticky-ticky profiling.
+    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.
diff --git a/docs/users_guide/safe_haskell.rst b/docs/users_guide/safe_haskell.rst
index e1238a8e2c..7be442e036 100644
--- a/docs/users_guide/safe_haskell.rst
+++ b/docs/users_guide/safe_haskell.rst
@@ -562,10 +562,10 @@ Trustworthy Requirements
 .. index::
    single: trustworthy
 
-Module authors using the :ghc-flag:`-XTrustworthy` language extension for a module ``M``
-should ensure that ``M``\'s public API (the symbols exposed by its export list)
-can't be used in an unsafe manner. This mean that symbols exported should
-respect type safety and referential transparency.
+Module authors using the :ghc-flag:`-XTrustworthy` language extension for a
+module ``M`` should ensure that ``M``\'s public API (the symbols exposed by its
+export list) can't be used in an unsafe manner. This mean that symbols exported
+should respect type safety and referential transparency.
 
 .. _safe-package-trust:
 
@@ -580,19 +580,30 @@ Several new options are available at the GHC command-line to specify the
 trust property of packages:
 
 .. ghc-flag:: -trust ⟨pkg⟩
+    :shortdesc: Expose package ⟨pkg⟩ and set it to be trusted. See
+        :ref:`safe-haskell`.
+    :type: dynamic/ ``:set``
+    :category:
 
-   Exposes package ⟨pkg⟩ if it was hidden and considers it a
-   trusted package regardless of the package database.
+    Exposes package ⟨pkg⟩ if it was hidden and considers it a
+    trusted package regardless of the package database.
 
 .. ghc-flag:: -distrust ⟨pkg⟩
+    :shortdesc: Expose package ⟨pkg⟩ and set it to be distrusted. See
+        :ref:`safe-haskell`.
+    :type: dynamic/ ``:set``
+    :category:
 
-   Exposes package ⟨pkg⟩ if it was hidden and considers it
-   an untrusted package regardless of the package database.
+    Exposes package ⟨pkg⟩ if it was hidden and considers it
+    an untrusted package regardless of the package database.
 
 .. ghc-flag:: -distrust-all-packages
+    :shortdesc: Distrust all packages by default. See :ref:`safe-haskell`.
+    :type: dynamic/ ``:set``
+    :category:
 
-   Considers all packages distrusted unless they are
-   explicitly set to be trusted by subsequent command-line options.
+    Considers all packages distrusted unless they are
+    explicitly set to be trusted by subsequent command-line options.
 
 To set a package's trust property in the package database please refer
 to :ref:`packages`.
@@ -647,6 +658,9 @@ Safe Haskell Flag Summary
 In summary, Safe Haskell consists of the following three language flags:
 
 .. ghc-flag:: -XSafe
+    :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Safe mode.
+    :type: dynamic
+    :category:
 
     :since: 7.2.1
 
@@ -662,6 +676,9 @@ In summary, Safe Haskell consists of the following three language flags:
     - *Imported Modules* — All forced to be safe imports, all must be trusted.
 
 .. ghc-flag:: -XTrustworthy
+    :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Trustworthy mode.
+    :type: dynamic
+    :category:
 
     :since: 7.2.1
 
@@ -683,6 +700,9 @@ In summary, Safe Haskell consists of the following three language flags:
       trusted.
 
 .. ghc-flag:: -XUnsafe
+    :shortdesc: Enable :ref:`Safe Haskell <safe-haskell>` Unsafe mode.
+    :type: dynamic
+    :category:
 
     :since: 7.4.1
 
@@ -699,6 +719,11 @@ In summary, Safe Haskell consists of the following three language flags:
 And one general flag:
 
 .. ghc-flag:: -fpackage-trust
+    :shortdesc: Enable :ref:`Safe Haskell <safe-haskell>` trusted package
+        requirement for trustworthy modules.
+    :type: dynamic
+    :category:
+
     When enabled, turn on an extra check for a trustworthy module ``M``,
     requiring the package that ``M`` resides in be considered trusted, for ``M``
     to be considered trusted.
@@ -706,18 +731,33 @@ And one general flag:
 And three warning flags:
 
 .. ghc-flag:: -Wunsafe
+    :shortdesc: warn if the module being compiled is regarded to be unsafe.
+        See :ref:`safe-haskell`
+    :type: dynamic
+    :reverse: -Wno-unsafe
+    :category:
 
     Issue a warning if the module being compiled is regarded to be
     unsafe. Should be used to check the safety type of modules when
     using safe inference.
 
 .. ghc-flag:: -Wsafe
+    :shortdesc: warn if the module being compiled is regarded to be safe.
+    :type: dynamic
+    :reverse: -Wno-safe
+    :category:
 
     Issue a warning if the module being compiled is regarded to be safe.
     Should be used to check the safety type of modules when using safe
     inference.
 
 .. ghc-flag:: -Wtrustworthy-safe
+    :shortdesc: warn if the module being compiled is marked as
+        :ghc-flag:`-XTrustworthy` but it could instead be marked as
+        :ghc-flag:`-XSafe`, a more informative bound.
+    :type: dynamic
+    :reverse: -Wno-safe
+    :category:
 
     Issue a warning if the module being compiled is marked as
     -XTrustworthy but it could instead be marked as
diff --git a/docs/users_guide/separate_compilation.rst b/docs/users_guide/separate_compilation.rst
index 85c82540e4..29ee7bb1aa 100644
--- a/docs/users_guide/separate_compilation.rst
+++ b/docs/users_guide/separate_compilation.rst
@@ -158,6 +158,9 @@ current directory). The following options can be used to add to or change the
 contents of the search path:
 
 .. ghc-flag:: -i⟨dir⟩[:⟨dir⟩]*
+    :shortdesc: add ⟨dir⟩, ⟨dir2⟩, etc. to import path
+    :type: dynamic/ ``:set``
+    :category: search-path
 
     .. index::
        single: search path; source code
@@ -166,6 +169,10 @@ contents of the search path:
     the search path.
 
 .. ghc-flag:: -i
+    :shortdesc: Empty the import directory list
+    :type: dynamic/ ``:set``
+    :category: search-path
+
     resets the search path back to nothing.
 
 This isn't the whole story: GHC also looks for modules in pre-compiled
@@ -182,6 +189,9 @@ Redirecting the compilation output(s)
    single: redirecting compilation output
 
 .. ghc-flag:: -o ⟨file⟩
+    :shortdesc: set output filename
+    :type: dynamic
+    :category:
 
     GHC's compiled output normally goes into a ``.hc``, ``.o``, etc.,
     file, depending on the last-run compilation phase. The option
@@ -231,6 +241,9 @@ Redirecting the compilation output(s)
     will produce ``Prog`` (or ``Prog.exe`` if you are on Windows).
 
 .. ghc-flag:: -odir ⟨dir⟩
+    :shortdesc: set directory for object files
+    :type: dynamic
+    :category:
 
     Redirects object files to directory ⟨dir⟩. For example:
 
@@ -248,6 +261,9 @@ Redirecting the compilation output(s)
     ``parse/Bar.hi``, and ``gurgle/Bumble.hi``.
 
 .. ghc-flag:: -ohi ⟨file⟩
+    :shortdesc: set the filename in which to put the interface
+    :type: dynamic
+    :category:
 
     The interface output may be directed to another file
     ``bar2/Wurble.iface`` with the option ``-ohi bar2/Wurble.iface``
@@ -265,11 +281,17 @@ Redirecting the compilation output(s)
     for example.
 
 .. ghc-flag:: -hidir ⟨dir⟩
+    :shortdesc: set directory for interface files
+    :type: dynamic
+    :category:
 
     Redirects all generated interface files into ⟨dir⟩, instead of the
     default.
 
 .. ghc-flag:: -stubdir ⟨dir⟩
+    :shortdesc: redirect FFI stub files
+    :type: dynamic
+    :category:
 
     Redirects all generated FFI stub files into ⟨dir⟩. Stub files are
     generated when the Haskell source contains a ``foreign export`` or
@@ -279,31 +301,40 @@ Redirecting the compilation output(s)
     hierarchical modules.
 
 .. ghc-flag:: -dumpdir ⟨dir⟩
+    :shortdesc: redirect dump files
+    :type: dynamic
+    :category:
 
     Redirects all dump files into ⟨dir⟩. Dump files are generated when
     ``-ddump-to-file`` is used with other ``-ddump-*`` flags.
 
 .. ghc-flag:: -outputdir ⟨dir⟩
+    :shortdesc: set output directory
+    :type: dynamic
+    :category:
 
     The ``-outputdir`` option is shorthand for the combination of
     :ghc-flag:`-odir ⟨dir⟩`, :ghc-flag:`-hidir ⟨dir⟩`, :ghc-flag:`-stubdir
     ⟨dir⟩` and :ghc-flag:`-dumpdir ⟨dir⟩`.
 
 .. ghc-flag:: -osuf ⟨suffix⟩
-              -hisuf ⟨suffix⟩
-              -hcsuf ⟨suffix⟩
+    :shortdesc: set the output file suffix
+    :type: dynamic
+    :category:
 
     The ``-osuf`` ⟨suffix⟩ will change the ``.o`` file suffix for object
     files to whatever you specify. We use this when compiling libraries,
     so that objects for the profiling versions of the libraries don't
     clobber the normal ones.
 
+.. ghc-flag:: -hisuf ⟨suffix⟩
+    :shortdesc: set the suffix to use for interface files
+    :type: dynamic
+    :category:
+
     Similarly, the ``-hisuf`` ⟨suffix⟩ will change the ``.hi`` file
     suffix for non-system interface files (see :ref:`hi-options`).
 
-    Finally, the option ``-hcsuf`` ⟨suffix⟩ will change the ``.hc`` file
-    suffix for compiler-generated intermediate C files.
-
     The ``-hisuf``/``-osuf`` game is particularly useful if you want to
     compile a program both with and without profiling, in the same
     directory. You can say:
@@ -320,6 +351,15 @@ Redirecting the compilation output(s)
 
     to get the profiled version.
 
+
+.. ghc-flag:: -hcsuf ⟨suffix⟩
+    :shortdesc: set the suffix to use for intermediate C files
+    :type: dynamic
+    :category:
+
+    Finally, the option ``-hcsuf`` ⟨suffix⟩ will change the ``.hc`` file
+    suffix for compiler-generated intermediate C files.
+
 .. _keeping-intermediates:
 
 Keeping Intermediate Files
@@ -337,21 +377,32 @@ compilation:
 
 .. ghc-flag:: -keep-hc-file
               -keep-hc-files
+    :shortdesc: Retain intermediate ``.hc`` files.
+    :type: dynamic
+    :category: keep-intermediates
 
     Keep intermediate ``.hc`` files when doing ``.hs``-to-``.o``
     compilations via :ref:`C <c-code-gen>` (Note: ``.hc`` files are only
     generated by :ref:`unregisterised <unreg>` compilers).
 
 .. ghc-flag:: -keep-hi-files
+    :shortdesc: Retain intermediate ``.hi`` files (the default).
+    :type: dynamic
+    :reverse: -no-keep-hi-files
+    :category: keep-intermediates
 
     .. index::
        single: temporary files; keeping
 
-   Keep intermediate ``.hi`` files. This is the default. You may use
-   ``-no-keep-hi-files`` if you are not interested in the ``.hi`` files.
+    Keep intermediate ``.hi`` files. This is the default. You may use
+    ``-no-keep-hi-files`` if you are not interested in the ``.hi`` files.
 
 .. ghc-flag:: -keep-llvm-file
               -keep-llvm-files
+    :shortdesc: Retain intermediate LLVM ``.ll`` files.
+        Implies :ghc-flag:`-fllvm`.
+    :type: dynamic
+    :category: keep-intermediates
 
     :implies: :ghc-flag:`-fllvm`
 
@@ -361,19 +412,29 @@ compilation:
     to use :ghc-flag:`-fllvm` to force them to be produced).
 
 .. ghc-flag:: -keep-o-files
+    :shortdesc: Retain intermediate ``.o`` files (the default).
+    :type: dynamic
+    :reverse: -no-keep-o-files
+    :category: keep-intermediates
 
     .. index::
        single: temporary files; keeping
 
-   Keep intermediate ``.o`` files. This is the default. You may use
-   ``-no-keep-o-files`` if you are not interested in the ``.o`` files.
+    Keep intermediate ``.o`` files. This is the default. You may use
+    ``-no-keep-o-files`` if you are not interested in the ``.o`` files.
 
 .. ghc-flag:: -keep-s-file
               -keep-s-files
+    :shortdesc: Retain intermediate ``.s`` files.
+    :type: dynamic
+    :category: keep-intermediates
 
     Keep intermediate ``.s`` files.
 
 .. ghc-flag:: -keep-tmp-files
+    :shortdesc: Retain all intermediate temporary files.
+    :type: dynamic
+    :category: keep-intermediates
 
     .. index::
        single: temporary files; keeping
@@ -392,6 +453,9 @@ Redirecting temporary files
    single: temporary files; redirecting
 
 .. ghc-flag:: -tmpdir ⟨dir⟩
+    :shortdesc: set the directory for temporary files
+    :type: dynamic
+    :category: temp-files
 
     If you have trouble because of running out of space in ``/tmp`` (or
     wherever your installation thinks temporary files should go), you
@@ -415,10 +479,16 @@ Other options related to interface files
    single: interface files, options
 
 .. ghc-flag:: -ddump-hi
+    :shortdesc: Dump the new interface to stdout
+    :type: dynamic
+    :category: interface-files
 
     Dumps the new interface to standard output.
 
 .. ghc-flag:: -ddump-hi-diffs
+    :shortdesc: Show the differences vs. the old interface
+    :type: dynamic
+    :category: interface-files
 
     The compiler does not overwrite an existing ``.hi`` interface file
     if the new one is the same as the old one; this is friendly to
@@ -427,6 +497,9 @@ Other options related to interface files
     differences between the old and new ``.hi`` files.
 
 .. ghc-flag:: -ddump-minimal-imports
+    :shortdesc: Dump a minimal set of imports
+    :type: dynamic
+    :category: interface-files
 
     Dump to the file :file:`{M}.imports` (where ⟨M⟩ is the name of the module
     being compiled) a "minimal" set of import declarations. The
@@ -441,6 +514,9 @@ Other options related to interface files
     is intended to reduce the labour.
 
 .. ghc-flag:: --show-iface ⟨file⟩
+    :shortdesc: See :ref:`modes`.
+    :type: mode
+    :category: interface-files
 
     where ⟨file⟩ is the name of an interface file, dumps the contents of
     that interface in a human-readable format. See :ref:`modes`.
@@ -454,6 +530,12 @@ The recompilation checker
    single: recompilation checker
 
 .. ghc-flag:: -fforce-recomp
+    :shortdesc: Turn off recompilation checking. This is implied by any
+        ``-ddump-X`` option when compiling a single file
+        (i.e. when using :ghc-flag:`-c`).
+    :type: dynamic
+    :reverse: -fno-force-recomp
+    :category: recompilation
 
     Turn off recompilation checking (which is on by default).
     Recompilation checking normally stops compilation early, leaving an
@@ -1172,6 +1254,9 @@ which you may find useful. The options which affect dependency
 generation are:
 
 .. ghc-flag:: -ddump-mod-cycles
+    :shortdesc: Dump module cycles
+    :type: dynamic
+    :category:
 
     Display a list of the cycles in the module graph. This is useful
     when trying to eliminate such cycles.
@@ -1184,6 +1269,9 @@ generation are:
     ``-v3`` and ``-v4``; see :ref:`options-help`.)
 
 .. ghc-flag:: -dep-makefile ⟨file⟩
+    :shortdesc: Use ⟨file⟩ as the makefile
+    :type: dynamic
+    :category:
 
     Use ⟨file⟩ as the makefile, rather than ``makefile`` or
     ``Makefile``. If ⟨file⟩ doesn't exist, ``mkdependHS`` creates it. We
@@ -1192,6 +1280,10 @@ generation are:
     ``Makefile``.
 
 .. ghc-flag:: -dep-suffix ⟨suffix⟩
+    :shortdesc: Make dependencies that declare that files with suffix
+        ``.⟨suf⟩⟨osuf⟩`` depend on interface files with suffix ``.⟨suf⟩hi``
+    :type: dynamic
+    :category:
 
     Make dependencies that declare that files with suffix
     ``.⟨suf⟩⟨osuf⟩`` depend on interface files with suffix
@@ -1203,11 +1295,18 @@ generation are:
     then pass ``-dep-suffix ''``.
 
 .. ghc-flag:: --exclude-module=⟨file⟩
+    :shortdesc: Regard ``⟨file⟩`` as "stable"; i.e., exclude it from having
+        dependencies on it.
+    :type: dynamic
+    :category:
 
     Regard ``⟨file⟩`` as "stable"; i.e., exclude it from having
     dependencies on it.
 
 .. ghc-flag:: -include-pkg-deps
+    :shortdesc: Regard modules imported from packages as unstable
+    :type: dynamic
+    :category:
 
     Regard modules imported from packages as unstable, i.e., generate
     dependencies on any imported package modules (including ``Prelude``,
diff --git a/docs/users_guide/using-concurrent.rst b/docs/users_guide/using-concurrent.rst
index 32e24256c3..e8640dcbc3 100644
--- a/docs/users_guide/using-concurrent.rst
+++ b/docs/users_guide/using-concurrent.rst
@@ -76,6 +76,10 @@ the :ghc-flag:`-threaded` option (see :ref:`options-linker`). Additionally, the
 following compiler options affect parallelism:
 
 .. ghc-flag:: -feager-blackholing
+    :shortdesc: Turn on :ref:`eager blackholing <parallel-compile-options>`
+    :type: dynamic
+    :category:
+    :noindex:
 
     Blackholing is the act of marking a thunk (lazy computation) as
     being under evaluation. It is useful for three reasons: firstly it
diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst
index 15916b2690..763c778872 100644
--- a/docs/users_guide/using-optimisation.rst
+++ b/docs/users_guide/using-optimisation.rst
@@ -50,6 +50,10 @@ compile quickly; I'm not over-bothered about compiled-code quality.”
 So, for example, ``ghc -c Foo.hs``
 
 .. ghc-flag:: -O0
+    :shortdesc: Disable optimisations (default)
+    :type: dynamic
+    :reverse: -O
+    :category: optimization-levels
 
     Means "turn off all optimisation", reverting to the same settings as
     if no ``-O`` options had been specified. Saying ``-O0`` can be
@@ -58,6 +62,10 @@ So, for example, ``ghc -c Foo.hs``
 
 .. ghc-flag:: -O
               -O1
+    :shortdesc: Enable level 1 optimisations
+    :type: dynamic
+    :reverse: -O0
+    :category: optimization-levels
 
     .. index::
        single: optimise; normally
@@ -66,6 +74,10 @@ So, for example, ``ghc -c Foo.hs``
     it." Thus, for example: ``ghc -c -O Main.lhs``
 
 .. ghc-flag:: -O2
+    :shortdesc: Enable level 2 optimisations
+    :type: dynamic
+    :reverse: -O0
+    :category: optimization-levels
 
     .. index::
        single: optimise; aggressively
@@ -78,6 +90,11 @@ So, for example, ``ghc -c Foo.hs``
     on or off individually.
 
 .. ghc-flag:: -Odph
+    :shortdesc: Enable level 2 optimisations, set
+        ``-fmax-simplifier-iterations=20``
+        and ``-fsimplifier-phases=3``.
+    :type: dynamic
+    :category: optimization-levels
 
     .. index::
        single: optimise; DPH
@@ -109,6 +126,10 @@ need to set any of them explicitly. A flag ``-fwombat`` can be negated
 by saying ``-fno-wombat``.
 
 .. ghc-flag:: -fcase-merge
+    :shortdesc: Enable case-merging. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-case-merge
+    :category:
 
     :default: on
 
@@ -129,6 +150,10 @@ by saying ``-fno-wombat``.
              Green -> e2
 
 .. ghc-flag:: -fcase-folding
+    :shortdesc: Enable constant folding in case expressions. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-case-folding
+    :category:
 
     :default: on
 
@@ -148,12 +173,20 @@ by saying ``-fno-wombat``.
              _    -> let v = x `minusWord#` 10## in e3
 
 .. ghc-flag:: -fcall-arity
+    :shortdesc: Enable call-arity optimisation. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-call-arity
+    :category:
 
     :default: on
 
     Enable call-arity analysis.
 
 .. ghc-flag:: -fcmm-elim-common-blocks
+    :shortdesc: Enable Cmm common block elimination. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-cmm-elim-common-blocks
+    :category:
 
     :default: on
 
@@ -162,6 +195,10 @@ by saying ``-fno-wombat``.
     Cmm blocks and eliminate the duplicates.
 
 .. ghc-flag:: -fcmm-sink
+    :shortdesc: Enable Cmm sinking. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-cmm-sink
+    :category:
 
     :default: on
 
@@ -172,12 +209,20 @@ by saying ``-fno-wombat``.
     literals or registers.
 
 .. ghc-flag:: -fcpr-anal
+    :shortdesc: Turn on CPR analysis in the demand analyser. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-cpr-anal
+    :category:
 
     :default: on
 
     Turn on CPR analysis in the demand analyser.
 
 .. ghc-flag:: -fcse
+    :shortdesc: Enable common sub-expression elimination. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-cse
+    :category:
 
     :default: on
 
@@ -186,6 +231,11 @@ by saying ``-fno-wombat``.
     ``unsafePerformIO`` expressions that you don't want commoned-up.
 
 .. ghc-flag:: -fstg-cse
+    :shortdesc: Enable common sub-expression elimination on the STG
+        intermediate language
+    :type: dynamic
+    :reverse: -fno-stg-cse
+    :category:
 
     :default: on
 
@@ -194,6 +244,10 @@ by saying ``-fno-wombat``.
     that differ in their types, but not their represetation.
 
 .. ghc-flag:: -fdicts-cheap
+    :shortdesc: Make dictionary-valued expressions seem cheap to the optimiser.
+    :type: dynamic
+    :reverse: -fno-dicts-cheap
+    :category:
 
     :default: off
 
@@ -201,18 +255,31 @@ by saying ``-fno-wombat``.
     seem cheap to the optimiser.
 
 .. ghc-flag:: -fdicts-strict
+    :shortdesc: Make dictionaries strict
+    :type: dynamic
+    :reverse: -fno-dicts-strict
+    :category:
 
     :default: off
 
     Make dictionaries strict.
 
 .. ghc-flag:: -fdmd-tx-dict-sel
+    :shortdesc: Use a special demand transformer for dictionary selectors.
+        Always enabled by default.
+    :type: dynamic
+    :reverse: -fno-dmd-tx-dict-sel
+    :category:
 
     :default: on
 
     Use a special demand transformer for dictionary selectors.
 
 .. ghc-flag:: -fdo-eta-reduction
+    :shortdesc: Enable eta-reduction. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-do-eta-reduction
+    :category:
 
     :default: on
 
@@ -220,12 +287,19 @@ by saying ``-fno-wombat``.
     lambdas.
 
 .. ghc-flag:: -fdo-lambda-eta-expansion
+    :shortdesc: Enable lambda eta-expansion. Always enabled by default.
+    :type: dynamic
+    :reverse: -fno-do-lambda-eta-expansion
+    :category:
 
     :default: on
 
     Eta-expand let-bindings to increase their arity.
 
 .. ghc-flag:: -feager-blackholing
+    :shortdesc: Turn on :ref:`eager blackholing <parallel-compile-options>`
+    :type: dynamic
+    :category:
 
     :default: off
 
@@ -234,7 +308,13 @@ by saying ``-fno-wombat``.
     a shared-memory
     multiprocessor <http://community.haskell.org/~simonmar/papers/multiproc.pdf>`__.
 
+    See :ref:`parallel-compile-options` for a dicussion on its use.
+
 .. ghc-flag:: -fexcess-precision
+    :shortdesc: Enable excess intermediate precision
+    :type: dynamic
+    :reverse: -fno-excess-precision
+    :category:
 
     :default: off
 
@@ -250,6 +330,10 @@ by saying ``-fno-wombat``.
     :ref:`bugs-ghc`.
 
 .. ghc-flag:: -fexpose-all-unfoldings
+    :shortdesc: Expose all unfoldings, even for very large or recursive functions.
+    :type: dynamic
+    :reverse: -fno-expose-all-unfoldings
+    :category:
 
     :default: off
 
@@ -258,6 +342,10 @@ by saying ``-fno-wombat``.
     while usually GHC would avoid inlining larger functions.
 
 .. ghc-flag:: -ffloat-in
+    :shortdesc: Turn on the float-in transformation. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-float-in
+    :category:
 
     :default: on
 
@@ -279,6 +367,11 @@ by saying ``-fno-wombat``.
     allocation and helping the garbage collector and allocator.
 
 .. ghc-flag:: -ffull-laziness
+    :shortdesc: Turn on full laziness (floating bindings outwards).
+        Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-full-laziness
+    :category:
 
     :default: on
 
@@ -300,6 +393,11 @@ by saying ``-fno-wombat``.
        don't rely on it.
 
 .. ghc-flag:: -ffun-to-thunk
+    :shortdesc: Allow worker-wrapper to convert a function closure into a thunk
+        if the function does not use any of its arguments. Off by default.
+    :type: dynamic
+    :reverse: -fno-fun-to-thunk
+    :category:
 
     :default: off
 
@@ -309,6 +407,10 @@ by saying ``-fno-wombat``.
     This flag allows worker/wrapper to remove *all* value lambdas.
 
 .. ghc-flag:: -fignore-asserts
+    :shortdesc: Ignore assertions in the source. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-ignore-asserts
+    :category:
 
     :default: on
 
@@ -317,6 +419,10 @@ by saying ``-fno-wombat``.
     :ref:`assertions`).
 
 .. ghc-flag:: -fignore-interface-pragmas
+    :shortdesc: Ignore pragmas in interface files. Implied by :ghc-flag:`-O0` only.
+    :type: dynamic
+    :reverse: -fno-ignore-interface-pragmas
+    :category:
 
     :default: off
 
@@ -326,6 +432,11 @@ by saying ``-fno-wombat``.
     information.
 
 .. ghc-flag:: -flate-dmd-anal
+    :shortdesc: Run demand analysis again, at the end of the
+        simplification pipeline
+    :type: dynamic
+    :reverse: -fno-late-dmd-anal
+    :category:
 
     :default: off
 
@@ -337,6 +448,10 @@ by saying ``-fno-wombat``.
     so is the cost. See notes on the :ghc-wiki:`Trac wiki page <LateDmd>`.
 
 .. ghc-flag:: -fliberate-case
+    :shortdesc: Turn on the liberate-case transformation. Implied by :ghc-flag:`-O2`.
+    :type: dynamic
+    :reverse: -fno-liberate-case
+    :category:
 
     :default: off but enabled with :ghc-flag:`-O2`.
 
@@ -346,12 +461,22 @@ by saying ``-fno-wombat``.
     free variables rather than arguments.
 
 .. ghc-flag:: -fliberate-case-threshold=⟨n⟩
+    :shortdesc: *default: 2000.* Set the size threshold for the liberate-case
+        transformation to ⟨n⟩
+    :type: dynamic
+    :reverse: -fno-liberate-case-threshold
+    :category:
 
     :default: 2000
 
     Set the size threshold for the liberate-case transformation.
 
 .. ghc-flag:: -floopification
+    :shortdesc: Turn saturated self-recursive tail-calls into local jumps in the
+        generated assembly. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-loopification
+    :category:
 
     :default: on
 
@@ -360,6 +485,10 @@ by saying ``-fno-wombat``.
     function calls.
 
 .. ghc-flag:: -fmax-inline-alloc-size=⟨n⟩
+    :shortdesc: *default: 128.* Set the maximum size of inline array allocations
+        to ⟨n⟩ bytes (default: 128).
+    :type: dynamic
+    :category:
 
     :default: 128
 
@@ -369,12 +498,20 @@ by saying ``-fno-wombat``.
     value should be quite a bit smaller than the block size (typically: 4096).
 
 .. ghc-flag:: -fmax-inline-memcpy-insns=⟨n⟩
+    :shortdesc: *default: 32.* Inline ``memcpy`` calls if they would generate no
+        more than ⟨n⟩ pseudo instructions.
+    :type: dynamic
+    :category:
 
     :default: 32
 
     Inline ``memcpy`` calls if they would generate no more than ⟨n⟩ pseudo-instructions.
 
 .. ghc-flag:: -fmax-inline-memset-insns=⟨n⟩
+    :shortdesc: *default: 32.* Inline ``memset`` calls if they would generate no
+        more than ⟨n⟩ pseudo instructions
+    :type: dynamic
+    :category:
 
     :default: 32
 
@@ -382,7 +519,11 @@ by saying ``-fno-wombat``.
     instructions.
 
 .. ghc-flag:: -fmax-relevant-binds=⟨n⟩
-              -fno-max-relevant-bindings
+    :shortdesc: *default: 6.* Set the maximum number of bindings to display in
+        type error messages.
+    :type: dynamic
+    :reverse: -fno-max-relevant-bindings
+    :category:
 
     :default: 6
 
@@ -395,7 +536,11 @@ by saying ``-fno-wombat``.
     them too.
 
 .. ghc-flag:: -fmax-valid-substitutions=⟨n⟩
-              -fno-max-valid-substitutions
+    :shortdesc: *default: 6.* Set the maximum number of valid substitutions for
+        typed holes to display in type error messages.
+    :type: dynamic
+    :reverse: -fno-max-valid-substitutions
+    :category:
 
     :default: 6
 
@@ -405,6 +550,10 @@ by saying ``-fno-wombat``.
     ``-fno-max-valid-substitutions`` gives an unlimited number.
 
 .. ghc-flag:: -fmax-uncovered-patterns=⟨n⟩
+    :shortdesc: *default: 4.* Set the maximum number of patterns to display in
+        warnings about non-exhaustive ones.
+    :type: dynamic
+    :category:
 
     :default: 4
 
@@ -412,30 +561,48 @@ by saying ``-fno-wombat``.
     :ghc-flag:`-Wincomplete-patterns` and :ghc-flag:`-Wincomplete-uni-patterns`.
 
 .. ghc-flag:: -fmax-simplifier-iterations=⟨n⟩
+    :shortdesc: *default: 4.* Set the max iterations for the simplifier.
+    :type: dynamic
+    :category:
 
     :default: 4
 
     Sets the maximal number of iterations for the simplifier.
 
 .. ghc-flag:: -fmax-worker-args=⟨n⟩
+    :shortdesc: *default: 10.* If a worker has that many arguments, none will
+        be unpacked anymore.
+    :type: dynamic
+    :category:
 
     :default: 10
 
     If a worker has that many arguments, none will be unpacked anymore.
 
 .. ghc-flag:: -fno-opt-coercion
+    :shortdesc: Turn off the coercion optimiser
+    :type: dynamic
+    :category:
 
     :default: off
 
     Turn off the coercion optimiser.
 
 .. ghc-flag:: -fno-pre-inlining
+    :shortdesc: Turn off pre-inlining
+    :type: dynamic
+    :category:
 
     :default: off
 
     Turn off pre-inlining.
 
 .. ghc-flag:: -fno-state-hack
+    :shortdesc: Turn off the \state hack\ whereby any lambda with a real-world
+        state token as argument is considered to be single-entry. Hence
+        OK to inline things inside it.
+    :type: dynamic
+    :category:
 
     :default: off
 
@@ -445,6 +612,10 @@ by saying ``-fno-wombat``.
     and ST monad code, but it runs the risk of reducing sharing.
 
 .. ghc-flag:: -fomit-interface-pragmas
+    :shortdesc: Don't generate interface pragmas. Implied by :ghc-flag:`-O0` only.
+    :type: dynamic
+    :reverse: -fno-omit-interface-pragmas
+    :category:
 
     :default: off
 
@@ -458,6 +629,10 @@ by saying ``-fno-wombat``.
     type, not when they change their implementation).
 
 .. ghc-flag:: -fomit-yields
+    :shortdesc: Omit heap checks when no allocation is being performed.
+    :type: dynamic
+    :reverse: -fno-omit-yields
+    :category:
 
     :default: on
 
@@ -470,6 +645,12 @@ by saying ``-fno-wombat``.
     turned off, if you need to guarantee interruptibility.
 
 .. ghc-flag:: -fpedantic-bottoms
+    :shortdesc: Make GHC be more precise about its treatment of bottom (but see
+        also :ghc-flag:`-fno-state-hack`). In particular, GHC will not
+        eta-expand through a case expression.
+    :type: dynamic
+    :reverse: -fno-pedantic-bottoms
+    :category:
 
     Make GHC be more precise about its treatment of bottom (but see also
     :ghc-flag:`-fno-state-hack`). In particular, stop GHC eta-expanding through
@@ -477,6 +658,11 @@ by saying ``-fno-wombat``.
     using ``seq`` on partial applications.
 
 .. ghc-flag:: -fregs-graph
+    :shortdesc: Use the graph colouring register allocator for register
+        allocation in the native code generator. Implied by :ghc-flag:`-O2`.
+    :type: dynamic
+    :reverse: -fno-regs-graph
+    :category:
 
     :default: off due to a performance regression bug (:ghc-ticket:`7679`)
 
@@ -490,6 +676,11 @@ by saying ``-fno-wombat``.
     when faced with code with high register pressure :ghc-ticket:`8657`.
 
 .. ghc-flag:: -fregs-iterative
+    :shortdesc: Use the iterative coalescing graph colouring register allocator
+        in the native code generator.
+    :type: dynamic
+    :reverse: -fno-regs-iterative
+    :category:
 
     :default: off
 
@@ -500,12 +691,19 @@ by saying ``-fno-wombat``.
     during register allocation.
 
 .. ghc-flag:: -fsimplifier-phases=⟨n⟩
+    :shortdesc: *default: 2.* Set the number of phases for the simplifier.
+        Ignored with :ghc-flag:`-O0`.
+    :type: dynamic
+    :category:
 
     :default: 2
 
     Set the number of phases for the simplifier. Ignored with ``-O0``.
 
 .. ghc-flag:: -fsimpl-tick-factor=⟨n⟩
+    :shortdesc: *default: 100.* Set the percentage factor for simplifier ticks.
+    :type: dynamic
+    :category:
 
     :default: 100
 
@@ -526,6 +724,10 @@ by saying ``-fno-wombat``.
     accurately, because some numbers are very large.
 
 .. ghc-flag:: -fspec-constr
+    :shortdesc: Turn on the SpecConstr transformation. Implied by :ghc-flag:`-O2`.
+    :type: dynamic
+    :reverse: -fno-spec-constr
+    :category:
 
     :default: off but enabled by :ghc-flag:`-O2`.
 
@@ -590,6 +792,11 @@ by saying ``-fno-wombat``.
     cases.
 
 .. ghc-flag:: -fspec-constr-keen
+    :shortdesc: Specialize a call with an explicit constructor argument,
+        even if the argument is not scrutinised in the body of the function
+    :type: dynamic
+    :reverse: -fno-spec-constr-keen
+    :category:
 
     :default: off
 
@@ -600,6 +807,12 @@ by saying ``-fno-wombat``.
     that can itself be specialised.
 
 .. ghc-flag:: -fspec-constr-count=⟨n⟩
+    :shortdesc: default: 3.* Set to ⟨n⟩ the maximum number of specialisations that
+        will be created for any one function by the SpecConstr
+        transformation.
+    :type: dynamic
+    :reverse: -fno-spec-constr-count
+    :category:
 
     :default: 3
 
@@ -607,12 +820,21 @@ by saying ``-fno-wombat``.
     any one function by the SpecConstr transformation.
 
 .. ghc-flag:: -fspec-constr-threshold=⟨n⟩
+    :shortdesc: *default: 2000.* Set the size threshold for the SpecConstr
+        transformation to ⟨n⟩.
+    :type: dynamic
+    :reverse: -fno-spec-constr-threshold
+    :category:
 
     :default: 2000
 
     Set the size threshold for the SpecConstr transformation.
 
 .. ghc-flag:: -fspecialise
+    :shortdesc: Turn on specialisation of overloaded functions. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-specialise
+    :category:
 
     :default: on
 
@@ -623,6 +845,11 @@ by saying ``-fno-wombat``.
     specialised as well.
 
 .. ghc-flag:: -fspecialise-aggressively
+    :shortdesc: Turn on specialisation of overloaded functions regardless of
+        size, if unfolding is available
+    :type: dynamic
+    :reverse: -fno-specialise-aggressively
+    :category:
 
     :default: off
 
@@ -635,6 +862,11 @@ by saying ``-fno-wombat``.
 
 
 .. ghc-flag:: -fcross-module-specialise
+    :shortdesc: Turn on specialisation of overloaded functions imported from
+        other modules.
+    :type: dynamic
+    :reverse: -fno-cross-module-specialise
+    :category:
 
     :default: on
 
@@ -644,6 +876,11 @@ by saying ``-fno-wombat``.
     enabled (by ``-fspecialise``) for this to have any effect.
 
 .. ghc-flag:: -fsolve-constant-dicts
+    :shortdesc: When solving constraints, try to eagerly solve
+        super classes using available dictionaries.
+    :type: dynamic
+    :reverse: -fno-solve-constant-dicts
+    :category:
 
     :default: on
 
@@ -675,6 +912,10 @@ by saying ``-fno-wombat``.
 
 
 .. ghc-flag:: -fstatic-argument-transformation
+    :shortdesc: Turn on the static argument transformation.
+    :type: dynamic
+    :reverse: -fno-static-argument-transformation
+    :category:
 
     :default: off
 
@@ -684,6 +925,11 @@ by saying ``-fno-wombat``.
     thesis <http://research.microsoft.com/en-us/um/people/simonpj/papers/santos-thesis.ps.gz>`__
 
 .. ghc-flag:: -fstrictness
+    :shortdesc: Turn on strictness analysis.
+        Implied by :ghc-flag:`-O`. Implies :ghc-flag:`-fworker-wrapper`
+    :type: dynamic
+    :reverse: -fno-strictness
+    :category:
 
     :default: on
 
@@ -698,10 +944,18 @@ by saying ``-fno-wombat``.
     arguments.
 
 .. ghc-flag:: -fstrictness-before=⟨n⟩
+    :shortdesc: Run an additional strictness analysis before simplifier phase ⟨n⟩
+    :type: dynamic
+    :category:
 
     Run an additional strictness analysis before simplifier phase ⟨n⟩.
 
 .. ghc-flag:: -funbox-small-strict-fields
+    :shortdesc: Flatten strict constructor fields with a pointer-sized
+        representation. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-unbox-small-strict-fields
+    :category:
 
     :default: on
 
@@ -737,6 +991,10 @@ by saying ``-fno-wombat``.
     they are technically larger than a pointer on those platforms.
 
 .. ghc-flag:: -funbox-strict-fields
+    :shortdesc: Flatten strict constructor fields
+    :type: dynamic
+    :reverse: -fno-unbox-strict-fields
+    :category:
 
     :default: off
 
@@ -760,6 +1018,9 @@ by saying ``-fno-wombat``.
     unbox strict fields which are "small".
 
 .. ghc-flag:: -funfolding-creation-threshold=⟨n⟩
+    :shortdesc: *default: 750.* Tweak unfolding settings.
+    :type: dynamic
+    :category:
 
     :default: 750
 
@@ -783,6 +1044,9 @@ by saying ``-fno-wombat``.
     useful.
 
 .. ghc-flag:: -funfolding-dict-discount=⟨n⟩
+    :shortdesc: *default: 30.* Tweak unfolding settings.
+    :type: dynamic
+    :category:
 
     :default: 30
 
@@ -793,6 +1057,9 @@ by saying ``-fno-wombat``.
     How eager should the compiler be to inline dictionaries?
 
 .. ghc-flag:: -funfolding-fun-discount=⟨n⟩
+    :shortdesc: *default: 60.* Tweak unfolding settings.
+    :type: dynamic
+    :category:
 
     :default: 60
 
@@ -803,6 +1070,9 @@ by saying ``-fno-wombat``.
     How eager should the compiler be to inline functions?
 
 .. ghc-flag:: -funfolding-keeness-factor=⟨n⟩
+    :shortdesc: *default: 1.5.* Tweak unfolding settings.
+    :type: dynamic
+    :category:
 
     :default: 1.5
 
@@ -813,6 +1083,9 @@ by saying ``-fno-wombat``.
     How eager should the compiler be to inline functions?
 
 .. ghc-flag:: -funfolding-use-threshold=⟨n⟩
+    :shortdesc: *default: 60.* Tweak unfolding settings.
+    :type: dynamic
+    :category:
 
     :default: 60
 
@@ -834,6 +1107,10 @@ by saying ``-fno-wombat``.
     potential inlining.
 
 .. ghc-flag:: -fvectorisation-avoidance
+    :shortdesc: Enable vectorisation avoidance. Always enabled by default.
+    :type: dynamic
+    :reverse: -fno-vectorisation-avoidance
+    :category:
 
     :default: on
 
@@ -852,6 +1129,10 @@ by saying ``-fno-wombat``.
     function would be better of unvectorised and if so, do just that.
 
 .. ghc-flag:: -fvectorise
+    :shortdesc: Enable vectorisation of nested data parallelism
+    :type: dynamic
+    :reverse: -fno-vectorise
+    :category:
 
     :default: off
 
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index 48a9296b1a..39d7de4147 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -37,6 +37,10 @@ generally likely to indicate bugs in your program. These are:
 The following flags are simple ways to select standard "packages" of warnings:
 
 .. ghc-flag:: -W
+    :shortdesc: enable normal warnings
+    :type: dynamic
+    :reverse: -w
+    :category:
 
     Provides the standard warnings plus
 
@@ -53,6 +57,10 @@ The following flags are simple ways to select standard "packages" of warnings:
         * :ghc-flag:`-Wunbanged-strict-patterns`
 
 .. ghc-flag:: -Wall
+    :shortdesc: enable almost all warnings (details in :ref:`options-sanity`)
+    :type: dynamic
+    :reverse: -w
+    :category:
 
     Turns on all warning options that indicate potentially suspicious
     code. The warnings that are *not* enabled by :ghc-flag:`-Wall` are
@@ -72,6 +80,11 @@ The following flags are simple ways to select standard "packages" of warnings:
         * :ghc-flag:`-Wredundant-constraints`
 
 .. ghc-flag:: -Wcompat
+    :shortdesc: enable future compatibility warnings
+        (details in :ref:`options-sanity`)
+    :type: dynamic
+    :reverse: -Wno-compat
+    :category:
 
     Turns on warnings that will be enabled by default in the future, but remain
     off in normal compilations for the time being. This allows library authors
@@ -88,10 +101,17 @@ The following flags are simple ways to select standard "packages" of warnings:
         * :ghc-flag:`-Wnoncanonical-monoid-instances`
 
 .. ghc-flag:: -Wno-compat
+    :shortdesc: Disables all warnings enabled by :ghc-flag:`-Wcompat`.
+    :type: dynamic
+    :reverse: -Wcompat
+    :category:
 
     Disables all warnings enabled by :ghc-flag:`-Wcompat`.
 
 .. ghc-flag:: -w
+    :shortdesc: disable all warnings
+    :type: dynamic
+    :category:
 
     Turns off all warnings, including the standard ones and those that
     :ghc-flag:`-Wall` doesn't enable.
@@ -100,11 +120,19 @@ These options control which warnings are considered fatal and cause compilation
 to abort.
 
 .. ghc-flag:: -Werror
+    :shortdesc: make warnings fatal
+    :type: dynamic
+    :reverse: -Wwarn
+    :category:
 
     Makes any warning into a fatal error. Useful so that you don't miss
     warnings when doing batch compilation.
 
 .. ghc-flag:: -Werror=⟨wflag⟩
+    :shortdesc: make a specific warning fatal
+    :type: dynamic
+    :reverse: -Wwarn=⟨wflag⟩
+    :category:
     :noindex:
 
     :implies: ``-W<wflag>``
@@ -113,11 +141,19 @@ to abort.
     it hasn't been enabled yet.
 
 .. ghc-flag:: -Wwarn
+    :shortdesc: make warnings non-fatal
+    :type: dynamic
+    :reverse: -Werror
+    :category:
 
     Warnings are treated only as warnings, not as errors. This is the
     default, but can be useful to negate a :ghc-flag:`-Werror` flag.
 
 .. ghc-flag:: -Wwarn=⟨wflag⟩
+    :shortdesc: make a specific warning non-fatal
+    :type: dynamic
+    :reverse: -Werror=⟨wflag⟩
+    :category:
     :noindex:
 
     Causes a specific warning to be treated as normal warning, not fatal error.
@@ -129,6 +165,10 @@ When a warning is emitted, the specific warning flag which controls
 it is shown.
 
 .. ghc-flag:: -fshow-warning-groups
+    :shortdesc: show which group an emitted warning belongs to.
+    :type: dynamic
+    :reverse: -fno-show-warning-groups
+    :category:
 
     When showing which flag controls a warning, also show the
     respective warning group flag(s) that warning is contained in.
@@ -142,6 +182,11 @@ all these warnings can still be controlled with ``-f(no-)warn-*`` instead
 of ``-W(no-)*``.
 
 .. ghc-flag:: -Wunrecognised-warning-flags
+    :shortdesc: throw a warning when an unreconised ``-W...`` flag is
+        encountered on the command line.
+    :type: dynamic
+    :reverse: -Wno-unrecognised-warning-flags
+    :category:
 
     Enables warnings when the compiler encounters a ``-W...`` flag that is not
     recognised.
@@ -149,6 +194,12 @@ of ``-W(no-)*``.
     This warning is on by default.
 
 .. ghc-flag:: -Wtyped-holes
+    :shortdesc: Report warnings when :ref:`typed hole <typed-holes>` errors are
+        :ref:`deferred until runtime <defer-type-errors>`. See
+        :ghc-flag:`-fdefer-typed-holes`.
+    :type: dynamic
+    :reverse: -Wno-typed-holes
+    :category:
 
     Determines whether the compiler reports typed holes warnings. Has no
     effect unless typed holes errors are deferred until runtime. See
@@ -156,7 +207,13 @@ of ``-W(no-)*``.
 
     This warning is on by default.
 
-.. ghc-flag:: -Wtype-errors
+.. ghc-flag:: -Wdeferred-type-errors
+    :shortdesc: Report warnings when :ref:`deferred type errors
+        <defer-type-errors>` are enabled. This option is enabled by
+        default. See :ghc-flag:`-fdefer-type-errors`.
+    :type: dynamic
+    :reverse: -Wno-deferred-type-errors
+    :category:
 
     Causes a warning to be reported when a type error is deferred until
     runtime. See :ref:`defer-type-errors`
@@ -164,6 +221,14 @@ of ``-W(no-)*``.
     This warning is on by default.
 
 .. ghc-flag:: -fdefer-type-errors
+    :shortdesc: Turn type errors into warnings, :ref:`deferring the error until
+        runtime <defer-type-errors>`. Implies
+        :ghc-flag:`-fdefer-typed-holes` and
+        :ghc-flag:`-fdefer-out-of-scope-variables`.
+        See also :ghc-flag:`-Wdeferred-type-errors`
+    :type: dynamic
+    :reverse: -fno-defer-type-errors
+    :category:
 
     :implies: :ghc-flag:`-fdefer-typed-holes`
 
@@ -174,6 +239,13 @@ of ``-W(no-)*``.
     :ref:`defer-type-errors`
 
 .. ghc-flag:: -fdefer-typed-holes
+    :shortdesc: Convert :ref:`typed hole <typed-holes>` errors into warnings,
+        :ref:`deferring the error until runtime <defer-type-errors>`.
+        Implied by :ghc-flag:`-fdefer-type-errors`.
+        See also :ghc-flag:`-Wtyped-holes`.
+    :type: dynamic
+    :reverse: -fno-defer-typed-holes
+    :category:
 
     Defer typed holes errors (errors about names with a leading underscore
     (e.g., “_”, “_foo”, “_bar”)) until runtime. This will turn the errors
@@ -185,6 +257,12 @@ of ``-W(no-)*``.
     Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wtyped-holes`.
 
 .. ghc-flag:: -fdefer-out-of-scope-variables
+    :shortdesc: Convert variable out of scope variables errors into warnings.
+        Implied by :ghc-flag:`-fdefer-type-errors`.
+        See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
+    :type: dynamic
+    :reverse: -fno-defer-out-of-scope-variables
+    :category:
 
     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.
@@ -195,10 +273,24 @@ 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
+    :shortdesc: Report warnings when variable out-of-scope errors are
+        :ref:`deferred until runtime.
+        See :ghc-flag:`-fdefer-out-of-scope-variables`.
+    :type: dynamic
+    :reverse: -Wno-deferred-out-of-scope-variables
+    :category:
 
     Warn when a deferred out-of-scope variable is encountered.
 
 .. ghc-flag:: -Wpartial-type-signatures
+    :shortdesc: warn about holes in partial type signatures when
+        :ghc-flag:`-XPartialTypeSignatures` is enabled. Not applicable when
+        :ghc-flag:`-XPartialTypesignatures` is not enabled, in which case
+        errors are generated for such holes. See
+        :ref:`partial-type-signatures`.
+    :type: dynamic
+    :reverse: -Wno-partial-type-signatures
+    :category:
 
     Determines whether the compiler reports holes in partial type
     signatures as warnings. Has no effect unless
@@ -209,6 +301,10 @@ of ``-W(no-)*``.
     This warning is on by default.
 
 .. ghc-flag:: -fhelpful-errors
+    :shortdesc: Make suggestions for mis-spelled names.
+    :type: dynamic
+    :reverse: -fno-helpful-errors
+    :category:
 
     When a name or package is not found in scope, make suggestions for
     the name or package you might have meant instead.
@@ -216,6 +312,10 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Wunrecognised-pragmas
+    :shortdesc: warn about uses of pragmas that GHC doesn't recognise
+    :type: dynamic
+    :reverse: -Wno-unrecognised-pragmas
+    :category:
 
     Causes a warning to be emitted when a pragma that GHC doesn't
     recognise is used. As well as pragmas that GHC itself uses, GHC also
@@ -225,22 +325,47 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Wmissed-specialisations
-              -Wall-missed-specialisations
+    :shortdesc: warn when specialisation of an imported, overloaded function
+        fails.
+    :type: dynamic
+    :reverse: -Wno-missed-specialisations
+    :category:
 
     Emits a warning if GHC cannot specialise an overloaded function, usually
-    because the function needs an ``INLINABLE`` pragma. The "all" form reports
-    all such situations whereas the "non-all" form only reports when the
+    because the function needs an ``INLINABLE`` pragma. Reports when the
     situation arises during specialisation of an imported function.
 
-    The "non-all" form is intended to catch cases where an imported function
-    that is marked as ``INLINABLE`` (presumably to enable specialisation) cannot
-    be specialised as it calls other functions that are themselves not specialised.
+    This form is intended to catch cases where an imported function
+    that is marked as ``INLINABLE`` (presumably to enable specialisation)
+    cannot be specialised as it calls other functions that are themselves not
+    specialised.
 
-    Note that these warnings will not throw errors if used with :ghc-flag:`-Werror`.
+    Note that this warning will not throw errors if used with
+    :ghc-flag:`-Werror`.
 
-    These options are both off by default.
+    This option is off by default.
+
+.. ghc-flag:: -Wall-missed-specialisations
+    :shortdesc: warn when specialisation of any overloaded function fails.
+    :type: dynamic
+    :reverse: -Wno-all-missed-specialisations
+    :category:
+
+    Emits a warning if GHC cannot specialise an overloaded function, usually
+    because the function needs an ``INLINABLE`` pragma. Reports
+    all such situations.
+
+    Note that this warning will not throw errors if used with
+    :ghc-flag:`-Werror`.
+
+    This option is off by default.
 
 .. ghc-flag:: -Wwarnings-deprecations
+    :shortdesc: warn about uses of functions & types that have warnings or
+        deprecated pragmas
+    :type: dynamic
+    :reverse: -Wno-warnings-deprecations
+    :category:
 
     .. index::
        pair: deprecations; warnings
@@ -252,6 +377,11 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Wdeprecations
+    :shortdesc: warn about uses of functions & types that have warnings or
+        deprecated pragmas. Alias for :ghc-flag:`-Wwarnings-deprecations`
+    :type: dynamic
+    :reverse: -Wno-deprecations
+    :category:
 
     .. index::
        single: deprecations
@@ -264,6 +394,11 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Wamp
+    :shortdesc: *(deprecated)* warn on definitions conflicting with the
+        Applicative-Monad Proposal (AMP)
+    :type: dynamic
+    :reverse: -Wno-amp
+    :category:
 
     .. index::
        single: AMP
@@ -275,6 +410,13 @@ of ``-W(no-)*``.
     the AMP (Applicative-Monad proosal).
 
 .. ghc-flag:: -Wnoncanonical-monad-instances
+    :shortdesc: warn when ``Applicative`` or ``Monad`` instances have
+        noncanonical definitions of ``return``, ``pure``, ``(>>)``,
+        or ``(*>)``.
+        See flag description in :ref:`options-sanity` for more details.
+    :type: dynamic
+    :reverse: -Wno-noncanonical-monad-instances
+    :category:
 
     Warn if noncanonical ``Applicative`` or ``Monad`` instances
     declarations are detected.
@@ -295,6 +437,12 @@ of ``-W(no-)*``.
     This option is off by default.
 
 .. ghc-flag:: -Wnoncanonical-monadfail-instances
+    :shortdesc: warn when ``Monad`` or ``MonadFail`` instances have
+        noncanonical definitions of ``fail``.
+        See flag description in :ref:`options-sanity` for more details.
+    :type: dynamic
+    :reverse: -Wno-noncanonical-monadfail-instances
+    :category:
 
     Warn if noncanonical ``Monad`` or ``MonadFail`` instances
     declarations are detected.
@@ -317,6 +465,12 @@ of ``-W(no-)*``.
     This option is off by default.
 
 .. ghc-flag:: -Wnoncanonical-monoid-instances
+    :shortdesc: warn when ``Semigroup`` or ``Monoid`` instances have
+        noncanonical definitions of ``(<>)`` or ``mappend``.
+        See flag description in :ref:`options-sanity` for more details.
+    :type: dynamic
+    :reverse: -Wno-noncanonical-monoid-instances
+    :category:
 
     Warn if noncanonical ``Semigroup`` or ``Monoid`` instances
     declarations are detected.
@@ -337,6 +491,11 @@ of ``-W(no-)*``.
     :ghc-flag:`-Wcompat` option group.
 
 .. ghc-flag:: -Wmissing-monadfail-instances
+    :shortdesc: Warn when a failable pattern is used in a do-block that does
+        not have a ``MonadFail`` instance.
+    :type: dynamic
+    :reverse: -Wno-missing-monadfail-instances
+    :category:
 
     .. index::
        single: MFP
@@ -353,6 +512,11 @@ of ``-W(no-)*``.
     <https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
 
 .. ghc-flag:: -Wsemigroup
+    :shortdesc: warn when a ``Monoid`` is not ``Semigroup``, and on non-
+        ``Semigroup`` definitions of ``(<>)``?
+    :type: dynamic
+    :reverse: -Wno-semigroup
+    :category:
 
     .. index::
        single: semigroup; warning
@@ -368,6 +532,10 @@ of ``-W(no-)*``.
     default, but will be switched on in a future GHC release.
 
 .. ghc-flag:: -Wdeprecated-flags
+    :shortdesc: warn about uses of commandline flags that are deprecated
+    :type: dynamic
+    :reverse: -Wno-deprecated-flags
+    :category:
 
     .. index::
        single: deprecated flags
@@ -378,6 +546,10 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Wunsupported-calling-conventions
+    :shortdesc: warn about use of an unsupported calling convention
+    :type: dynamic
+    :reverse: -Wno-unsupported-calling-conventions
+    :category:
 
     Causes a warning to be emitted for foreign declarations that use
     unsupported calling conventions. In particular, if the ``stdcall``
@@ -385,6 +557,10 @@ of ``-W(no-)*``.
     it will be treated as ``ccall``.
 
 .. ghc-flag:: -Wdodgy-foreign-imports
+    :shortdesc: warn about dodgy foreign imports
+    :type: dynamic
+    :reverse: -Wno-dodgy-foreign-import
+    :category:
 
     Causes a warning to be emitted for foreign imports of the following
     form: ::
@@ -403,6 +579,10 @@ of ``-W(no-)*``.
     warning.
 
 .. ghc-flag:: -Wdodgy-exports
+    :shortdesc: warn about dodgy exports
+    :type: dynamic
+    :reverse: -Wno-dodgy-exports
+    :category:
 
     Causes a warning to be emitted when a datatype ``T`` is exported
     with all constructors, i.e. ``T(..)``, but is it just a type
@@ -412,6 +592,10 @@ of ``-W(no-)*``.
     but that module exports nothing.
 
 .. ghc-flag:: -Wdodgy-imports
+    :shortdesc: warn about dodgy imports
+    :type: dynamic
+    :reverse: -Wno-dodgy-imports
+    :category:
 
     Causes a warning to be emitted in the following cases:
 
@@ -422,16 +606,28 @@ of ``-W(no-)*``.
        exported.
 
 .. ghc-flag:: -Woverflowed-literals
+    :shortdesc: warn about literals that will overflow their type
+    :type: dynamic
+    :reverse: -Wno-overflowed-literals
+    :category:
 
     Causes a warning to be emitted if a literal will overflow, e.g.
     ``300 :: Word8``.
 
 .. ghc-flag:: -Wempty-enumerations
+    :shortdesc: warn about enumerations that are empty
+    :type: dynamic
+    :reverse: -Wno-empty-enumerations
+    :category:
 
     Causes a warning to be emitted if an enumeration is empty, e.g.
     ``[5 .. 3]``.
 
 .. ghc-flag:: -Wduplicate-constraints
+    :shortdesc: warn when a constraint appears duplicated in a type signature
+    :type: dynamic
+    :reverse: -Wno-duplicate-constraints
+    :category:
 
     .. index::
        single: duplicate constraints, warning
@@ -447,6 +643,11 @@ of ``-W(no-)*``.
     :ghc-flag:`-Wredundant-constraints`.
 
 .. ghc-flag:: -Wredundant-constraints
+    :shortdesc: Have the compiler warn about redundant constraints in type
+        signatures.
+    :type: dynamic
+    :reverse: -Wno-redundant-constraints
+    :category:
 
     :since: 8.0
 
@@ -492,6 +693,10 @@ of ``-W(no-)*``.
     constraint is needed, so no warning is issued.
 
 .. ghc-flag:: -Wduplicate-exports
+    :shortdesc: warn when an entity is exported multiple times
+    :type: dynamic
+    :reverse: -Wno-duplicate-exports
+    :category:
 
     .. index::
        single: duplicate exports, warning
@@ -505,6 +710,10 @@ of ``-W(no-)*``.
     This option is on by default.
 
 .. ghc-flag:: -Whi-shadowing
+    :shortdesc: warn when a ``.hi`` file in the current directory shadows a library
+    :type: dynamic
+    :reverse: -Wno-hi-shadowing
+    :category:
 
     .. index::
        single: shadowing; interface files
@@ -514,6 +723,11 @@ of ``-W(no-)*``.
     name in a library or other directory.
 
 .. ghc-flag:: -Widentities
+    :shortdesc: warn about uses of Prelude numeric conversions that are probably
+        the identity (and hence could be omitted)
+    :type: dynamic
+    :reverse: -Wno-identities
+    :category:
 
     Causes the compiler to emit a warning when a Prelude numeric
     conversion converts a type ``T`` to the same type ``T``; such calls are
@@ -521,27 +735,34 @@ of ``-W(no-)*``.
     ``toInteger``, ``toRational``, ``fromIntegral``, and ``realToFrac``.
 
 .. ghc-flag:: -Wimplicit-prelude
+    :shortdesc: warn when the Prelude is implicitly imported
+    :type: dynamic
+    :reverse: -Wno-implicit-prelude
+    :category:
 
     .. index::
        single: implicit prelude, warning
 
-    Have the compiler warn if the Prelude is implicitly imported. This
-    happens unless either the Prelude module is explicitly imported with
-    an ``import ... Prelude ...`` line, or this implicit import is
-    disabled (either by :ghc-flag:`-XNoImplicitPrelude` or a
-    ``LANGUAGE NoImplicitPrelude`` pragma).
+    Have the compiler warn if the Prelude is implicitly imported. This happens
+    unless either the Prelude module is explicitly imported with an ``import
+    ... Prelude ...`` line, or this implicit import is disabled (either by
+    :ghc-flag:`-XNoImplicitPrelude` or a ``LANGUAGE NoImplicitPrelude``
+    pragma).
 
-    Note that no warning is given for syntax that implicitly refers to
-    the Prelude, even if :ghc-flag:`-XNoImplicitPrelude` would change whether it
-    refers to the Prelude. For example, no warning is given when ``368``
-    means ``Prelude.fromInteger (368::Prelude.Integer)`` (where
-    ``Prelude`` refers to the actual Prelude module, regardless of the
-    imports of the module being compiled).
+    Note that no warning is given for syntax that implicitly refers to the
+    Prelude, even if :ghc-flag:`-XNoImplicitPrelude` would change whether it
+    refers to the Prelude. For example, no warning is given when ``368`` means
+    ``Prelude.fromInteger (368::Prelude.Integer)`` (where ``Prelude`` refers
+    to the actual Prelude module, regardless of the imports of the module
+    being compiled).
 
     This warning is off by default.
 
 .. ghc-flag:: -Wincomplete-patterns
-              -Wincomplete-uni-patterns
+    :shortdesc: warn when a pattern match could fail
+    :type: dynamic
+    :reverse: -Wno-incomplete-patterns
+    :category:
 
     .. index::
        single: incomplete patterns, warning
@@ -559,14 +780,26 @@ of ``-W(no-)*``.
     generally considered good practice to cover all the cases in your
     functions, and it is switched on by :ghc-flag:`-W`.
 
-    The flag :ghc-flag:`-Wincomplete-uni-patterns` is similar, except that
-    it applies only to lambda-expressions and pattern bindings,
-    constructs that only allow a single pattern: ::
+
+.. ghc-flag:: -Wincomplete-uni-patterns
+    :shortdesc: warn when a pattern match in a lambda expression or
+        pattern binding could fail
+    :type: dynamic
+    :reverse: -Wno-incomplete-uni-patterns
+    :category:
+
+    The flag :ghc-flag:`-Wincomplete-uni-patterns` is similar to
+    :ghc-flag:`-Wincomplete-patterns`, except that it applies only to
+    lambda-expressions and pattern bindings, constructs that only allow a
+    single pattern: ::
 
         h = \[] -> 2
         Just k = f y
 
 .. ghc-flag:: -fmax-pmcheck-iterations=⟨n⟩
+    :shortdesc: the iteration limit for the pattern match checker
+    :type: dynamic
+    :category:
 
     :default: 2000000
 
@@ -579,6 +812,10 @@ of ``-W(no-)*``.
     pattern match, for the sake of future readers of your code.
 
 .. ghc-flag:: -Wincomplete-record-updates
+    :shortdesc: warn when a record update could fail
+    :type: dynamic
+    :reverse: -Wno-incomplete-record-updates
+    :category:
 
     .. index::
        single: incomplete record updates, warning
@@ -598,6 +835,10 @@ of ``-W(no-)*``.
     and it often doesn't indicate a bug in the program.
 
 .. ghc-flag:: -Wmissing-fields
+    :shortdesc: warn when fields of a record are uninitialised
+    :type: dynamic
+    :reverse: -Wno-missing-fields
+    :category:
 
     .. index::
        single: missing fields, warning
@@ -610,6 +851,11 @@ of ``-W(no-)*``.
     programmer error.
 
 .. ghc-flag:: -Wmissing-import-lists
+    :shortdesc: warn when an import declaration does not explicitly list all the
+        names brought into scope
+    :type: dynamic
+    :reverse: -fnowarn-missing-import-lists
+    :category:
 
     .. index::
        single: missing import lists, warning
@@ -632,6 +878,10 @@ of ``-W(no-)*``.
     unlikely to produce ambiguity in ``M``.
 
 .. ghc-flag:: -Wmissing-methods
+    :shortdesc: warn when class methods are undefined
+    :type: dynamic
+    :reverse: -Wno-missing-methods
+    :category:
 
     .. index::
        single: missing methods, warning
@@ -658,6 +908,10 @@ of ``-W(no-)*``.
     :ref:`minimal-pragma`.
 
 .. ghc-flag:: -Wmissing-signatures
+    :shortdesc: warn about top-level functions without signatures
+    :type: dynamic
+    :reverse: -Wno-missing-signatures
+    :category:
 
     .. index::
        single: type signatures, missing
@@ -668,6 +922,12 @@ of ``-W(no-)*``.
     option is off by default.
 
 .. ghc-flag:: -Wmissing-exported-sigs
+    :shortdesc: *(deprecated)*
+        warn about top-level functions without signatures, only if they
+        are exported. takes precedence over -Wmissing-signatures
+    :type: dynamic
+    :reverse: -Wno-missing-exported-sigs
+    :category:
 
     .. index::
        single: type signatures, missing
@@ -676,6 +936,11 @@ of ``-W(no-)*``.
     :ghc-flag:`-Wmissing-exported-signatures`.
 
 .. ghc-flag:: -Wmissing-exported-signatures
+    :shortdesc: warn about top-level functions without signatures, only if they
+        are exported. takes precedence over -Wmissing-signatures
+    :type: dynamic
+    :reverse: -Wno-missing-exported-signatures
+    :category:
 
     .. index::
        single: type signatures, missing
@@ -688,6 +953,11 @@ of ``-W(no-)*``.
     reports the inferred type. The option is off by default.
 
 .. ghc-flag:: -Wmissing-local-sigs
+    :shortdesc: *(deprecated)*
+        warn about polymorphic local bindings without signatures
+    :type: dynamic
+    :reverse: -Wno-missing-local-sigs
+    :category:
 
     .. index::
        single: type signatures, missing
@@ -696,6 +966,10 @@ of ``-W(no-)*``.
     :ghc-flag:`-Wmissing-local-signatures`.
 
 .. ghc-flag:: -Wmissing-local-signatures
+    :shortdesc: warn about polymorphic local bindings without signatures
+    :type: dynamic
+    :reverse: -Wno-missing-local-signatures
+    :category:
 
     .. index::
        single: type signatures, missing
@@ -706,6 +980,10 @@ of ``-W(no-)*``.
     default.
 
 .. ghc-flag:: -Wmissing-pattern-synonym-signatures
+    :shortdesc: warn when pattern synonyms do not have type signatures
+    :type: dynamic
+    :reverse: -Wno-missing-pattern-synonym-signatures
+    :category:
 
     .. index::
          single: type signatures, missing, pattern synonyms
@@ -719,6 +997,10 @@ of ``-W(no-)*``.
     type. This option is off by default.
 
 .. ghc-flag:: -Wname-shadowing
+    :shortdesc: warn when names are shadowed
+    :type: dynamic
+    :reverse: -Wno-name-shadowing
+    :category:
 
     .. index::
        single: shadowing, warning
@@ -736,6 +1018,11 @@ of ``-W(no-)*``.
         f x = do { _ignore <- this; _ignore <- that; return (the other) }
 
 .. ghc-flag:: -Worphans
+    :shortdesc: warn when the module contains :ref:`orphan instance declarations
+        or rewrite rules <orphan-modules>`
+    :type: dynamic
+    :reverse: -Wno-orphans
+    :category:
 
     .. index::
        single: orphan instances, warning
@@ -758,6 +1045,10 @@ of ``-W(no-)*``.
     instances.
 
 .. ghc-flag:: -Woverlapping-patterns
+    :shortdesc: warn about overlapping patterns
+    :type: dynamic
+    :reverse: -Wno-overlapping-patterns
+    :category:
 
     .. index::
        single: overlapping patterns, warning
@@ -776,6 +1067,11 @@ of ``-W(no-)*``.
     is a programmer mistake/error, so this option is enabled by default.
 
 .. ghc-flag:: -Wsimplifiable-class-constraints
+    :shortdesc: 2arn about class constraints in a type signature that can
+        be simplified using a top-level instance declaration.
+    :type: dynamic
+    :reverse: -Wno-overlapping-patterns
+    :category:
 
     :since: 8.2
 
@@ -799,6 +1095,10 @@ of ``-W(no-)*``.
     <-Wsimplifiable-class-constraints>`.
 
 .. ghc-flag:: -Wtabs
+    :shortdesc: warn if there are tabs in the source file
+    :type: dynamic
+    :reverse: -Wno-tabs
+    :category:
 
     .. index::
        single: tabs, warning
@@ -806,6 +1106,10 @@ of ``-W(no-)*``.
     Have the compiler warn if there are tabs in your source file.
 
 .. ghc-flag:: -Wtype-defaults
+    :shortdesc: warn when defaulting happens
+    :type: dynamic
+    :reverse: -Wno-type-defaults
+    :category:
 
     .. index::
        single: defaulting mechanism, warning
@@ -822,6 +1126,10 @@ of ``-W(no-)*``.
     This warning is off by default.
 
 .. ghc-flag:: -Wmonomorphism-restriction
+    :shortdesc: warn when the Monomorphism Restriction is applied
+    :type: dynamic
+    :reverse: -Wno-monomorphism-restriction
+    :category:
 
     .. index::
        single: monomorphism restriction, warning
@@ -834,10 +1142,19 @@ of ``-W(no-)*``.
     This warning is off by default.
 
 .. ghc-flag:: -Wunsupported-llvm-version
+    :shortdesc: Warn when using :ghc-flag:`-fllvm` with an unsupported
+        version of LLVM.
+    :type: dynamic
+    :reverse: -Wno-monomorphism-restriction
+    :category:
 
     Warn when using :ghc-flag:`-fllvm` with an unsupported version of LLVM.
 
 .. ghc-flag:: -Wunticked-promoted-constructors
+    :shortdesc: warn if promoted constructors are not ticked
+    :type: dynamic
+    :reverse: -Wno-unticked-promoted-constructors
+    :category:
 
     .. index::
        single: promoted constructor, warning
@@ -859,6 +1176,12 @@ of ``-W(no-)*``.
     This warning is enabled by default in :ghc-flag:`-Wall` mode.
 
 .. ghc-flag:: -Wunused-binds
+    :shortdesc: warn about bindings that are unused. Alias for
+        :ghc-flag:`-Wunused-top-binds`, :ghc-flag:`-Wunused-local-binds` and
+        :ghc-flag:`-Wunused-pattern-binds`
+    :type: dynamic
+    :reverse: -Wno-unused-binds
+    :category:
 
     .. index::
        single: unused binds, warning
@@ -872,6 +1195,10 @@ of ``-W(no-)*``.
     -  :ghc-flag:`-Wunused-pattern-binds`
 
 .. ghc-flag:: -Wunused-top-binds
+    :shortdesc: warn about top-level bindings that are unused
+    :type: dynamic
+    :reverse: -Wno-unused-top-binds
+    :category:
 
     .. index::
        single: unused binds, warning
@@ -902,6 +1229,10 @@ of ``-W(no-)*``.
         _w = True                    -- No warning: _w starts with an underscore
 
 .. ghc-flag:: -Wunused-local-binds
+    :shortdesc: warn about local bindings that are unused
+    :type: dynamic
+    :reverse: -Wno-unused-local-binds
+    :category:
 
     .. index::
        single: unused binds, warning
@@ -914,6 +1245,10 @@ of ``-W(no-)*``.
         g = h x                      -- No warning: g is unused, but is a top-level binding
 
 .. ghc-flag:: -Wunused-pattern-binds
+    :shortdesc: warn about pattern match bindings that are unused
+    :type: dynamic
+    :reverse: -Wno-unused-pattern-binds
+    :category:
 
     .. index::
        single: unused binds, warning
@@ -936,6 +1271,10 @@ of ``-W(no-)*``.
     it forces evaluation, and is useful as an alternative to ``seq``.
 
 .. ghc-flag:: -Wunused-imports
+    :shortdesc: warn about unnecessary imports
+    :type: dynamic
+    :reverse: -Wno-unused-imports
+    :category:
 
     .. index::
        single: unused imports, warning
@@ -947,6 +1286,10 @@ of ``-W(no-)*``.
     declarations, which are anonymous in Haskell.
 
 .. ghc-flag:: -Wunused-matches
+    :shortdesc: warn about variables in patterns that aren't used
+    :type: dynamic
+    :reverse: -Wno-unused-matches
+    :category:
 
     .. index::
        single: unused matches, warning
@@ -965,6 +1308,11 @@ of ``-W(no-)*``.
     :ghc-flag:`-Wunused-type-patterns` flag.
 
 .. ghc-flag:: -Wunused-do-bind
+    :shortdesc: warn about do bindings that appear to throw away values of types
+        other than ``()``
+    :type: dynamic
+    :reverse: -Wno-unused-do-bind
+    :category:
 
     .. index::
        single: unused do binding, warning
@@ -986,6 +1334,11 @@ of ``-W(no-)*``.
         do { mapM_ popInt xs ; return 10 }
 
 .. ghc-flag:: -Wunused-type-patterns
+    :shortdesc: warn about unused type variables which arise from patterns
+        in type family and data family instances
+    :type: dynamic
+    :reverse: -Wno-unused-type-patterns
+    :category:
 
     .. index::
        single: unused type patterns, warning
@@ -1008,6 +1361,11 @@ of ``-W(no-)*``.
     documentation harder to read.
 
 .. ghc-flag:: -Wunused-foralls
+    :shortdesc: warn about type variables in user-written
+        ``forall``\\s that are unused
+    :type: dynamic
+    :reverse: -Wno-unused-foralls
+    :category:
 
     .. index::
        single: unused foralls, warning
@@ -1021,6 +1379,11 @@ of ``-W(no-)*``.
     would report ``a`` and ``c`` as unused.
 
 .. ghc-flag:: -Wwrong-do-bind
+    :shortdesc: warn about do bindings that appear to throw away monadic values
+        that you should have bound instead
+    :type: dynamic
+    :reverse: -Wno-wrong-do-bind
+    :category:
 
     .. index::
        single: apparently erroneous do binding, warning
@@ -1044,12 +1407,21 @@ of ``-W(no-)*``.
         do { popInt 10 ; return 10 }
 
 .. ghc-flag:: -Winline-rule-shadowing
+    :shortdesc: Warn if a rewrite RULE might fail to fire because the
+        function might be inlined before the rule has a chance to fire.
+        See :ref:`rules-inline`.
+    :type: dynamic
+    :reverse: -Wno-inline-rule-shadowing
+    :category:
 
     Warn if a rewrite RULE might fail to fire because the function might
     be inlined before the rule has a chance to fire. See
     :ref:`rules-inline`.
 
 .. ghc-flag:: -Wcpp-undef
+    :shortdesc: warn on uses of the `#if` directive on undefined identifiers
+    :type: dynamic
+    :category:
 
     :since: 8.2
 
@@ -1058,12 +1430,24 @@ of ``-W(no-)*``.
     undefined identifiers.
 
 .. ghc-flag:: -Wunbanged-strict-patterns
+    :shortdesc: warn on pattern bind of unlifted variable that is neither bare
+        nor banged
+    :type: dynamic
+    :reverse: -Wno-unbanged-strict-patterns
+    :category:
 
     This flag warns whenever you write a pattern that binds a variable whose
     type is unlifted, and yet the pattern is not a bang pattern nor a bare variable.
     See :ref:`glasgow-unboxed` for information about unlifted types.
 
 .. ghc-flag:: -Wmissing-home-modules
+    :shortdesc: warn when encountering a home module imported, but not listed
+        on the command line. Useful for cabal to ensure GHC won't pick
+        up modules, not listed neither in ``exposed-modules``, nor in
+        ``other-modules``.
+    :type: dynamic
+    :reverse: -Wno-missing-home-modules
+    :category:
 
     :since: 8.2
 
diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index 6dde0ee423..a963ead8f1 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -258,6 +258,10 @@ to produce an executable.
 The available mode flags are:
 
 .. ghc-flag:: --interactive
+    :shortdesc: Interactive mode - normally used by just running ``ghci``;
+        see :ref:`ghci` for details.
+    :type: mode
+    :category: modes
 
     .. index::
        single: interactive mode
@@ -267,6 +271,11 @@ The available mode flags are:
     mode is described in more detail in :ref:`ghci`.
 
 .. ghc-flag:: --make
+    :shortdesc: Build a multi-module Haskell program, automatically figuring out
+        dependencies. Likely to be much easier, and faster, than using
+        ``make``; see :ref:`make-mode` for details.
+    :type: mode
+    :category: modes
 
     .. index::
        single: make mode; of GHC
@@ -282,6 +291,9 @@ The available mode flags are:
     option can be omitted.
 
 .. ghc-flag:: -e ⟨expr⟩
+    :shortdesc: Evaluate ``expr``; see :ref:`eval-mode` for details.
+    :type: mode
+    :category: modes
 
     .. index::
        single: eval mode; of GHC
@@ -292,15 +304,42 @@ The available mode flags are:
     details.
 
 .. ghc-flag:: -E
-              -C
-              -S
-              -c
+    :shortdesc: Stop after preprocessing (``.hspp`` file)
+    :type: mode
+    :category: phases
+
+    Stop after preprocessing (``.hspp`` file)
+
+.. ghc-flag:: -C
+    :shortdesc: Stop after generating C (``.hc`` file)
+    :type: mode
+    :category: phases
+    
+    Stop after generating C (``.hc`` file)
+
+.. ghc-flag:: -S
+    :shortdesc: Stop after generating assembly (``.s`` file)
+    :type: mode
+    :category: phases
+
+    Stop after generating assembly (``.s`` file)
+
+.. ghc-flag:: -c
+    :shortdesc: Stop after generating object (``.o``) file
+    :type: mode
+    :category: phases
+    
+    Stop after generating object (``.o``) file
 
     This is the traditional batch-compiler mode, in which GHC can
     compile source files one at a time, or link objects together into an
     executable. See :ref:`options-order`.
 
 .. ghc-flag:: -M
+    :shortdesc: generate dependency information suitable for use in a
+        ``Makefile``; see :ref:`makefile-dependencies` for details.
+    :type: mode
+    :category: modes
 
     .. index::
         single: dependency-generation mode; of GHC
@@ -310,6 +349,10 @@ The available mode flags are:
     See :ref:`makefile-dependencies`.
 
 .. ghc-flag:: --frontend ⟨module⟩
+    :shortdesc: run GHC with the given frontend plugin; see
+        :ref:`frontend_plugins` for details.
+    :type: mode
+    :category: modes
 
     .. index::
         single: frontend plugins; using
@@ -318,6 +361,9 @@ The available mode flags are:
     details.
 
 .. ghc-flag:: --mk-dll
+    :shortdesc: DLL-creation mode (Windows only)
+    :type: mode
+    :category: modes
 
     .. index::
        single: DLL-creation mode
@@ -326,39 +372,63 @@ The available mode flags are:
 
 .. ghc-flag:: --help
               -?
+    :shortdesc: Display help
+    :type: mode
+    :category: modes
 
     Cause GHC to spew a long usage message to standard output and then
     exit.
 
 .. ghc-flag:: --show-iface ⟨file⟩
+    :shortdesc: display the contents of an interface file.
+    :type: mode
+    :category: modes
 
     Read the interface in ⟨file⟩ and dump it as text to ``stdout``. For
     example ``ghc --show-iface M.hi``.
 
 .. ghc-flag:: --supported-extensions
               --supported-languages
+    :shortdesc: display the supported language extensions
+    :type: mode
+    :category: modes
 
     Print the supported language extensions.
 
 .. ghc-flag:: --show-options
+    :shortdesc: display the supported command line options
+    :type: mode
+    :category: modes
 
     Print the supported command line options. This flag can be used for
     autocompletion in a shell.
 
 .. ghc-flag:: --info
+    :shortdesc: display information about the compiler
+    :type: mode
+    :category: modes
 
     Print information about the compiler.
 
 .. ghc-flag:: --version
               -V
+    :shortdesc: display GHC version
+    :type: mode
+    :category: modes
 
     Print a one-line string including GHC's version number.
 
 .. ghc-flag:: --numeric-version
+    :shortdesc: display GHC version (numeric only)
+    :type: mode
+    :category: modes
 
     Print GHC's numeric version number only.
 
 .. ghc-flag:: --print-libdir
+    :shortdesc: display GHC library directory
+    :type: mode
+    :category: modes
 
     .. index::
        single: libdir
@@ -446,6 +516,10 @@ directory; the :ghc-flag:`-i` option can be used to add directories to the
 search path (see :ref:`search-path`).
 
 .. ghc-flag:: -j[⟨n⟩]
+    :shortdesc: When compiling with :ghc-flag:`--make`, compile ⟨n⟩ modules
+        in parallel.
+    :type: dynamic
+    :category: misc
 
     Perform compilation in parallel when possible. GHC will use up to ⟨N⟩
     threads during compilation. If N is omitted, then it defaults to the
@@ -554,6 +628,9 @@ suffix. This behaviour can be overridden using the :ghc-flag:`-x ⟨suffix⟩`
 option:
 
 .. ghc-flag:: -x ⟨suffix⟩
+    :shortdesc: Override default behaviour for source files
+    :type: dynamic
+    :category: phases
 
     Causes all files following this option on the command line to be
     processed as if they had the suffix ⟨suffix⟩. For example, to
@@ -572,6 +649,9 @@ See also the ``--help``, ``--version``, ``--numeric-version``, and
 ``--print-libdir`` modes in :ref:`modes`.
 
 .. ghc-flag:: -v
+    :shortdesc: verbose mode (equivalent to ``-v3``)
+    :type: dynamic
+    :category: verbosity
 
     The :ghc-flag:`-v` option makes GHC *verbose*: it reports its version number
     and shows (on stderr) exactly how it invokes each phase of the
@@ -583,8 +663,10 @@ See also the ``--help``, ``--version``, ``--numeric-version``, and
     Knowing that you ran the right bits in the right order is always the
     first thing we want to verify.
 
-.. ghc-flag:: -v ⟨n⟩
-    :noindex:
+.. ghc-flag:: -v⟨n⟩
+    :shortdesc: set verbosity level
+    :type: dynamic
+    :category: verbosity
 
     To provide more control over the compiler's verbosity, the ``-v``
     flag takes an optional numeric argument. Specifying ``-v`` on its
@@ -613,12 +695,19 @@ See also the ``--help``, ``--version``, ``--numeric-version``, and
         (excluding preprocessed and C/assembly files).
 
 .. ghc-flag:: -fprint-potential-instances
+    :shortdesc: display all available instances in type error messages
+    :type: dynamic
+    :reverse: -fno-print-potential-instances
+    :category: verbosity
 
     When GHC can't find an instance for a class, it displays a short
     list of some in the instances it knows about. With this flag it
     prints *all* the instances it knows about.
 
 .. ghc-flag:: -fhide-source-paths
+    :shortdesc: hide module source and object paths
+    :type: dynamic
+    :category: verbosity
 
     Starting with minimal verbosity (``-v1``, see :ghc-flag:`-v`), GHC
     displays the name, the source path and the target path of each compiled
@@ -629,6 +718,11 @@ The following flags control the way in which GHC displays types in error
 messages and in GHCi:
 
 .. ghc-flag:: -fprint-unicode-syntax
+    :shortdesc: Use unicode syntax when printing expressions, types and kinds.
+        See also :ghc-flag:`-XUnicodeSyntax`
+    :type: dynamic
+    :reverse: -fno-print-unicode-syntax
+    :category: verbosity
 
     When enabled GHC prints type signatures using the unicode symbols from the
     :ghc-flag:`-XUnicodeSyntax` extension. For instance,
@@ -642,6 +736,11 @@ messages and in GHCi:
 .. _pretty-printing-types:
 
 .. ghc-flag:: -fprint-explicit-foralls
+    :shortdesc: Print explicit ``forall`` quantification in types.
+        See also :ghc-flag:`-XExplicitForAll`
+    :type: dynamic
+    :reverse: -fno-print-explicit-foralls
+    :category: verbosity
 
     Using :ghc-flag:`-fprint-explicit-foralls` makes
     GHC print explicit ``forall`` quantification at the top level of a
@@ -678,6 +777,11 @@ messages and in GHCi:
                    -- Defined in Data.Type.Equality
 
 .. ghc-flag:: -fprint-explicit-kinds
+    :shortdesc: Print explicit kind foralls and kind arguments in types.
+        See also :ghc-flag:`-XKindSignatures`
+    :type: dynamic
+    :reverse: -fno-print-explicit-kinds
+    :category: verbosity
 
     Using :ghc-flag:`-fprint-explicit-kinds` makes GHC print kind arguments in
     types, which are normally suppressed. This can be important when you
@@ -694,6 +798,11 @@ messages and in GHCi:
         MkT :: forall (k :: BOX) (a :: k). T k a
 
 .. 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: verbosity
 
     When :ghc-flag:`-fprint-explicit-runtime-reps` is enabled, GHC prints
     ``RuntimeRep`` type variables for levity-polymorphic types.
@@ -710,6 +819,10 @@ messages and in GHCi:
              (a -> b) -> a -> b
 
 .. ghc-flag:: -fprint-explicit-coercions
+    :shortdesc: Print coercions in types
+    :type: dynamic
+    :reverse: -fno-print-explicit-coercions
+    :category: verbosity
 
     Using :ghc-flag:`-fprint-explicit-coercions` makes GHC print coercions in
     types. When trying to prove the equality between types of different
@@ -717,6 +830,10 @@ messages and in GHCi:
     see these, as they are meant to be internal.
 
 .. ghc-flag:: -fprint-equality-relations
+    :shortdesc: Distinguish between equality relations when printing
+    :type: dynamic
+    :reverse: -fno-print-equality-relations
+    :category: verbosity
 
     Using :ghc-flag:`-fprint-equality-relations` tells GHC to distinguish between
     its equality relations when printing. For example, ``~`` is homogeneous
@@ -729,6 +846,10 @@ messages and in GHCi:
     prints all of these as ``~``. See also :ref:`equality-constraints`.
 
 .. ghc-flag:: -fprint-expanded-synonyms
+    :shortdesc: In type errors, also print type-synonym-expanded types.
+    :type: dynamic
+    :reverse: -fno-print-expanded-synonyms
+    :category: verbosity
 
     When enabled, GHC also prints type-synonym-expanded types in type
     errors. For example, with this type synonyms: ::
@@ -757,6 +878,10 @@ messages and in GHCi:
           Actual type: ST s Bool
 
 .. ghc-flag:: -fprint-typechecker-elaboration
+    :shortdesc: Print extra information from typechecker.
+    :type: dynamic
+    :reverse: -fno-print-typechecker-elaboration
+    :category: verbosity
 
     When enabled, GHC also prints extra information from the typechecker in
     warnings. For example: ::
@@ -794,6 +919,9 @@ messages and in GHCi:
         or by using the flag -fno-warn-unused-do-bind
 
 .. ghc-flag:: -fdiagnostics-color=⟨always|auto|never⟩
+    :shortdesc: Use colors in error messages
+    :type: dynamic
+    :category: verbosity
 
     Causes GHC to display error messages with colors.  To do this, the
     terminal must have support for ANSI color codes, or else garbled text will
@@ -833,13 +961,20 @@ messages and in GHCi:
     or ``always``, which is equivalent to setting the corresponding
     ``-fdiagnostics-color`` flag but with lower precedence.
 
-.. ghc-flag:: -f[no-]diagnostics-show-caret
+.. ghc-flag:: -fdiagnostics-show-caret
+    :shortdesc: Whether to show snippets of original source code
+    :type: dynamic
+    :reverse: -fno-diagnostics-show-caret
+    :category: verbosity
 
     Controls whether GHC displays a line of the original source code where the
     error was detected.  This also affects the associated caret symbol that
     points at the region of code at fault.  The flag is on by default.
 
 .. ghc-flag:: -ferror-spans
+    :shortdesc: Output full span in error messages
+    :type: dynamic
+    :category: verbosity
 
     Causes GHC to emit the full source span of the syntactic entity
     relating to an error message. Normally, GHC emits the source
@@ -872,11 +1007,17 @@ messages and in GHCi:
     (i.e. this is how Emacs does it).
 
 .. ghc-flag:: -H ⟨size⟩
+    :shortdesc: Set the minimum size of the heap to ⟨size⟩
+    :type: dynamic
+    :category: misc
 
     Set the minimum size of the heap to ⟨size⟩. This option is
     equivalent to ``+RTS -Hsize``, see :ref:`rts-options-gc`.
 
 .. ghc-flag:: -Rghc-timing
+    :shortdesc: Summarise timing stats for GHC (same as ``+RTS -tstderr``).
+    :type: dynamic
+    :category: verbosity
 
     Prints a one-line summary of timing statistics for the GHC run. This
     option is equivalent to ``+RTS -tstderr``, see
@@ -895,6 +1036,9 @@ Platform-specific Flags
 Some flags only make sense for particular target platforms.
 
 .. ghc-flag:: -msse2
+    :shortdesc: (x86 only) Use SSE2 for floating-point operations
+    :type: dynamic
+    :category: platform-options
 
     (x86 only, added in GHC 7.0.1) Use the SSE2 registers and
     instruction set to implement floating point operations when using
@@ -909,6 +1053,9 @@ Some flags only make sense for particular target platforms.
     SSE2 is unconditionally used on x86-64 platforms.
 
 .. ghc-flag:: -msse4.2
+    :shortdesc: (x86 only) Use SSE4.2 for floating-point operations
+    :type: dynamic
+    :category: platform-options
 
     (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/docs/users_guide/what_glasgow_exts_does.rst b/docs/users_guide/what_glasgow_exts_does.rst
new file mode 100644
index 0000000000..9a3fc14fd5
--- /dev/null
+++ b/docs/users_guide/what_glasgow_exts_does.rst
@@ -0,0 +1,33 @@
+.. hlist::
+
+ * ``-XConstrainedClassMethods``
+ * ``-XDeriveDataTypeable``
+ * ``-XDeriveFoldable``
+ * ``-XDeriveFunctor``
+ * ``-XDeriveGeneric``
+ * ``-XDeriveTraversable``
+ * ``-XEmptyDataDecls``
+ * ``-XExistentialQuantification``
+ * ``-XExplicitNamespaces``
+ * ``-XFlexibleContexts``
+ * ``-XFlexibleInstances``
+ * ``-XForeignFunctionInterface``
+ * ``-XFunctionalDependencies``
+ * ``-XGeneralizedNewtypeDeriving``
+ * ``-XImplicitParams``
+ * ``-XKindSignatures``
+ * ``-XLiberalTypeSynonyms``
+ * ``-XMagicHash``
+ * ``-XMultiParamTypeClasses``
+ * ``-XParallelListComp``
+ * ``-XPatternGuards``
+ * ``-XPostfixOperators``
+ * ``-XRankNTypes``
+ * ``-XRecursiveDo``
+ * ``-XScopedTypeVariables``
+ * ``-XStandaloneDeriving``
+ * ``-XTypeOperators``
+ * ``-XTypeSynonymInstances``
+ * ``-XUnboxedTuples``
+ * ``-XUnicodeSyntax``
+ * ``-XUnliftedFFITypes``