users_guide: Use semantic directive/role for command line options

And GHCi commands. This makes cross-referencing much easier.

Also normalize markup a bit and add some missing flags.

1 files changed, 74 insertions, 74 deletions

diff --git a/docs/users_guide/safe_haskell.rst b/docs/users_guide/safe_haskell.rst
index b54b1ec2a8..efa6188b1c 100644
--- a/docs/users_guide/safe_haskell.rst
+++ b/docs/users_guide/safe_haskell.rst
@@ -158,40 +158,40 @@ reasons this security mechanism would fail without Safe Haskell:
   it.
 
 Safe Haskell prevents all these attacks. This is done by compiling the
-RIO module with the ``-XSafe`` or ``-XTrustworthy`` flag and compiling
-``Danger`` with the ``-XSafe`` flag. We explain each below.
+RIO module with the :ghc-flag:`-XSafe` or :ghc-flag:`-XTrustworthy` flag and compiling
+``Danger`` with the :ghc-flag:`-XSafe` flag. We explain each below.
 
-The use of ``-XSafe`` to compile ``Danger`` restricts the features of
+The use of :ghc-flag:`-XSafe` to compile ``Danger`` restricts the features of
 Haskell that can be used to a `safe subset <#safe-language>`__. This
 includes disallowing ``unsafePerformIO``, Template Haskell, pure FFI
 functions, RULES and restricting the operation of Overlapping Instances.
-The ``-XSafe`` flag also restricts the modules can be imported by
+The :ghc-flag:`-XSafe` flag also restricts the modules can be imported by
 ``Danger`` to only those that are considered trusted. Trusted modules
-are those compiled with ``-XSafe``, where GHC provides a mechanical
+are those compiled with :ghc-flag:`-XSafe`, where GHC provides a mechanical
 guarantee that the code is safe. Or those modules compiled with
-``-XTrustworthy``, where the module author claims that the module is
+:ghc-flag:`-XTrustworthy`, where the module author claims that the module is
 Safe.
 
