Docs: use :default: and :ghc-ticket:

8 files changed, 62 insertions, 56 deletions

diff --git a/docs/users_guide/exts/defer_type_errors.rst b/docs/users_guide/exts/defer_type_errors.rst
index 1c644c5eda..b60be4557d 100644
--- a/docs/users_guide/exts/defer_type_errors.rst
+++ b/docs/users_guide/exts/defer_type_errors.rst
@@ -116,8 +116,7 @@ In a few cases, equality constraints cannot be deferred.  Specifically:
 
   This type signature contains a kind error which cannot be deferred.
 
-- Type equalities under a forall (c.f. `#14605
-  <https://gitlab.haskell.org/ghc/ghc/issues/14605>`_).
+- Type equalities under a forall (c.f. :ghc-ticket:`14605`).
 
 - Kind errors in a visible type application. e.g. ::
 
diff --git a/docs/users_guide/exts/ffi.rst b/docs/users_guide/exts/ffi.rst
index c05b2d26f8..56f55352ef 100644
--- a/docs/users_guide/exts/ffi.rst
+++ b/docs/users_guide/exts/ffi.rst
@@ -360,7 +360,7 @@ and functions like :base-ref:`System.Timeout.timeout` will not work.
 Finally, after the ``interruptible`` foreign call returns into Haskell, the
 Haskell code should allow exceptions to be raised
 (``Control.Exception``'s ``allowInterrupt``, or ``interruptible yield``
-for non-``-threaded``, see https://gitlab.haskell.org/ghc/ghc/issues/8684),
+for non-``-threaded``, see :ghc-ticket:`8684`),
 and implement the ``EINTR``-retrying in Haskell
 (e.g. using e.g. :base-ref:`Foreign.C.Error.throwErrnoIfMinus1Retry`).
 
diff --git a/docs/users_guide/exts/pattern_synonyms.rst b/docs/users_guide/exts/pattern_synonyms.rst
index 6055dffe8e..198cc41358 100644
--- a/docs/users_guide/exts/pattern_synonyms.rst
+++ b/docs/users_guide/exts/pattern_synonyms.rst
@@ -418,7 +418,7 @@ Note also the following points
          pattern P x y v <- MkT True x y (v::a)
 
    Here the universal type variable `a` scopes over the definition of `P`,
-   but the existential `b` does not.  (c.f. discussion on #14998.)
+   but the existential `b` does not.  (c.f. discussion on :ghc-ticket:`14998`.)
 
 -  For a bidirectional pattern synonym, a use of the pattern synonym as
    an expression has the type
diff --git a/docs/users_guide/exts/primitives.rst b/docs/users_guide/exts/primitives.rst
index 620b12c24e..4f61f75f93 100644
--- a/docs/users_guide/exts/primitives.rst
+++ b/docs/users_guide/exts/primitives.rst
@@ -424,7 +424,7 @@ argument either way), GHC currently disallows the more general type
 ``PEither @l Int Bool -> Bool``. This is a consequence of the
 `representation-polymorphic binder restriction <#representation-polymorphism-restrictions>`__,
 
-Due to `ticket 19487 <https://gitlab.haskell.org/ghc/ghc/-/issues/19487>`, it's
+Due to :ghc-ticket:`19487`, it's
 currently not possible to declare levity-polymorphic data types with nullary
 data constructors. There's a workaround, though: ::
 
diff --git a/docs/users_guide/exts/safe_haskell.rst b/docs/users_guide/exts/safe_haskell.rst
index 7cbfdc0ef9..22508d5d7c 100644
--- a/docs/users_guide/exts/safe_haskell.rst
+++ b/docs/users_guide/exts/safe_haskell.rst
@@ -784,6 +784,7 @@ And five warning flags:
     :category: warnings
 
     :since: 8.10.1
+    :default: off
 
     .. index::
        single: safe haskell imports, warning
@@ -809,7 +810,6 @@ And five warning flags:
     ``B``, it will cause compilation error of ``A``.  When
     :ghc-flag:`-Winferred-safe-imports` is enabled, the compiler will emit a
     warning about this.
-    This option is off by default.
 
 .. ghc-flag:: -Wmissing-safe-haskell-mode
     :shortdesc: warn when the Safe Haskell mode is not explicitly specified.
@@ -818,13 +818,13 @@ And five warning flags:
     :category: warnings
 
     :since: 8.10.1
+    :default: off
 
     .. index::
        single: safe haskell mode, missing
 
     The compiler will warn when none of  :extension:`Safe`,
     :extension:`Trustworthy` or :extension:`Unsafe` is specified.
-    This option is off by default.
 
 .. _safe-compilation:
 
