Documentation fixes

- Add missing :since: for NondecreasingIndentation and OverlappingInstances
- Remove duplicated descriptions for Safe Haskell flags and
  UndecidableInstances. Instead, the sections contain a link.
- compare-flags: Also check for options supported by ghci.
  This uncovered two more that are not documented.
  The flag -smp was removed.
- Formatting fixes
- Remove the warning about -XNoImplicitPrelude - it was written in 1996,
  the extension is no longer dangerous.
- Fix misspelled :reverse: flags

Fixes #18958.

15 files changed, 40 insertions, 60 deletions

diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst
index cfcfc0417c..2f6eecd54a 100644
--- a/docs/users_guide/bugs.rst
+++ b/docs/users_guide/bugs.rst
@@ -121,6 +121,8 @@ Context-free syntax
     :shortdesc: Allow nested contexts to be at the same indentation level as
       its enclosing context.
 
+    :since: 7.2.1
+
     Allow nested contexts to be at the same indentation level as
     its enclosing context.
 
@@ -189,7 +191,7 @@ For example
 
 Will warn you with
 
-::
+.. code-block:: none
 
     • Could not deduce (MonadFail m)
         arising from a do statement
@@ -199,7 +201,7 @@ Will warn you with
                    mayFail :: forall (m :: * -> *). MonadIO m => m ()
 
 And indeed, since the `Monad <https://hackage.haskell.org/package/base-4.14.1.0/docs/Control-Monad.html#t:Monad>`__ class does not have the ``fail`` method anymore,
-we need to explicitly add ``(MonadFail m)`` to the contraints of the function.
+we need to explicitly add ``(MonadFail m)`` to the constraints of the function.
 
 .. _infelicities-decls:
 
@@ -337,10 +339,10 @@ Numbers, basic types, and built-in classes
     by:
 
     -  Whenever you make a ``Num`` instance of a type, also make
-        ``Show`` and ``Eq`` instances, and
+       ``Show`` and ``Eq`` instances, and
 
     -  Whenever you give a function, instance or class a ``Num t``
-        constraint, also give it ``Show t`` and ``Eq t`` constraints.
+       constraint, also give it ``Show t`` and ``Eq t`` constraints.
 
 ``Bits`` superclass
     The ``Bits`` class does not have a ``Num`` superclass. It
@@ -350,13 +352,13 @@ Numbers, basic types, and built-in classes
     You can make code that works with both Haskell 2010 and GHC by:
 
     -  Whenever you make a ``Bits`` instance of a type, also make a
-        ``Num`` instance, and
+       ``Num`` instance, and
 
     -  Whenever you give a function, instance or class a ``Bits t``
-        constraint, also give it a ``Num t`` constraint, and
+       constraint, also give it a ``Num t`` constraint, and
 
     -  Always define the ``bit``, ``testBit`` and ``popCount`` methods
-        in ``Bits`` instances.
+       in ``Bits`` instances.
 
 ``Read`` class methods
     The ``Read`` class has two extra methods, ``readPrec`` and
diff --git a/docs/users_guide/compare-flags.py b/docs/users_guide/compare-flags.py
index 81a11b90e5..e858e3011b 100755
--- a/docs/users_guide/compare-flags.py
+++ b/docs/users_guide/compare-flags.py
@@ -49,8 +49,11 @@ def read_documented_flags(doc_flags) -> Set[str]:
 
 def read_ghc_flags(ghc_path: str) -> Set[str]:
     ghc_output = subprocess.check_output([ghc_path, '--show-options'])
-    flags = {flag.strip() for flag in ghc_output.decode('UTF-8').split('\n')}
-    return {flag for flag in flags
+    ghci_output = subprocess.check_output([ghc_path, '--interactive', '--show-options'])
+
+    return {flag
+            for flag in ghc_output.decode('UTF-8').splitlines() +
+                        ghci_output.decode('UTF-8').splitlines()
             if not expected_undocumented(flag)
             if flag != ''}
 
@@ -61,9 +64,11 @@ def main() -> None:
     import argparse
     parser = argparse.ArgumentParser()
     parser.add_argument('--ghc', type=argparse.FileType('r'),
-                        help='path of GHC executable')
+                        help='path of GHC executable',
+                        required=True)
     parser.add_argument('--doc-flags', type=argparse.FileType(mode='r', encoding='UTF-8'),
-                        help='path of ghc-flags.txt output from Sphinx')
+                        help='path of ghc-flags.txt output from Sphinx',
+                        required=True)
     args = parser.parse_args()
 
     doc_flags = read_documented_flags(args.doc_flags)
diff --git a/docs/users_guide/debug-info.rst b/docs/users_guide/debug-info.rst
index 42afa9078f..e18f0287a4 100644
--- a/docs/users_guide/debug-info.rst
+++ b/docs/users_guide/debug-info.rst
@@ -268,7 +268,7 @@ In particular GHC produces the following DWARF sections,
 ``.debug_arange``
   Address range information necessary for efficient lookup in debug information.
 