-This is why the RIO module is compiled with ``-XSafe`` or
-``-XTrustworthy``>, to allow the ``Danger`` module to import it. The
-``-XTrustworthy`` flag doesn't place any restrictions on the module like
-``-XSafe`` does (expect to restrict overlapping instances to `safe
+This is why the RIO module is compiled with :ghc-flag:`-XSafe` or
+:ghc-flag:`-XTrustworthy`>, to allow the ``Danger`` module to import it. The
+:ghc-flag:`-XTrustworthy` flag doesn't place any restrictions on the module like
+:ghc-flag:`-XSafe` does (expect to restrict overlapping instances to `safe
 overlapping instances <#safe-overlapping-instances>`__). Instead the
 module author claims that while code may use unsafe features internally,
 it only exposes an API that can used in a safe manner.
 
-However, the unrestricted use of ``-XTrustworthy`` is a problem as an
+However, the unrestricted use of :ghc-flag:`-XTrustworthy` is a problem as an
 arbitrary module can use it to mark themselves as trusted, yet
-``-XTrustworthy`` doesn't offer any guarantees about the module, unlike
-``-XSafe``. To control the use of trustworthy modules it is recommended
-to use the ``-fpackage-trust`` flag. This flag adds an extra requirement
+:ghc-flag:`-XTrustworthy` doesn't offer any guarantees about the module, unlike
+:ghc-flag:`-XSafe`. To control the use of trustworthy modules it is recommended
+to use the :ghc-flag:`-fpackage-trust` flag. This flag adds an extra requirement
 to the trust check for trustworthy modules. It requires that for a
 trustworthy modules to be considered trusted, and allowed to be used in
-``-XSafe`` compiled code, the client C compiling the code must tell GHC
+:ghc-flag:`-XSafe` compiled code, the client C compiling the code must tell GHC
 that they trust the package the trustworthy module resides in. This is
 essentially a way of for C to say, while this package contains
 trustworthy modules that can be used by untrusted modules compiled with
-``-XSafe``, I trust the author(s) of this package and trust the modules
+:ghc-flag:`-XSafe`, I trust the author(s) of this package and trust the modules
 only expose a safe API. The trust of a package can be changed at any
 time, so if a vulnerability found in a package, C can declare that
 package untrusted so that any future compilation against that package
@@ -199,7 +199,7 @@ would fail. For a more detailed overview of this mechanism see
 :ref:`safe-trust`.
 
 In the example, ``Danger`` can import module ``RIO`` because ``RIO`` is
-compiled with ``-XSafe``. Thus, ``Danger`` can make use of the
+compiled with :ghc-flag:`-XSafe`. Thus, ``Danger`` can make use of the
 ``rioReadFile`` and ``rioWriteFile`` functions to access permitted file
 names. The main application then imports both ``RIO`` and ``Danger``. To
 run the plugin, it calls ``RIO.runRIO Danger.runMe`` within the ``IO``
@@ -258,7 +258,7 @@ Furthermore, we restrict the following features:
 - ``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 ``-XSafe`` are
+- ``RULES`` — Rewrite rules defined in a module M compiled with :ghc-flag:`-XSafe` are
   dropped. Rules defined in Trustworthy modules that ``M`` imports are still
   valid and will fire as usual.
 
@@ -275,7 +275,7 @@ Furthermore, we restrict the following features:
 
 - ``Data.Typeable`` — Hand crafted instances of the Typeable type class are not allowed
   in Safe Haskell as this can easily be abused to unsafely coerce
-  between types. Derived instances (through the ``-XDeriveDataTypeable``
+  between types. Derived instances (through the :ghc-flag:`-XDeriveDataTypeable`
   extension) are still allowed.
 
 .. _safe-overlapping-instances:
@@ -318,12 +318,12 @@ More specifically, consider the following modules:
               f :: String
               f = op ([1,2,3,4] :: [Int])
 
-Both module ``Class`` and module ``Dangerous`` will compile under ``-XSafe``
+Both module ``Class`` and module ``Dangerous`` will compile under :ghc-flag:`-XSafe`
 without issue. However, in module ``TCB_Runner``, we must check if the call
 to ``op`` in function ``f`` is safe.
 
 What does it mean to be Safe? That importing a module compiled with
-``-XSafe`` shouldn't change the meaning of code that compiles fine
+:ghc-flag:`-XSafe` shouldn't change the meaning of code that compiles fine
 without importing the module. This is the Safe Haskell property known as
 *semantic consistency*.
 
@@ -350,8 +350,8 @@ if the second condition isn't violated, then the module author ``M`` must
 depend either on a type-class or type defined in ``N``.
 
 When an particular type-class method call is considered unsafe due to
-overlapping instances, and the module being compiled is using ``-XSafe``
-or ``-XTrustworthy``, then compilation will fail. For ``-XUnsafe``, no
+overlapping instances, and the module being compiled is using :ghc-flag:`-XSafe`
+or :ghc-flag:`-XTrustworthy`, then compilation will fail. For :ghc-flag:`-XUnsafe`, no
 restriction is applied, and for modules using safe inference, they will
 be inferred unsafe.
 
@@ -387,13 +387,13 @@ Trust and Safe Haskell Modes
 
 Safe Haskell introduces the following three language flags:
 
-- ``-XSafe`` — Enables the safe language dialect, asking GHC to guarantee trust.
+- :ghc-flag:`-XSafe` — Enables the safe language dialect, asking GHC to guarantee trust.
   The safe language dialect requires that all imports be trusted or a
   compilation error will occur. Safe Haskell will also infer this safety type
   for modules automatically when possible. Please refer to section
   :ref:`safe-inference` for more details of this.
 
-- ``-XTrustworthy`` — Means that while this module may invoke unsafe functions
+- :ghc-flag:`-XTrustworthy` — Means that while this module may invoke unsafe functions
   internally, the module's author claims that it exports an API that can't be
   used in an unsafe way. This doesn't enable the safe language. It does however
   restrict the resolution of overlapping instances to only allow :ref:`safe
@@ -403,8 +403,8 @@ Safe Haskell introduces the following three language flags:
   An import statement without the keyword behaves as usual and can import any
   module whether trusted or not.
 
-- ``-XUnsafe`` — Marks the module being compiled as unsafe so that modules
-  compiled using ``-XSafe`` can't import it. You may want to explicitly mark a
+- :ghc-flag:`-XUnsafe` — Marks the module being compiled as unsafe so that modules
+  compiled using :ghc-flag:`-XSafe` can't import it. You may want to explicitly mark a
   module unsafe when it exports internal constructors that can be used to
   violate invariants.
 
@@ -416,8 +416,8 @@ Safe Haskell, please refer to section :ref:`safe-inference` for more
 details.
 
 The procedure to check if a module is trusted or not depends on if the
-``-fpackage-trust`` flag is present. The check is similar in both cases
-with the ``-fpackage-trust`` flag enabling an extra requirement for
+:ghc-flag:`-fpackage-trust` flag is present. The check is similar in both cases
+with the :ghc-flag:`-fpackage-trust` flag enabling an extra requirement for
 trustworthy modules to be regarded as trusted.
 
 Trust check (``-fpackage-trust`` disabled)
@@ -430,18 +430,18 @@ A module ``M`` in a package ``P`` is trusted by a client C if and only if:
 
 - Both of these hold:
 
-   -  The module was compiled with ``-XSafe``
+   -  The module was compiled with :ghc-flag:`-XSafe`
    -  All of M's direct imports are trusted by C
 
 - *or* all of these hold:
 
-   -  The module was compiled with ``-XTrustworthy``
+   -  The module was compiled with :ghc-flag:`-XTrustworthy`
    -  All of ``M``\'s direct *safe imports* are trusted by C
 
 The above definition of trust has an issue. Any module can be compiled
-with ``-XTrustworthy`` and it will be trusted. To control this, there is
+with :ghc-flag:`-XTrustworthy` and it will be trusted. To control this, there is
 an additional definition of package trust (enabled with the
-``-fpackage-trust`` flag). The point of package trust is to require that
+:ghc-flag:`-fpackage-trust` flag). The point of package trust is to require that
 the client C explicitly say which packages are allowed to contain
 trustworthy modules. Trustworthy packages are only trusted if they
 reside in a package trusted by C.
@@ -453,7 +453,7 @@ Trust check (``-fpackage-trust`` enabled)
    single: trust check
    single: -fpackage-trust
 
-When the ``-fpackage-trust`` flag is enabled, whether or not a module is
+When the :ghc-flag:`-fpackage-trust` flag is enabled, whether or not a module is
 trusted depends on if certain packages are trusted. Package trust is
 determined by the client C invoking GHC (i.e. you).
 
@@ -467,17 +467,17 @@ Specifically, a package *P is trusted* when one of these hold:
 In either case, C is the only authority on package trust. It is up to
 the client to decide which `packages they trust <#safe-package-trust>`__.
 
-When the ``-fpackage-trust`` flag is used a *module M from package P is
+When the :ghc-flag:`-fpackage-trust` flag is used a *module M from package P is
 trusted by a client C* if and only if:
 
 -  Both of these hold:
 
-   -  The module was compiled with ``-XSafe``
+   -  The module was compiled with :ghc-flag:`-XSafe`
    -  All of ``M``\'s direct imports are trusted by C
 
 -  *or* all of these hold:
 
-   -  The module was compiled with ``-XTrustworthy``
+   -  The module was compiled with :ghc-flag:`-XTrustworthy`
    -  All of ``M``\'s direct safe imports are trusted by C
    -  Package ``P`` is trusted by C
 
@@ -486,17 +486,17 @@ through the restrictions imposed by the safe language. For the second
 definition of trust, the guarantee is provided initially by the module
 author. The client C then establishes that they trust the module author
 by indicating they trust the package the module resides in. This trust
-chain is required as GHC provides no guarantee for ``-XTrustworthy``
+chain is required as GHC provides no guarantee for :ghc-flag:`-XTrustworthy`
 compiled modules.
 
 The reason there are two modes of checking trust is that the extra
-requirement enabled by ``-fpackage-trust`` causes the design of Safe
+requirement enabled by :ghc-flag:`-fpackage-trust` causes the design of Safe
 Haskell to be invasive. Packages using Safe Haskell when the flag is
 enabled may or may not compile depending on the state of trusted
 packages on a users machine. This is both fragile, and causes
 compilation failures for everyone, even if they aren't trying to use any
 of the guarantees provided by Safe Haskell. Disabling
-``-fpackage-trust`` by default and turning it into a flag makes Safe
+:ghc-flag:`-fpackage-trust` by default and turning it into a flag makes Safe
 Haskell an opt-in extension rather than an always on feature.
 
 .. _safe-trust-example:
@@ -519,11 +519,11 @@ Example
             import safe Buggle
 
 Suppose a client C decides to trust package ``P`` and package ``base``. Then
-does C trust module ``M``? Well ``M`` is marked ``-XTrustworthy``, so we don't
+does C trust module ``M``? Well ``M`` is marked :ghc-flag:`-XTrustworthy`, so we don't
 restrict the language. However, we still must check ``M``\'s imports:
 
 - First, ``M`` imports ``System.IO.Unsafe``. This is an unsafe module, however
-  ``M`` was compiled with ``-XTrustworthy`` , so ``P``\'s author takes
+  ``M`` was compiled with :ghc-flag:`-XTrustworthy` , so ``P``\'s author takes
   responsibility for that import. ``C`` trusts ``P``\'s author, so this import
   is fine.
 
@@ -535,14 +535,14 @@ restrict the language. However, we still must check ``M``\'s imports:
   OK, but again under the assumption that all of ``Buggle``\'s imports are
   trusted by ``C``. We must recursively check all imports!
 
-- Buggle only imports ``Prelude``, which is compiled with ``-XTrustworthy``.
+- Buggle only imports ``Prelude``, which is compiled with :ghc-flag:`-XTrustworthy`.
   ``Prelude`` resides in the ``base`` package, which ``C`` trusts, and (we'll
   assume) all of ``Prelude``\'s imports are trusted. So ``C`` trusts
   ``Prelude``, and so ``C`` also trusts Buggle. (While ``Prelude`` is typically
   imported implicitly, it still obeys the same rules outlined here).
 
 Notice that C didn't need to trust package Wuggle; the machine checking
-is enough. C only needs to trust packages that contain ``-XTrustworthy``
+is enough. C only needs to trust packages that contain :ghc-flag:`-XTrustworthy`
 modules.
 
 .. _trustworthy-guarantees:
@@ -553,7 +553,7 @@ Trustworthy Requirements
 .. index::
    single: trustworthy
 
-Module authors using the ``-XTrustworthy`` language extension for a module ``M``
+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.
@@ -570,14 +570,20 @@ Safe Haskell gives packages a new Boolean property, that of trust.
 Several new options are available at the GHC command-line to specify the
 trust property of packages:
 
-- ``-trust ⟨pkg⟩`` — Exposes package ⟨pkg⟩ if it was hidden and considers it a
-  trusted package regardless of the package database.
+.. ghc-flag:: -trust ⟨pkg⟩
 
-- ``-distrust ⟨pkg⟩`` — 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 a
+   trusted package regardless of the package database.
 
-- ``-distrust-all-packages`` — Considers all packages distrusted unless they are
-  explicitly set to be trusted by subsequent command-line options.
+.. ghc-flag:: -distrust ⟨pkg⟩
+
+   Exposes package ⟨pkg⟩ if it was hidden and considers it
+   an untrusted package regardless of the package database.
+
+.. ghc-flag:: -distrust-all-packages
+
+   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`.
@@ -590,16 +596,16 @@ Safe Haskell Inference
 .. index::
    single: safe inference
 
-In the case where a module is compiled without one of ``-XSafe``,
-``-XTrustworthy`` or ``-XUnsafe`` being used, GHC will try to figure out
+In the case where a module is compiled without one of :ghc-flag:`-XSafe`,
+:ghc-flag:`-XTrustworthy` or :ghc-flag:`-XUnsafe` being used, GHC will try to figure out
 itself if the module can be considered safe. This safety inference will
 never mark a module as trustworthy, only as either unsafe or as safe.
 GHC uses a simple method to determine this for a module M: If M would
-compile without error under the ``-XSafe`` flag, then M is marked as
+compile without error under the :ghc-flag:`-XSafe` flag, then M is marked as
 safe. Otherwise, it is marked as unsafe.
 
 When should you use Safe Haskell inference and when should you use an
-explicit ``-XSafe`` flag? The later case should be used when you have a
+explicit :ghc-flag:`-XSafe` flag? The later case should be used when you have a
 hard requirement that the module be safe. This is most useful for the
 :ref:`safe-use-cases` of Safe Haskell: running untrusted code. Safe
 inference is meant to be used by ordinary Haskell programmers. Users who
@@ -631,9 +637,7 @@ Safe Haskell Flag Summary
 
 In summary, Safe Haskell consists of the following three language flags:
 
-``-XSafe``
-    .. index::
-       single: -XSafe
+.. ghc-flag:: -XSafe
 
     Restricts the module to the safe language. All of the module's
     direct imports must be trusted, but the module itself need not
@@ -646,33 +650,29 @@ In summary, Safe Haskell consists of the following three language flags:
     - *Haskell Language* — Restricted to Safe Language
     - *Imported Modules* — All forced to be safe imports, all must be trusted.
 
-``-XTrustworthy``
-    .. index::
-       single: -XTrustworthy
+.. ghc-flag:: -XTrustworthy
 
     This establishes that the module is trusted, but the guarantee is
     provided by the module's author. A client of this module then
     specifies that they trust the module author by specifying they trust
-    the package containing the module. ``-XTrustworthy`` doesn't restrict the
+    the package containing the module. :ghc-flag:`-XTrustworthy` doesn't restrict the
     module to the safe language. It does however restrict the resolution of
     overlapping instances to only allow :ref:`safe overlapping instances
     <safe-overlapping-instances>`. It also allows the use of the safe import
     keyword.
 
     - *Module Truste*  — Yes.
-    - *Module Truste*  (``-fpackage-trust`` enabled) — Yes but only if the package
+    - *Module Truste*  (:ghc-flag:`-fpackage-trust` enabled) — Yes but only if the package
        the module resides in is also trusted.
     - *Haskell Languag*  — Unrestricted, except only safe overlapping instances
       allowed.
     - *Imported Modules* — Under control of module author which ones must be
       trusted.
 
-``-XUnsafe``
-    .. index::
-       single: -XUnsafe
+.. ghc-flag:: -XUnsafe
 
     Mark a module as unsafe so that it can't be imported by code
-    compiled with ``-XSafe``. Also enable the Safe Import extension so that a
+    compiled with :ghc-flag:`-XSafe`. Also enable the Safe Import extension so that a
     module can require
     a dependency to be trusted.
 
@@ -683,24 +683,24 @@ In summary, Safe Haskell consists of the following three language flags:
 
 And one general flag:
 
-``-fpackage-trust``
+.. ghc-flag:: -fpackage-trust
     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.
 
 And three warning flags:
 
-``-Wunsafe``
+.. ghc-flag:: -Wunsafe
     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.
 
-``-Wsafe``
+.. ghc-flag:: -Wsafe
     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.
 
-``-Wtrustworthy-safe``
+.. ghc-flag:: -Wtrustworthy-safe
     Issue a warning 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
@@ -735,9 +735,9 @@ taken:
    source level pragma.
 
 -  Ensure that all untrusted code is imported as a
-   :ref:`safe import <safe-imports>`
-   and that the ``-fpackage-trust`` :ref:`flag <safe-package-trust>` is used
-   with packages from untrusted sources being marked as untrusted.
+   :ref:`safe import <safe-imports>` and that the :ghc-flag:`-fpackage-trust`
+   flag (see :ref:`flag <safe-package-trust>`) is used with packages from
+   untrusted sources being marked as untrusted.
 
 There is a more detailed discussion of the issues involved in
 compilation safety and some potential solutions on the