diff --git a/docs/users_guide/exts/undecidable_super_classes.rst b/docs/users_guide/exts/undecidable_super_classes.rst
index ed55da29a9..88ae6b53f0 100644
--- a/docs/users_guide/exts/undecidable_super_classes.rst
+++ b/docs/users_guide/exts/undecidable_super_classes.rst
@@ -42,7 +42,7 @@ But superclass constraints like these are sometimes useful, and the conservative
 check is annoying where no actual recursion is involved.
 
 Moreover genuinely-recursive superclasses are sometimes useful. Here's a real-life
-example (#10318) ::
+example (:ghc-ticket:`10318`) ::
 
      class (Frac (Frac a) ~ Frac a,
             Fractional (Frac a),
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index 04e01c870c..1f658e8167 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -237,11 +237,11 @@ it is shown.
     :reverse: -fno-show-warning-groups
     :category:
 
+    :default: off
+
     When showing which flag controls a warning, also show the
     respective warning group flag(s) that warning is contained in.
 
-    This option is off by default.
-
 The full set of warning options is described below. To turn off any
 warning, simply give the corresponding ``-Wno-...`` option on the
 command line. For backwards compatibility with GHC versions prior to 8.0,
@@ -314,11 +314,11 @@ of ``-W(no-)*``.
 
     :since: 8.4
 
+    :default: on
+
     Causes a warning to be reported when a type error is deferred until
     runtime. See :ref:`defer-type-errors`
 
-    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
@@ -394,25 +394,25 @@ of ``-W(no-)*``.
 
     :since: 7.10
 
+    :default: on
+
     Determines whether the compiler reports holes in partial type
     signatures as warnings. Has no effect unless
     :extension:`PartialTypeSignatures` is enabled, which controls whether
     errors should be generated for holes in types or not. See
     :ref:`partial-type-signatures`.
 
-    This warning is on by default.
-
 .. ghc-flag:: -fhelpful-errors
     :shortdesc: Make suggestions for mis-spelled names.
     :type: dynamic
     :reverse: -fno-helpful-errors
     :category:
 
+    :default: on
+
     When a name or package is not found in scope, make suggestions for
     the name or package you might have meant instead.
 
-    This option is on by default.
-
 .. ghc-flag:: -Wunrecognised-pragmas
     :shortdesc: warn about uses of pragmas that GHC doesn't recognise
     :type: dynamic
@@ -421,13 +421,13 @@ of ``-W(no-)*``.
 
     :since: 6.10
 
+    :default: on
+
     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
     recognises pragmas known to be used by other tools, e.g.
     ``OPTIONS_HUGS`` and ``DERIVE``.
 
-    This option is on by default.
-
 .. ghc-flag:: -Wmissed-specialisations
     :shortdesc: warn when specialisation of an imported, overloaded function
         fails.
@@ -437,6 +437,8 @@ of ``-W(no-)*``.
 
     :since: 8.0
 
+    :default: off
+
     Emits a warning if GHC cannot specialise an overloaded function, usually
     because the function needs an ``INLINABLE`` pragma. Reports when the
     situation arises during specialisation of an imported function.
@@ -449,8 +451,6 @@ of ``-W(no-)*``.
     Note that this warning will not throw errors if used with
     :ghc-flag:`-Werror`.
 
-    This option is off by default.
-
 .. ghc-flag:: -Wmissed-specializations
     :shortdesc: alias for :ghc-flag:`-Wmissed-specialisations`
     :type: dynamic
@@ -466,6 +466,8 @@ of ``-W(no-)*``.
 
     :since: 8.0
 
+    :default: off
+
     Emits a warning if GHC cannot specialise an overloaded function, usually
     because the function needs an ``INLINABLE`` pragma. Reports
     all such situations.
@@ -473,8 +475,6 @@ of ``-W(no-)*``.
     Note that this warning will not throw errors if used with
     :ghc-flag:`-Werror`.
 
-    This option is off by default.
-
 .. ghc-flag:: -Wall-missed-specializations
     :shortdesc: alias for :ghc-flag:`-Wall-missed-specialisations`
     :type: dynamic
@@ -491,6 +491,8 @@ of ``-W(no-)*``.
 
     :since: 6.10
 
+    :default: on
+
     .. index::
        pair: deprecations; warnings
 
@@ -498,8 +500,6 @@ of ``-W(no-)*``.
     a ``WARNING`` or ``DEPRECATED pragma`` is used. See
     :ref:`warning-deprecated-pragma` for more details on the pragmas.
 
-    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`
@@ -507,6 +507,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-deprecations
     :category:
 
+    :default: on
+
     .. index::
        single: deprecations
 
@@ -515,8 +517,6 @@ of ``-W(no-)*``.
     :ref:`warning-deprecated-pragma` for more details on the pragmas.
     An alias for :ghc-flag:`-Wwarnings-deprecations`.
 
-    This option is on by default.
-
 .. ghc-flag:: -Wnoncanonical-monad-instances
     :shortdesc: warn when ``Applicative`` or ``Monad`` instances have
         noncanonical definitions of ``return``, ``pure``, ``(>>)``,
@@ -528,6 +528,8 @@ of ``-W(no-)*``.
 
     :since: 8.0
 
+    :default: off
+
     Warn if noncanonical ``Applicative`` or ``Monad`` instances
     declarations are detected.
 
@@ -544,8 +546,6 @@ of ``-W(no-)*``.
      * Warn if ``pure`` is defined backwards (i.e. ``pure = return``).
      * Warn if ``(*>)`` is defined backwards (i.e. ``(*>) = (>>)``).
 
-    This option is off by default.
-
 .. ghc-flag:: -Wnoncanonical-monadfail-instances
     :shortdesc: *(deprecated)*
         warn when ``Monad`` or ``MonadFail`` instances have
@@ -635,14 +635,14 @@ of ``-W(no-)*``.
 
     :since: 6.10
 
+    :default: on
+
     .. index::
        single: deprecated flags
 
     Causes a warning to be emitted when a deprecated command-line flag
     is used.
 
-    This option is on by default.
-
 .. ghc-flag:: -Wunsupported-calling-conventions
     :shortdesc: warn about use of an unsupported calling convention
     :type: dynamic
@@ -827,6 +827,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-duplicate-exports
     :category:
 
+    :default: on
+
     .. index::
        single: duplicate exports, warning
        single: export lists, duplicates
@@ -836,8 +838,6 @@ of ``-W(no-)*``.
     to avoid the continued export of a definition after you've deleted
     (one) mention of it in the export list.
 
-    This option is on by default.
-
 .. ghc-flag:: -Whi-shadowing
     :shortdesc: *(deprecated)*
         warn when a ``.hi`` file in the current directory shadows a library
@@ -917,6 +917,8 @@ of ``-W(no-)*``.
 
     :since: 6.8
 
+    :default: off
+
     .. index::
        single: implicit prelude, warning
 
@@ -933,8 +935,6 @@ of ``-W(no-)*``.
     to the actual Prelude module, regardless of the imports of the module
     being compiled).
 
-    This warning is off by default.
-
 .. ghc-flag:: -Wincomplete-patterns
     :shortdesc: warn when a pattern match could fail
     :type: dynamic
@@ -1035,7 +1035,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-missing-deriving-strategies
     :category:
 
-    :since: 8.8
+    :since: 8.8.1
+    :default: off
 
     The datatype below derives the ``Eq`` typeclass, but doesn't specify a
     strategy. When :ghc-flag:`-Wmissing-deriving-strategies` is enabled,
@@ -1047,8 +1048,7 @@ of ``-W(no-)*``.
     The compiler will warn here that the deriving clause doesn't specify a
     strategy. If the warning is enabled, but :extension:`DerivingStrategies` is
     not enabled, the compiler will suggest turning on the
-    :extension:`DerivingStrategies` extension. This option is not on by default,
-    having to be turned on manually or with :ghc-flag:`-Weverything`.
+    :extension:`DerivingStrategies` extension.
 
 .. ghc-flag:: -Wmissing-fields
     :shortdesc: warn when fields of a record are uninitialised
@@ -1126,13 +1126,15 @@ of ``-W(no-)*``.
     :reverse: -Wno-missing-methods
     :category:
 
+    :default: on
+
     .. index::
        single: missing methods, warning
        single: methods, missing
 
-    This option is on by default, and warns you whenever an instance
-    declaration is missing one or more methods, and the corresponding
-    class declaration has no default declaration for them.
+    This option warns you whenever an instance declaration is missing
+    one or more methods, and the corresponding class declaration has no default
+    declaration for them.
 
     The ``MINIMAL`` pragma can be used to change which combination of
     methods will be required for instances of a particular class. See
@@ -1144,13 +1146,14 @@ of ``-W(no-)*``.
     :reverse: -Wno-missing-signatures
     :category:
 
+    :default: off
+
     .. index::
        single: type signatures, missing
 
     If you would like GHC to check that every top-level function/value
     has a type signature, use the :ghc-flag:`-Wmissing-signatures` option.
-    As part of the warning GHC also reports the inferred type. The
-    option is off by default.
+    As part of the warning GHC also reports the inferred type.
 
 .. ghc-flag:: -Wmissing-exported-sigs
     :shortdesc: *(deprecated)*
@@ -1177,6 +1180,8 @@ of ``-W(no-)*``.
 
     :since: 8.0
 
+    :default: off
+
     .. index::
        single: type signatures, missing
 
@@ -1186,7 +1191,7 @@ of ``-W(no-)*``.
     option. If this option is used in conjunction with
     :ghc-flag:`-Wmissing-signatures` then every top-level function/value
     must have a type signature. As part of the warning GHC also
-    reports the inferred type. The option is off by default.
+    reports the inferred type.
 
 .. ghc-flag:: -Wmissing-local-sigs
     :shortdesc: *(deprecated)*
@@ -1227,6 +1232,8 @@ of ``-W(no-)*``.
 
     :since: 8.0
 
+    :default: off
+
     .. index::
          single: type signatures, missing, pattern synonyms
 
@@ -1236,7 +1243,7 @@ of ``-W(no-)*``.
     option is used in conjunction with
     :ghc-flag:`-Wmissing-exported-signatures` then only exported pattern
     synonyms must have a type signature. GHC also reports the inferred
-    type. This option is off by default.
+    type.
 
 .. ghc-flag:: -Wmissing-kind-signatures
     :shortdesc: warn when type declarations don't have kind signatures nor CUSKs
@@ -1245,6 +1252,7 @@ of ``-W(no-)*``.
     :category:
 
     :since: 9.2
+    :default: off
 
     .. index::
          single: kind signatures, missing
@@ -1262,8 +1270,6 @@ of ``-W(no-)*``.
     the parent class a standalone kind signature or CUSK is sufficient to fix
     the warning for the class's associated type families as well.
 
-    This option is off by default.
-
 .. ghc-flag:: -Wmissing-exported-pattern-synonym-signatures
     :shortdesc: warn about pattern synonyms without signatures, only if they
         are exported
@@ -1271,6 +1277,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-missing-exported-pattern-synonym-signatures
     :category:
 
+    :default: off
+
     .. index::
        single: type signatures, missing, pattern synonyms
 
@@ -1280,7 +1288,7 @@ of ``-W(no-)*``.
     option is used in conjunction with
     :ghc-flag:`-Wmissing-pattern-synonym-signatures` then every pattern synonym
     must have a type signature. As part of the warning GHC also reports the
-    inferred type. The option is off by default.
+    inferred type.
 
 .. ghc-flag:: -Wname-shadowing
     :shortdesc: warn when names are shadowed
@@ -1482,6 +1490,7 @@ of ``-W(no-)*``.
     :category:
 
     :since: 8.2
+    :default: on
 
     .. index::
        single: simplifiable class constraints, warning
@@ -1498,10 +1507,6 @@ of ``-W(no-)*``.
 
        f :: Eq a => a -> a
 
-    This option is on by default. As usual you can suppress it on a
-    per-module basis with :ghc-flag:`-Wno-simplifiable-class-constraints
-    <-Wsimplifiable-class-constraints>`.
-
 .. ghc-flag:: -Wtabs
     :shortdesc: warn if there are tabs in the source file
     :type: dynamic
@@ -1521,6 +1526,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-type-defaults
     :category:
 
+    :default: off
+
     .. index::
        single: defaulting mechanism, warning
 
@@ -1533,8 +1540,6 @@ of ``-W(no-)*``.
     ``Integer``. This may lead to differences in performance and
     behaviour, hence the usefulness of being non-silent about this.
 
-    This warning is off by default.
-
 .. ghc-flag:: -Wmonomorphism-restriction
     :shortdesc: warn when the Monomorphism Restriction is applied
     :type: dynamic
@@ -1543,6 +1548,8 @@ of ``-W(no-)*``.
 
     :since: 6.8
 
+    :default: off
+
     .. index::
        single: monomorphism restriction, warning
 
@@ -1551,8 +1558,6 @@ of ``-W(no-)*``.
     give rise to unexpected behaviour, so it can be helpful to have an
     explicit warning that it is being applied.
 
-    This warning is off by default.
-
 .. ghc-flag:: -Wunsupported-llvm-version
     :shortdesc: Warn when using :ghc-flag:`-fllvm` with an unsupported
         version of LLVM.
diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index dee39d4d94..6660dfa4d5 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -1195,9 +1195,11 @@ messages and in GHCi:
     :reverse: -fno-diagnostics-show-caret
     :category: verbosity
 
+    :default: on
+
     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.
+    points at the region of code at fault.
 
 .. ghc-flag:: -ferror-spans
     :shortdesc: Output full span in error messages