-.. _dwarf_dies:
+.. _dwarf-dies:
 
 Debugging information entities
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/users_guide/expected-undocumented-flags.txt b/docs/users_guide/expected-undocumented-flags.txt
index fdcf1eaee2..aba8f87a8c 100644
--- a/docs/users_guide/expected-undocumented-flags.txt
+++ b/docs/users_guide/expected-undocumented-flags.txt
@@ -63,6 +63,7 @@
 -fghci-history
 -fghci-sandbox
 -fhistory-size
+-fimplicit-import-qualified
 -fimplicit-params
 -fimplicit-prelude
 -firrefutable-tuples
@@ -72,6 +73,7 @@
 -fmonomorphism-restriction
 -fnum-constant-folding
 -fpre-inlining
+-fprint-bind-contents
 -freduction-depth
 -frewrite-rules
 -fscoped-type-variables
@@ -110,7 +112,6 @@
 -rtsopts=ignoreAll
 -rtsopts=none
 -rtsopts=some
--smp
 -syslib
 -this-component-id
 -ticky-LNE
diff --git a/docs/users_guide/exts/instances.rst b/docs/users_guide/exts/instances.rst
index 01655bb05b..b8041cdb8d 100644
--- a/docs/users_guide/exts/instances.rst
+++ b/docs/users_guide/exts/instances.rst
@@ -324,6 +324,8 @@ Overlapping instances
 .. extension:: OverlappingInstances
     :shortdesc: Enable overlapping instances.
 
+    :since: 6.8.1
+
     Deprecated extension to weaken checks intended to ensure instance resolution
     termination.
 
diff --git a/docs/users_guide/exts/safe_imports.rst b/docs/users_guide/exts/safe_imports.rst
index 51a17f3bf8..be6016d032 100644
--- a/docs/users_guide/exts/safe_imports.rst
+++ b/docs/users_guide/exts/safe_imports.rst
@@ -3,30 +3,6 @@
 Safe imports
 ~~~~~~~~~~~~
 
-.. extension:: Safe
-    :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Safe mode.
-    :noindex:
-
-    :since: 7.2.1
-
-    Declare the Safe Haskell state of the current module.
-
-.. extension:: Trustworthy
-    :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Trustworthy mode.
-    :noindex:
-
-    :since: 7.2.1
-
-    Declare the Safe Haskell state of the current module.
-
-.. extension:: Unsafe
-    :shortdesc: Enable Safe Haskell Unsafe mode.
-    :noindex:
-
-    :since: 7.4.1
-
-    Declare the Safe Haskell state of the current module.
-
 With the :extension:`Safe`, :extension:`Trustworthy` and :extension:`Unsafe`
 language flags, GHC extends the import declaration syntax to take an optional
 ``safe`` keyword after the ``import`` keyword. This feature is part of the Safe
diff --git a/docs/users_guide/exts/template_haskell.rst b/docs/users_guide/exts/template_haskell.rst
index 075608d77c..8e617f3852 100644
--- a/docs/users_guide/exts/template_haskell.rst
+++ b/docs/users_guide/exts/template_haskell.rst
@@ -386,7 +386,7 @@ splices and quotations are supported.)
 .. ghc-flag:: -fenable-th-splice-warnings
     :shortdesc: Generate warnings for Template Haskell splices
     :type: dynamic
-    :reverse: -fno-enable-th-splices
+    :reverse: -fno-enable-th-splice-warnings
     :category: warnings
 
     Template Haskell splices won't be checked for warnings, because the code
diff --git a/docs/users_guide/exts/type_families.rst b/docs/users_guide/exts/type_families.rst
index 4843e35a80..15cf21e027 100644
--- a/docs/users_guide/exts/type_families.rst
+++ b/docs/users_guide/exts/type_families.rst
@@ -544,11 +544,6 @@ However see :ref:`ghci-decls` for the overlap rules in GHCi.
 Decidability of type synonym instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. extension:: UndecidableInstances
