users-guide: Fix a variety of broken links and syntax

5 files changed, 30 insertions, 19 deletions

diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst
index 4372c97cef..009f699512 100644
--- a/docs/users_guide/bugs.rst
+++ b/docs/users_guide/bugs.rst
@@ -553,7 +553,7 @@ Bugs in GHC
          To increase the limit, use -fsimpl-tick-factor=N (default 100)
 
    with the panic being reported no matter how high a
-   :ghc-flag:`-fsimpl-tick-factor` you supply.
+   :ghc-flag:`-fsimpl-tick-factor <-fsimpl-tick-factor=⟨n⟩>` you supply.
 
    We have never found another class of programs, other than this
    contrived one, that makes GHC diverge, and fixing the problem would
@@ -585,7 +585,7 @@ Bugs in GHC
    libraries that come with GHC are probably built without this option,
    unless you built GHC yourself.
 
--  The :ghc-flag:`state hack <-fstate-hack>` optimization can result in
+-  The :ghc-flag:`state hack <-fno-state-hack>` optimization can result in
    non-obvious changes in evaluation ordering which may hide exceptions, even
    with :ghc-flag:`-fpedantic-bottoms` (see, e.g., :ghc-ticket:`7411`). For
    instance, ::
diff --git a/docs/users_guide/codegens.rst b/docs/users_guide/codegens.rst
index 936d7251dd..c68eff25d4 100644
--- a/docs/users_guide/codegens.rst
+++ b/docs/users_guide/codegens.rst
@@ -76,6 +76,13 @@ C Code Generator (``-fvia-C``)
    single: C code generator
    single: -fvia-C
 
+.. ghc-flag:: -fvia-C
+    :shortdesc: use the C code generator
+    :type: dynamic
+    :category: warnings
+
+    Use the C code generator. Only supposed in unregisterised GHC builds.
+
 This is the oldest code generator in GHC and is generally not included
 any more having been deprecated around GHC 7.0. Select it with the
 :ghc-flag:`-fvia-C` flag.
diff --git a/docs/users_guide/extending_ghc.rst b/docs/users_guide/extending_ghc.rst
index 5908df7bfd..ee816bf1b0 100644
--- a/docs/users_guide/extending_ghc.rst
+++ b/docs/users_guide/extending_ghc.rst
@@ -232,9 +232,10 @@ be reset with the :ghc-flag:`-fclear-plugins` option.
     :category: plugins
 
     Clear the list of plugins previously specified with
-    :ghc-flag:`-fplugin`. This is useful in GHCi where simply removing the
-    :ghc-flag:`-fplugin` options from the command line is not possible. Instead
-    `:set -fclear-plugins` can be used.
+    :ghc-flag:`-fplugin <-fplugin=⟨module⟩>`. This is useful in GHCi where
+    simply removing the :ghc-flag:`-fplugin <-fplugin=⟨module⟩>` options from
+    the command line is not possible. Instead `:set -fclear-plugins` can be
+    used.
 
 
 As an example, in order to load the plugin exported by ``Foo.Plugin`` in
diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index 36e29c5253..32818e8c70 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -416,6 +416,7 @@ It must be enabled in modules where either of the following occur:
 - A data family is declared with a kind other than ``Type``. Both ``Foo``
   and ``Bar``, defined below, fall into this category:
   ::
+
      class Foo a where
        data FooKey a :: TYPE 'IntRep
      class Bar (r :: RuntimeRep) where
@@ -425,6 +426,7 @@ It must be enabled in modules where either of the following occur:
   following instances of ``Foo`` and ``Bar`` as defined above fall into
   this category.
   ::
+
      instance Foo Bool where
        newtype FooKey Bool = FooKeyBoolC Int#
      instance Bar 'WordRep where
diff --git a/docs/users_guide/safe_haskell.rst b/docs/users_guide/safe_haskell.rst
index b734fe4743..7d7e120613 100644
--- a/docs/users_guide/safe_haskell.rst
+++ b/docs/users_guide/safe_haskell.rst
@@ -255,28 +255,29 @@ normally would.
 To achieve these properties, in the safe language dialect we disable
 completely the following features:
 
-- ``TemplateHaskell`` — Can be used to gain access to constructors and abstract
-  data types that weren't exported by a module, subverting module boundaries.
+- :extension:`TemplateHaskell` — Can be used to gain access to constructors and
+  abstract data types that weren't exported by a module, subverting module
+  boundaries.
 
 Furthermore, we restrict the following features:
 
-- ``ForeignFunctionInterface`` — Foreign import declarations that import a
-  function with a non-``IO`` type are disallowed.
+- :extension:`ForeignFunctionInterface` — Foreign import declarations that
+  import a function with a non-``IO`` type are disallowed.
 
-- ``RULES`` — Rewrite rules defined in a module M compiled with :extension:`Safe` are
-  dropped. Rules defined in Trustworthy modules that ``M`` imports are still
-  valid and will fire as usual.
+- ``RULES`` — Rewrite rules defined in a module M compiled with
+  :extension:`Safe` are dropped. Rules defined in Trustworthy modules that
+  ``M`` imports are still valid and will fire as usual.
 
-- ``OverlappingInstances`` — There is no restriction on the creation of
-  overlapping instances, but we do restrict their use at a particular call
+- :extension:`OverlappingInstances` — There is no restriction on the creation
+  of overlapping instances, but we do restrict their use at a particular call
   site. This is a detailed restriction, please refer to :ref:`Safe Overlapping
   Instances <safe-overlapping-instances>` for details.
 
-- ``GeneralisedNewtypeDeriving`` — GND is not allowed in the safe language. This
-  is due to the ability of it to violate module boundaries when module authors
-  forget to put nominal role annotations on their types as appropriate. For
-  this reason, the ``Data.Coerce`` module is also considered unsafe. We are
-  hoping to find a better solution here in the future.
+- :extension:`GeneralisedNewtypeDeriving` — GND is not allowed in the safe
+  language. This is due to the ability of it to violate module boundaries when
+  module authors forget to put nominal role annotations on their types as
+  appropriate. For this reason, the ``Data.Coerce`` module is also considered
+  unsafe. We are hoping to find a better solution here in the future.
 
 - ``GHC.Generics`` — Hand crafted instances of the ``Generic`` type class are
   not allowed in Safe Haskell. Such instances aren't strictly unsafe, but