mkUserGuidePart: Better flag cross-referencing

9 files changed, 94 insertions, 89 deletions

diff --git a/utils/mkUserGuidePart/Main.hs b/utils/mkUserGuidePart/Main.hs
index b30cc8f01d..41e8e40f86 100644
--- a/utils/mkUserGuidePart/Main.hs
+++ b/utils/mkUserGuidePart/Main.hs
@@ -52,13 +52,11 @@ flagsTable theFlags =
           ["Flag", "Description", "Static/Dynamic", "Reverse"]
           (map flagRow theFlags)
   where
-    code ""  = ""
-    code str = "``"++str++"``"
     flagRow flag =
-        [ code (flagName flag)
+        [ role "ghc-flag" (flagName flag)
         , flagDescription flag
         , type_
-        , code (flagReverse flag)
+        , role "ghc-flag" (flagReverse flag)
         ]
       where
         type_ = case flagType flag of
@@ -71,6 +69,12 @@ flagsTable theFlags =
 inlineCode :: String -> ReST
 inlineCode s = "``" ++ s ++ "``"
 
+-- | @role "hi" "Hello world"@ produces the ReST inline role element
+-- @:hi:`Hello world`@.
+role :: String -> String -> ReST
+role _ "" = ""
+role r c  = concat [":",r,":`",c,"`"]
+
 heading :: Char -> String -> ReST
 heading chr title = unlines
     [ title
diff --git a/utils/mkUserGuidePart/Options/Language.hs b/utils/mkUserGuidePart/Options/Language.hs
index 12fbbf543a..c9bb6ea6c0 100644
--- a/utils/mkUserGuidePart/Options/Language.hs
+++ b/utils/mkUserGuidePart/Options/Language.hs
@@ -72,7 +72,7 @@ languageOptions =
            "As of GHC 7.10, this option is not needed, and should not be "++
            "used. Previously this would automatically :ref:`derive Typeable "++
            "instances for every datatype and type class declaration "++
-           "<deriving-typeable>`. Implies ``-XDeriveDataTypeable``."
+           "<deriving-typeable>`. Implies :ghc-flag:`XDeriveDataTypeable`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoAutoDeriveTypeable"
          , flagSince = "7.8.1"
@@ -141,7 +141,7 @@ languageOptions =
   , flag { flagName = "-XDeriveDataTypeable"
          , flagDescription =
            "Enable ``deriving`` for the :ref:`Data class "++
-           "<deriving-typeable>`. Implied by ``-XAutoDeriveTypeable``."
+           "<deriving-typeable>`. Implied by :ghc-flag:`XAutoDeriveTypeable`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoDeriveDataTypeable"
          , flagSince = "6.8.1"
@@ -149,7 +149,7 @@ languageOptions =
   , flag { flagName = "-XDeriveFunctor"
          , flagDescription =
            "Enable :ref:`deriving for the Functor class <deriving-extra>`. "++
-           "Implied by ``-XDeriveTraversable``."
+           "Implied by :ghc-flag:`XDeriveTraversable`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoDeriveFunctor"
          , flagSince = "7.10.1"
@@ -157,7 +157,7 @@ languageOptions =
   , flag { flagName = "-XDeriveFoldable"
          , flagDescription =
            "Enable :ref:`deriving for the Foldable class <deriving-extra>`. "++
-           "Implied by ``-XDeriveTraversable``."
+           "Implied by :ghc-flag:`XDeriveTraversable`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoDeriveFoldable"
          , flagSince = "7.10.1"
@@ -186,7 +186,7 @@ languageOptions =
   , flag { flagName = "-XDeriveTraversable"
          , flagDescription =
            "Enable :ref:`deriving for the Traversable class <deriving-extra>`. "++
-           "Implies ``-XDeriveFunctor`` and ``-XDeriveFoldable``."
+           "Implies :ghc-flag:`XDeriveFunctor` and :ghc-flag:`XDeriveFoldable`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoDeriveTraversable"
          , flagSince = "7.10.1"
@@ -194,7 +194,7 @@ languageOptions =
   , flag { flagName = "-XDisambiguateRecordFields"
          , flagDescription =
            "Enable :ref:`record field disambiguation <disambiguate-fields>`. "++
-           "Implied by ``-XRecordWildCards``."
+           "Implied by :ghc-flag:`XRecordWildCards`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoDisambiguateRecordFields"
          , flagSince = "6.8.1"
@@ -222,8 +222,8 @@ languageOptions =
   , flag { flagName = "-XExplicitForAll"
          , flagDescription =
            "Enable :ref:`explicit universal quantification <explicit-foralls>`."++
-           " Implied by ``-XScopedTypeVariables``, ``-XLiberalTypeSynonyms``,"++
-           " ``-XRankNTypes`` and ``-XExistentialQuantification``."
+           " Implied by :ghc-flag:`XScopedTypeVariables`, :ghc-flag:`XLiberalTypeSynonyms`,"++
+           " :ghc-flag:`XRankNTypes` and :ghc-flag:`XExistentialQuantification`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoExplicitForAll"
          , flagSince = "6.12.1"
@@ -232,7 +232,7 @@ languageOptions =
          , flagDescription =
            "Enable using the keyword ``type`` to specify the namespace of "++
            "entries in imports and exports (:ref:`explicit-namespaces`). "++
-           "Implied by ``-XTypeOperators`` and ``-XTypeFamilies``."
+           "Implied by :ghc-flag:`XTypeOperators` and :ghc-flag:`XTypeFamilies`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoExplicitNamespaces"
          , flagSince = "7.6.1"
@@ -248,7 +248,7 @@ languageOptions =
   , flag { flagName = "-XFlexibleContexts"
          , flagDescription =
            "Enable :ref:`flexible contexts <flexible-contexts>`. Implied by "++
-           "``-XImplicitParams``."
+           ":ghc-flag:`XImplicitParams`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoFlexibleContexts"
          , flagSince = "6.8.1"
@@ -256,8 +256,8 @@ languageOptions =
   , flag { flagName = "-XFlexibleInstances"
          , flagDescription =
            "Enable :ref:`flexible instances <instance-rules>`. "++
-           "Implies ``-XTypeSynonymInstances``. "++
-           "Implied by ``-XImplicitParams``."
+           "Implies :ghc-flag:`XTypeSynonymInstances`. "++
+           "Implied by :ghc-flag:`XImplicitParams`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoFlexibleInstances"
          , flagSince = "6.8.1"
@@ -272,7 +272,7 @@ languageOptions =
   , flag { flagName = "-XFunctionalDependencies"
          , flagDescription =
            "Enable :ref:`functional dependencies <functional-dependencies>`. "++
-           "Implies ``-XMultiParamTypeClasses``."
+           "Implies :ghc-flag:`XMultiParamTypeClasses`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoFunctionalDependencies"
          , flagSince = "6.8.1"
@@ -280,7 +280,7 @@ languageOptions =
   , flag { flagName = "-XGADTs"
          , flagDescription =
            "Enable :ref:`generalised algebraic data types <gadt>`. "++
-           "Implies ``-XGADTSyntax`` and ``-XMonoLocalBinds``."
+           "Implies :ghc-flag:`XGADTSyntax` and :ghc-flag:`XMonoLocalBinds`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoGADTs"
          , flagSince = "6.8.1"
@@ -311,7 +311,7 @@ languageOptions =
   , flag { flagName = "-XImplicitParams"
          , flagDescription =
            "Enable :ref:`Implicit Parameters <implicit-parameters>`. "++
-           "Implies ``-XFlexibleContexts`` and ``-XFlexibleInstances``."
+           "Implies :ghc-flag:`XFlexibleContexts` and :ghc-flag:`XFlexibleInstances`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoImplicitParams"
          , flagSince = "6.8.1"
@@ -319,7 +319,7 @@ languageOptions =
   , flag { flagName = "-XNoImplicitPrelude"
          , flagDescription =
            "Don't implicitly ``import Prelude``. "++
-           "Implied by ``-XRebindableSyntax``."
+           "Implied by :ghc-flag:`XRebindableSyntax`."
          , flagType = DynamicFlag
          , flagReverse = "-XImplicitPrelude"
          , flagSince = "6.8.1"
@@ -327,7 +327,7 @@ languageOptions =
   , flag { flagName = "-XImpredicativeTypes"
          , flagDescription =
            "Enable :ref:`impredicative types <impredicative-polymorphism>`. "++
-           "Implies ``-XRankNTypes``."
+           "Implies :ghc-flag:`XRankNTypes`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoImpredicativeTypes"
          , flagSince = "6.10.1"
@@ -335,7 +335,7 @@ languageOptions =
   , flag { flagName = "-XIncoherentInstances"
          , flagDescription =
            "Enable :ref:`incoherent instances <instance-overlap>`. "++
-           "Implies ``-XOverlappingInstances``."
+           "Implies :ghc-flag:`XOverlappingInstances`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoIncoherentInstances"
          , flagSince = "6.8.1"
@@ -343,7 +343,7 @@ languageOptions =
   , flag { flagName = "-XTypeFamilyDependencies"
          , flagDescription =
            "Enable :ref:`injective type families <injective-ty-fams>`. "++
-           "Implies ``-XTypeFamilies``."
+           "Implies :ghc-flag:`XTypeFamilies`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoTypeFamilyDependencies"
          , flagSince = "8.0.1"
@@ -364,7 +364,7 @@ languageOptions =
   , flag { flagName = "-XKindSignatures"
          , flagDescription =
            "Enable :ref:`kind signatures <kinding>`. "++
-           "Implied by ``-XTypeFamilies`` and ``-XPolyKinds``."
+           "Implied by :ghc-flag:`XTypeFamilies` and :ghc-flag:`XPolyKinds`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoKindSignatures"
          , flagSince = "6.8.1"
@@ -400,7 +400,7 @@ languageOptions =
   , flag { flagName = "-XMonoLocalBinds"
          , flagDescription =
            "Enable :ref:`do not generalise local bindings <mono-local-binds>`. "++
-           "Implied by ``-XTypeFamilies`` and ``-XGADTs``."
+           "Implied by :ghc-flag:`XTypeFamilies` and :ghc-flag:`XGADTs`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoMonoLocalBinds"
          , flagSince = "6.12.1"
@@ -416,7 +416,7 @@ languageOptions =
          , flagDescription =
            "Enable :ref:`multi parameter type classes "++
            "<multi-param-type-classes>`. Implied by "++
-           "``-XFunctionalDependencies``."
+           ":ghc-flag:`XFunctionalDependencies`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoMultiParamTypeClasses"
          , flagSince = "6.8.1"
@@ -457,7 +457,7 @@ languageOptions =
          , flagDescription =
            "Deprecated, does nothing. :ref:`nullary (no parameter) type "++
            "classes <nullary-type-classes>` are now enabled using "++
-           "``-XMultiParamTypeClasses``."
+           ":ghc-flag:`XMultiParamTypeClasses`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoNullaryTypeClasses"
          , flagSince = "7.8.1"
@@ -499,7 +499,7 @@ languageOptions =
          }
   , flag { flagName = "-XParallelArrays"
          , flagDescription =
-           "Enable parallel arrays. Implies ``-XParallelListComp``."
+           "Enable parallel arrays. Implies :ghc-flag:`XParallelListComp`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoParallelArrays"
          , flagSince = "7.4.1"
@@ -508,7 +508,7 @@ languageOptions =
          , flagDescription =
            "Enable :ref:`parallel list comprehensions "++
            "<parallel-list-comprehensions>`. "++
-           "Implied by ``-XParallelArrays``."
+           "Implied by :ghc-flag:`XParallelArrays`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoParallelListComp"
          , flagSince = "6.8.1"
@@ -536,7 +536,7 @@ languageOptions =
   , flag { flagName = "-XPolyKinds"
          , flagDescription =
            "Enable :ref:`kind polymorphism <kind-polymorphism>`. "++
-           "Implies ``-XKindSignatures``."
+           "Implies :ghc-flag:`XKindSignatures`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoPolyKinds"
          , flagSince = "7.4.1"
@@ -544,7 +544,7 @@ languageOptions =
   , flag { flagName = "-XPolymorphicComponents"
          , flagDescription =
            "Enable :ref:`polymorphic components for data constructors "++
-           "<universal-quantification>`. Synonym for ``-XRankNTypes``."
+           "<universal-quantification>`. Synonym for :ghc-flag:`XRankNTypes`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoPolymorphicComponents"
          , flagSince = "6.8.1"
@@ -565,7 +565,7 @@ languageOptions =
   , flag { flagName = "-XRank2Types"
          , flagDescription =
            "Enable :ref:`rank-2 types <universal-quantification>`. "++
-           "Synonym for ``-XRankNTypes``."
+           "Synonym for :ghc-flag:`XRankNTypes`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoRank2Types"
          , flagSince = "6.8.1"
@@ -573,7 +573,7 @@ languageOptions =
   , flag { flagName = "-XRankNTypes"
          , flagDescription =
            "Enable :ref:`rank-N types <universal-quantification>`. "++
-           "Implied by ``-XImpredicativeTypes``."
+           "Implied by :ghc-flag:`XImpredicativeTypes`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoRankNTypes"
          , flagSince = "6.8.1"
@@ -581,7 +581,7 @@ languageOptions =
   , flag { flagName = "-XRebindableSyntax"
          , flagDescription =
            "Employ :ref:`rebindable syntax <rebindable-syntax>`. "++
-           "Implies ``-XNoImplicitPrelude``."
+           "Implies :ghc-flag:`XNoImplicitPrelude`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoRebindableSyntax"
          , flagSince = "7.0.1"
@@ -589,7 +589,7 @@ languageOptions =
   , flag { flagName = "-XRecordWildCards"
          , flagDescription =
            "Enable :ref:`record wildcards <record-wildcards>`. "++
-           "Implies ``-XDisambiguateRecordFields``."
+           "Implies :ghc-flag:`XDisambiguateRecordFields`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoRecordWildCards"
          , flagSince = "6.8.1"
@@ -688,8 +688,8 @@ languageOptions =
   , flag { flagName = "-XTypeFamilies"
          , flagDescription =
            "Enable :ref:`type families <type-families>`. "++
-           "Implies ``-XExplicitNamespaces``, ``-XKindSignatures``, "++
-           "and ``-XMonoLocalBinds``."
+           "Implies :ghc-flag:`XExplicitNamespaces`, :ghc-flag:`XKindSignatures`, "++
+           "and :ghc-flag:`XMonoLocalBinds`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoTypeFamilies"
          , flagSince = "6.8.1"
@@ -697,7 +697,7 @@ languageOptions =
   , flag { flagName = "-XTypeOperators"
          , flagDescription =
            "Enable :ref:`type operators <type-operators>`. "++
-           "Implies ``-XExplicitNamespaces``."
+           "Implies :ghc-flag:`XExplicitNamespaces`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoTypeOperators"
          , flagSince = "6.8.1"
@@ -705,7 +705,7 @@ languageOptions =
   , flag { flagName = "-XTypeSynonymInstances"
          , flagDescription =
            "Enable :ref:`type synonyms in instance heads "++
-           "<flexible-instance-head>`. Implied by ``-XFlexibleInstances``."
+           "<flexible-instance-head>`. Implied by :ghc-flag:`XFlexibleInstances`."
          , flagType = DynamicFlag
          , flagReverse = "-XNoTypeSynonymInstances"
          , flagSince = "6.8.1"
diff --git a/utils/mkUserGuidePart/Options/Linking.hs b/utils/mkUserGuidePart/Options/Linking.hs
index 14c4783585..2348daa3f4 100644
--- a/utils/mkUserGuidePart/Options/Linking.hs
+++ b/utils/mkUserGuidePart/Options/Linking.hs
@@ -94,7 +94,7 @@ linkingOptions =
          }
   , flag { flagName = "-no-rtsopts-suggestions"
          , flagDescription =
-           "Don't print RTS suggestions about linking with ``-rtsopts``."
+           "Don't print RTS suggestions about linking with :ghc-flag:`rtsopts`."
          , flagType = DynamicFlag
          }
   , flag { flagName = "-no-link"
@@ -123,7 +123,7 @@ linkingOptions =
          }
   , flag { flagName = "-ticky"
          , flagDescription =
-           "For linking, this simply implies ``-debug``; "++
+           "For linking, this simply implies :ghc-flag:`debug`; "++
            "see :ref:`ticky-ticky`."
          , flagType = DynamicFlag
          }
diff --git a/utils/mkUserGuidePart/Options/Misc.hs b/utils/mkUserGuidePart/Options/Misc.hs
index 141a9caf1c..a3e8738d48 100644
--- a/utils/mkUserGuidePart/Options/Misc.hs
+++ b/utils/mkUserGuidePart/Options/Misc.hs
@@ -6,7 +6,7 @@ miscOptions :: [Flag]
 miscOptions =
   [ flag { flagName = "-jN"
          , flagDescription =
-           "When compiling with ``--make``, compile ⟨N⟩ modules in parallel."
+           "When compiling with :ghc-flag:`-make`, compile ⟨N⟩ modules in parallel."
          , flagType = DynamicFlag
          }
   , flag { flagName = "-fno-hi-version-check"
diff --git a/utils/mkUserGuidePart/Options/Optimizations.hs b/utils/mkUserGuidePart/Options/Optimizations.hs
index 6e0a2ff5bf..389cd37c68 100644
--- a/utils/mkUserGuidePart/Options/Optimizations.hs
+++ b/utils/mkUserGuidePart/Options/Optimizations.hs
@@ -6,35 +6,35 @@ optimizationsOptions :: [Flag]
 optimizationsOptions =
   [ flag { flagName = "-fcall-arity"
          , flagDescription =
-           "Enable call-arity optimisation. Implied by ``-O``."
+           "Enable call-arity optimisation. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-call-arity"
          }
   , flag { flagName = "-fcase-merge"
-         , flagDescription = "Enable case-merging. Implied by ``-O``."
+         , flagDescription = "Enable case-merging. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-case-merge"
          }
   , flag { flagName = "-fcmm-elim-common-blocks"
          , flagDescription =
-           "Enable Cmm common block elimination. Implied by ``-O``."
+           "Enable Cmm common block elimination. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-cmm-elim-common-blocks"
          }
   , flag { flagName = "-fcmm-sink"
-         , flagDescription = "Enable Cmm sinking. Implied by ``-O``."
+         , flagDescription = "Enable Cmm sinking. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-cmm-sink"
          }
   , flag { flagName = "-fcpr-anal"
          , flagDescription =
-           "Turn on CPR analysis in the demand analyser. Implied by ``-O``."
+           "Turn on CPR analysis in the demand analyser. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-cpr-anal"
          }
   , flag { flagName = "-fcse"
          , flagDescription =
-           "Enable common sub-expression elimination. Implied by ``-O``."
+           "Enable common sub-expression elimination. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-cse"
          }
@@ -57,7 +57,7 @@ optimizationsOptions =
          , flagReverse = "-fno-dmd-tx-dict-sel"
          }
   , flag { flagName = "-fdo-eta-reduction"
-         , flagDescription = "Enable eta-reduction. Implied by ``-O``."
+         , flagDescription = "Enable eta-reduction. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-do-eta-reduction"
          }
@@ -76,7 +76,7 @@ optimizationsOptions =
          , flagDescription =
            "Switch on all rewrite rules (including rules generated by "++
            "automatic specialisation of overloaded functions). Implied by "++
-           "``-O``."
+           ":ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-enable-rewrite-rules"
          }
@@ -93,14 +93,14 @@ optimizationsOptions =
          }
   , flag { flagName = "-ffloat-in"
          , flagDescription =
-           "Turn on the float-in transformation. Implied by ``-O``."
+           "Turn on the float-in transformation. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-float-in"
          }
   , flag { flagName = "-ffull-laziness"
          , flagDescription =
            "Turn on full laziness (floating bindings outwards). "++
-           "Implied by ``-O``."
+           "Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-full-laziness"
          }
@@ -113,13 +113,13 @@ optimizationsOptions =
          }
   , flag { flagName = "-fignore-asserts"
          , flagDescription =
-           "Ignore assertions in the source. Implied by ``-O``."
+           "Ignore assertions in the source. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-ignore-asserts"
          }
   , flag { flagName = "-fignore-interface-pragmas"
          , flagDescription =
-           "Ignore pragmas in interface files. Implied by ``-O0`` only."
+           "Ignore pragmas in interface files. Implied by :ghc-flag:`O0` only."
          , flagType = DynamicFlag
          , flagReverse = "-fno-ignore-interface-pragmas"
          }
@@ -132,7 +132,7 @@ optimizationsOptions =
          }
   , flag { flagName = "-fliberate-case"
          , flagDescription =
-           "Turn on the liberate-case transformation. Implied by ``-O2``."
+           "Turn on the liberate-case transformation. Implied by :ghc-flag:`O2`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-liberate-case"
          }
@@ -146,7 +146,7 @@ optimizationsOptions =
   , flag { flagName = "-floopification"
          , flagDescription =
            "Turn saturated self-recursive tail-calls into local jumps in the "++
-           "generated assembly. Implied by ``-O``."
+           "generated assembly. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-loopification"
          }
@@ -206,7 +206,7 @@ optimizationsOptions =
          }
   , flag { flagName = "-fomit-interface-pragmas"
          , flagDescription =
-           "Don't generate interface pragmas. Implied by ``-O0`` only."
+           "Don't generate interface pragmas. Implied by :ghc-flag:`O0` only."
          , flagType = DynamicFlag
          , flagReverse = "-fno-omit-interface-pragmas"
          }
@@ -219,7 +219,7 @@ optimizationsOptions =
   , flag { flagName = "-fpedantic-bottoms"
          , flagDescription =
            "Make GHC be more precise about its treatment of bottom (but see "++
-           "also ``-fno-state-hack``). In particular, GHC will not "++
+           "also :ghc-flag:`fno-state-hack`). In particular, GHC will not "++
            "eta-expand through a case expression."
          , flagType = DynamicFlag
          , flagReverse = "-fno-pedantic-bottoms"
@@ -227,7 +227,7 @@ optimizationsOptions =
   , flag { flagName = "-fregs-graph"
          , flagDescription =
            "Use the graph colouring register allocator for register "++
-           "allocation in the native code generator. Implied by ``-O2``."
+           "allocation in the native code generator. Implied by :ghc-flag:`O2`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-regs-graph"
          }
@@ -241,7 +241,7 @@ optimizationsOptions =
   , flag { flagName = "-fsimplifier-phases=⟨n⟩"
          , flagDescription =
            "*default: 2.* Set the number of phases for the simplifier. "++
-           "Ignored with ``-O0``."
+           "Ignored with :ghc-flag:`O0`."
          , flagType = DynamicFlag
          }
   , flag { flagName = "-fsimpl-tick-factor=⟨n⟩"
@@ -251,7 +251,7 @@ optimizationsOptions =
          }
   , flag { flagName = "-fspec-constr"
          , flagDescription =
-           "Turn on the SpecConstr transformation. Implied by ``-O2``."
+           "Turn on the SpecConstr transformation. Implied by :ghc-flag:`O2`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-spec-constr"
          }
@@ -272,7 +272,7 @@ optimizationsOptions =
          }
   , flag { flagName = "-fspecialise"
          , flagDescription =
-           "Turn on specialisation of overloaded functions. Implied by ``-O``."
+           "Turn on specialisation of overloaded functions. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-specialise"
          }
@@ -290,7 +290,7 @@ optimizationsOptions =
          }
   , flag { flagName = "-fstrictness"
          , flagDescription = "Turn on strictness analysis." ++
-           " Implied by ``-O``. Implies ``-fworker-wrapper``"
+           " Implied by :ghc-flag:`O`. Implies :ghc-flag:`fworker-wrapper`"
          , flagType = DynamicFlag
          , flagReverse = "-fno-strictness"
          }
@@ -302,7 +302,7 @@ optimizationsOptions =
   , flag { flagName = "-funbox-small-strict-fields"
          , flagDescription =
            "Flatten strict constructor fields with a pointer-sized "++
-           "representation. Implied by ``-O``."
+           "representation. Implied by :ghc-flag:`O`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-unbox-small-strict-fields"
          }
@@ -345,9 +345,9 @@ optimizationsOptions =
   , flag { flagName = "-fworker-wrapper"
          , flagDescription =
            "Enable the worker-wrapper transformation after a strictness" ++
-           " analysis pass. Implied by ``-O``, and by ``-fstrictness``." ++
-           " Disabled by ``-fno-strictness``. Enabling ``-fworker-wrapper``" ++
-           " while strictness analysis is disabled (by ``-fno-strictness``)" ++
+           " analysis pass. Implied by :ghc-flag:`O`, and by :ghc-flag:`fstrictness`." ++
+           " Disabled by :ghc-flag:`fno-strictness`. Enabling :ghc-flag:`fworker-wrapper`" ++
+           " while strictness analysis is disabled (by :ghc-flag:`fno-strictness`)" ++
            " has no effect."
          , flagType = DynamicFlag
          , flagReverse = "-fno-worker-wrapper"
diff --git a/utils/mkUserGuidePart/Options/Phases.hs b/utils/mkUserGuidePart/Options/Phases.hs
index 230eda1495..b32fa3468e 100644
--- a/utils/mkUserGuidePart/Options/Phases.hs
+++ b/utils/mkUserGuidePart/Options/Phases.hs
@@ -7,7 +7,7 @@ phaseOptions =
   [ flag { flagName = "-F"
          , flagDescription =
            "Enable the use of a :ref:`pre-processor <pre-processor>` "++
-           "(set with ``-pgmF``)"
+           "(set with :ghc-flag:`pgmF`)"
          , flagType = DynamicFlag
          }
   , flag { flagName = "-E"
diff --git a/utils/mkUserGuidePart/Options/RecompilationChecking.hs b/utils/mkUserGuidePart/Options/RecompilationChecking.hs
index 1dec661f40..740d04f55d 100644
--- a/utils/mkUserGuidePart/Options/RecompilationChecking.hs
+++ b/utils/mkUserGuidePart/Options/RecompilationChecking.hs
@@ -8,7 +8,7 @@ recompilationCheckingOptions =
          , flagDescription =
            "Turn off recompilation checking. This is implied by any " ++
            "``-ddump-X`` option when compiling a single file " ++
-           "(i.e. when using ``-c``)."
+           "(i.e. when using :ghc-flag:`c`)."
          , flagType = DynamicFlag
          , flagReverse = "-fno-force-recomp"
          }
diff --git a/utils/mkUserGuidePart/Options/Verbosity.hs b/utils/mkUserGuidePart/Options/Verbosity.hs
index 72a29f184c..8d5ed1aa62 100644
--- a/utils/mkUserGuidePart/Options/Verbosity.hs
+++ b/utils/mkUserGuidePart/Options/Verbosity.hs
@@ -22,21 +22,21 @@ verbosityOptions =
   , flag { flagName = "-fprint-explicit-foralls"
          , flagDescription =
            "Print explicit ``forall`` quantification in types. " ++
-           "See also ``-XExplicitForAll``"
+           "See also :ghc-flag:`XExplicitForAll`"
          , flagType = DynamicFlag
          , flagReverse = "-fno-print-explicit-foralls"
          }
   , flag { flagName = "-fprint-explicit-kinds"
          , flagDescription =
            "Print explicit kind foralls and kind arguments in types. " ++
-           "See also ``-XKindSignature``"
+           "See also :ghc-flag:`XKindSignature`"
          , flagType = DynamicFlag
          , flagReverse = "-fno-print-explicit-kinds"
          }
   , flag { flagName = "-fprint-unicode-syntax"
          , flagDescription =
            "Use unicode syntax when printing expressions, types and kinds. " ++
-           "See also ``-XUnicodeSyntax``"
+           "See also :ghc-flag:`XUnicodeSyntax`"
          , flagType = DynamicFlag
          , flagReverse = "-fno-print-unicode-syntax"
          }
diff --git a/utils/mkUserGuidePart/Options/Warnings.hs b/utils/mkUserGuidePart/Options/Warnings.hs
index c775af4f6c..a9b754d8c2 100644
--- a/utils/mkUserGuidePart/Options/Warnings.hs
+++ b/utils/mkUserGuidePart/Options/Warnings.hs
@@ -39,8 +39,8 @@ warningsOptions =
   , flag { flagName = "-fdefer-type-errors"
          , flagDescription =
            "Turn type errors into warnings, :ref:`deferring the error until "++
-           "runtime <defer-type-errors>`. Implies ``-fdefer-typed-holes``. "++
-           "See also ``-Wdeferred-type-errors``"
+           "runtime <defer-type-errors>`. Implies :ghc-flag:`fdefer-typed-holes`. "++
+           "See also :ghc-flag:`Wdeferred-type-errors`"
          , flagType = DynamicFlag
          , flagReverse = "-fno-defer-type-errors"
          }
@@ -48,8 +48,8 @@ warningsOptions =
          , flagDescription =
            "Convert :ref:`typed hole <typed-holes>` errors into warnings, "++
            ":ref:`deferring the error until runtime <defer-type-errors>`. "++
-           "Implied by ``-fdefer-type-errors``. "++
-           "See also ``-Wtyped-holes``."
+           "Implied by :ghc-flag:`fdefer-type-errors`. "++
+           "See also :ghc-flag:`Wtyped-holes`."
          , flagType = DynamicFlag
          , flagReverse = "-fno-defer-typed-holes"
          }
@@ -246,8 +246,8 @@ warningsOptions =
   , flag { flagName = "-Wunused-binds"
          , flagDescription =
            "warn about bindings that are unused. Alias for "++
-           "``-Wunused-top-binds``, ``-Wunused-local-binds`` and "++
-           "``-Wunused-pattern-binds``"
+           ":ghc-flag:`Wunused-top-binds`, :ghc-flag:`Wunused-local-binds` and "++
+           ":ghc-flag:`Wunused-pattern-binds`"
          , flagType = DynamicFlag
          , flagReverse = "-Wno-unused-binds"
          }
@@ -296,7 +296,7 @@ warningsOptions =
            "Should be used to check the safety status of modules when using "++
            "safe inference. Works on all module types, even those using "++
            "explicit :ref:`Safe Haskell <safe-haskell>` modes (such as "++
-           "``-XTrustworthy``) and so can be used to have the compiler check "++
+           ":ghc-flag:`XTrustworthy`) and so can be used to have the compiler check "++
            "any assumptions made."
          , flagType = DynamicFlag
          , flagReverse = "-Wno-unsafe"
@@ -307,17 +307,17 @@ warningsOptions =
            "be used to check the safety status of modules when using safe "++
            "inference. Works on all module types, even those using explicit "++
            ":ref:`Safe Haskell <safe-haskell>` modes (such as "++
-           "``-XTrustworthy``) and so can be used to have the compiler check "++
+           ":ghc-flag:`XTrustworthy`) and so can be used to have the compiler check "++
            "any assumptions made."
          , flagType = DynamicFlag
          , flagReverse = "-Wno-safe"
          }
   , flag { flagName = "-Wtrustworthy-safe"
          , flagDescription =
-           "warn if the module being compiled is marked as ``-XTrustworthy`` "++
-           "but it could instead be marked as ``-XSafe``, a more informative "++
-           "bound. Can be used to detect once a Safe Haskell bound can be "++
-           "improved as dependencies are updated."
+           "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. Can be used to detect"++
+           "once a Safe Haskell bound can be improved as dependencies are updated."
          , flagType = DynamicFlag
          , flagReverse = "-Wno-safe"
          }
@@ -339,7 +339,7 @@ warningsOptions =
          , flagDescription =
            "Report warnings when :ref:`deferred type errors "++
            "<defer-type-errors>` are enabled. This option is enabled by "++
-           "default. See ``-fdefer-type-errors``."
+           "default. See :ghc-flag:`fdefer-type-errors`."
          , flagType = DynamicFlag
          , flagReverse = "-Wno-deferred-type-errors"
          }
@@ -347,16 +347,17 @@ warningsOptions =
          , flagDescription =
            "Report warnings when :ref:`typed hole <typed-holes>` errors are "++
            ":ref:`deferred until runtime <defer-type-errors>`. See "++
-           "``-fdefer-typed-holes``."
+           ":ghc-flag:`fdefer-typed-holes`."
          , flagType = DynamicFlag
          , flagReverse = "-Wno-typed-holes"
          }
   , flag { flagName = "-Wpartial-type-signatures"
          , flagDescription =
            "warn about holes in partial type signatures when "++
-           "``-XPartialTypeSignatures`` is enabled. Not applicable when "++
-           "``-XPartialTypesignatures`` is not enabled, in which case errors "++
-           "are generated for such holes. See :ref:`partial-type-signatures`."
+           ":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`."
          , flagType = DynamicFlag
          , flagReverse = "-Wno-partial-type-signatures"
          }