-    :noindex:
-
-    Relax restrictions on the decidability of type synonym family instances.
-
 In order to guarantee that type inference in the presence of type
 families is decidable, we need to place a number of additional restrictions
 on the formation of type instance declarations (c.f., Definition 5
@@ -577,9 +572,10 @@ as ``a ~ [F a]``, where a recursive occurrence of a type variable is
 underneath a family application and data constructor application - see
 the above mentioned paper for details.
 
-If the option :extension:`UndecidableInstances` is passed to the compiler, the
-above restrictions are not enforced and it is on the programmer to ensure
-termination of the normalisation of type families during type inference.
+If the option :extension:`UndecidableInstances` is passed to the compiler
+(see :ref:`undecidable-instances`), the above restrictions are not enforced
+and it is on the programmer to ensure termination of the normalisation
+of type families during type inference.
 
 Reducing type family applications
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/users_guide/exts/typed_holes.rst b/docs/users_guide/exts/typed_holes.rst
index 170824ee4f..7ad2d633a5 100644
--- a/docs/users_guide/exts/typed_holes.rst
+++ b/docs/users_guide/exts/typed_holes.rst
@@ -300,7 +300,7 @@ configurable by a few flags.
        in the output.
     :type: dynamic
     :category: verbosity
-    :reverse: -fno-type-of-hole-fits
+    :reverse: -fno-show-type-of-hole-fits
 
     :default: on
 
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst
index 78c74c5dc3..6ff9c1f20a 100644
--- a/docs/users_guide/ghci.rst
+++ b/docs/users_guide/ghci.rst
@@ -3303,6 +3303,7 @@ read:
 .. ghc-flag:: -ignore-dot-ghci
     :shortdesc: Disable reading of ``.ghci`` files
     :type: dynamic
+    :reverse: -no-ignore-dot-ghci
     :category:
 
     Don't read either :file:`./.ghci` or the other startup files when
diff --git a/docs/users_guide/gone_wrong.rst b/docs/users_guide/gone_wrong.rst
index 736bad36e0..5bf38a8cdb 100644
--- a/docs/users_guide/gone_wrong.rst
+++ b/docs/users_guide/gone_wrong.rst
@@ -38,9 +38,7 @@ When the compiler “does the wrong thing”
 Sensitivity to ``.hi`` interface files
     GHC is very sensitive about interface files. For example, if it
     picks up a non-standard ``Prelude.hi`` file, pretty terrible things
-    will happen. If you turn on
-    ``-XNoImplicitPrelude`` option, the compiler will
-    almost surely die, unless you know what you are doing.
+    will happen.
 
     Furthermore, as sketched below, you may have big problems running
     programs compiled using unstable interfaces.
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index 2b156d7328..797b10e8fe 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -727,7 +727,7 @@ Options affecting code generation
 
     Request that GHC emits verbose symbol tables which include local symbols
     for module-internal functions. These can be useful for tools like
-    :ref:`perf <https://perf.wiki.kernel.org/>` but increase object file sizes.
+    `perf <https://perf.wiki.kernel.org/>`__ but increase object file sizes.
     This is implied by :ghc-flag:`-g2 <-g>` and above.
 
     :ghc-flag:`-fno-expose-internal-symbols <-fexpose-internal-symbols>`
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index 62b5615aed..2463654837 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -429,7 +429,7 @@ compiled program.
 .. ghc-flag:: -fprof-auto-calls
     :shortdesc: Auto-add ``SCC``\\ s to all call sites
     :type: dynamic
-    :reverse: -fno-prof-auto-calls
+    :reverse: -fno-prof-auto
     :category:
 
     Adds an automatic ``SCC`` annotation to all *call sites*. This is
diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst
index d450fce141..ee5b1de95e 100644
--- a/docs/users_guide/using-optimisation.rst
+++ b/docs/users_guide/using-optimisation.rst
@@ -572,16 +572,15 @@ by saying ``-fno-wombat``.
     function calls.
 
 .. ghc-flag:: -fllvm-pass-vectors-in-regs
-    :shortdesc: Pass vector value in vector registers for function calls
+    :shortdesc: *(deprecated)* Does nothing
     :type: dynamic
-    :reverse: -fno-llvm-pass-vectors-in-regs
     :category:
 
     :default: on
 
-    Instructs GHC to use the platform's native vector registers to pass vector
-    arguments during function calls. As with all vector support, this requires
-    :ghc-flag:`-fllvm`.
+    This flag has no effect since GHC 8.8 - its behavior is always on.
+    It used to instruct GHC to use the platform's native vector registers
+    to pass vector arguments during function calls.
 
 .. ghc-flag:: -fmax-inline-alloc-size=⟨n⟩
     :shortdesc: *default: 128.* Set the maximum size of inline array allocations
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index 400db598ca..9b7f625bb6 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -640,7 +640,7 @@ of ``-W(no-)*``.
 .. ghc-flag:: -Wdodgy-foreign-imports
     :shortdesc: warn about dodgy foreign imports
     :type: dynamic
-    :reverse: -Wno-dodgy-foreign-import
+    :reverse: -Wno-dodgy-foreign-imports
     :category:
 
     Causes a warning to be emitted for foreign imports of the following
@@ -1007,7 +1007,7 @@ of ``-W(no-)*``.
     :shortdesc: warn when a module declaration does not explicitly list all
         exports
     :type: dynamic
-    :reverse: -fnowarn-missing-export-lists
+    :reverse: -Wno-missing-export-lists
     :category:
 
     :since: 8.4.1
@@ -1032,7 +1032,7 @@ of ``-W(no-)*``.
     :shortdesc: warn when an import declaration does not explicitly list all the
         names brought into scope
     :type: dynamic
-    :reverse: -fnowarn-missing-import-lists
+    :reverse: -Wno-missing-import-lists
     :category:
 
     .. index::