users-guide: Make it easier to reference haddocks

Previously you had to painstakingly construct the URI to the haddock
documentation. Now the Python bits have enough smarts to construct this
themselves.

Reviewers: austin, patrickdoc

Reviewed By: patrickdoc

Subscribers: rwbarton, thomie

Differential Revision: https://phabricator.haskell.org/D3785

14 files changed, 108 insertions, 75 deletions

diff --git a/docs/users_guide/8.2.1-notes.rst b/docs/users_guide/8.2.1-notes.rst
index 43134faeba..76fcc49f9d 100644
--- a/docs/users_guide/8.2.1-notes.rst
+++ b/docs/users_guide/8.2.1-notes.rst
@@ -319,8 +319,8 @@ Runtime system
   move long-lived data outside of the heap so that the garbage
   collector does not have to trace it repeatedly.  Compacted data can
   also be serialized, stored, and deserialized again later by the same
-  program.  For more details see the :ghc-compact-ref:`GHC.Compact
-  <GHC-Compact.html>` module. Moreover, see the ``compact`` library on `Hackage
+  program. For more details see the :ghc-compact-ref:`GHC.Compact.` module.
+  Moreover, see the ``compact`` library on `Hackage
   <https://hackage.haskell.org/package/compact>`_ for a high-level interface.
 
 - There is new support for improving performance on machines with a
diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py
index 3af6ac109e..9c75d5bf97 100644
--- a/docs/users_guide/conf.py
+++ b/docs/users_guide/conf.py
@@ -11,6 +11,7 @@ import os
 # Support for :base-ref:, etc.
 sys.path.insert(0, os.path.abspath('.'))
 from ghc_config import extlinks, version
+import ghc_config
 
 extensions = ['sphinx.ext.extlinks', 'sphinx.ext.mathjax']
 
@@ -150,6 +151,37 @@ def parse_flag(env, sig, signode):
     # Reference name left unchanged
     return sig
 
+def haddock_role(lib):
+    """
+    For instance,
+     * reference to module:      :base-ref:`Control.Applicative.`
+     * reference to identifier:  :base-ref:`Control.Applicative.pure`
+     * reference to type:        :base-ref:`Control.Applicative.Applicative`
+    """
+    path = '%s/%s-%s' % (ghc_config.libs_base_uri, lib, ghc_config.lib_versions[lib])
+    def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+        try:
+            parts = text.split('.')
+            module_parts = parts[:-1]
+            thing = parts[-1]
+            if thing != '':
+                # reference to type or identifier
+                tag = 't' if thing[0].isupper() else 'v'
+                anchor = '#%s:%s' % (tag, thing)
+                link_text = text
+            else:
+                # reference to module
+                anchor = ''
+                link_text = '.'.join(module_parts)
+
+            uri = '%s/%s.html%s' % (path, '-'.join(module_parts), anchor)
+            node = nodes.reference(link_text, link_text, refuri=uri)
+            return [node], []
+        except ValueError:
+            msg = inliner.reporter.error('')
+
+    return role
+
 def setup(app):
     from sphinx.util.docfields import Field, TypedField
 
@@ -171,6 +203,15 @@ def setup(app):
                             Field('static')
                         ])
 
+    # Haddock references
+    app.add_role('th-ref', haddock_role('template-haskell'))
+    app.add_role('base-ref', haddock_role('base'))
+    app.add_role('cabal-ref', haddock_role('Cabal'))
+    app.add_role('ghc-compact-ref', haddock_role('ghc-compact'))
+    app.add_role('ghc-prim-ref', haddock_role('ghc-prim'))
+    app.add_role('parallel-ref', haddock_role('parallel'))
+    app.add_role('array-ref', haddock_role('array'))
+
     app.add_object_type('rts-flag', 'rts-flag',
                         objname='runtime system command-line option',
                         parse_node=parse_flag,
diff --git a/docs/users_guide/debug-info.rst b/docs/users_guide/debug-info.rst
index b4056007b1..6a34431c84 100644
--- a/docs/users_guide/debug-info.rst
+++ b/docs/users_guide/debug-info.rst
@@ -177,7 +177,7 @@ will be of little use unless debug information is available in the executable
 and its dependent libraries.
 
 Stack trace functionality is exposed for use by Haskell programs in the
-:base-ref:`GHC.ExecutionStack <GHC-ExecutionStack.html>` module. See the Haddock
+:base-ref:`GHC.ExecutionStack.` module. See the Haddock
 documentation in this module for details regarding usage.
 
 Requesting a stack trace with ``SIGUSR2``
diff --git a/docs/users_guide/ffi-chap.rst b/docs/users_guide/ffi-chap.rst
index c653596646..311146c4d9 100644
--- a/docs/users_guide/ffi-chap.rst
+++ b/docs/users_guide/ffi-chap.rst
@@ -23,8 +23,8 @@ Haskell 2010 Report. These extensions are described in :ref:`ffi-ghcexts`, but
 please note that programs using these features are not portable. Hence, these
 features should be avoided where possible.
 
-The FFI libraries are documented in the accompanying library
-documentation; see for example the :base-ref:`Foreign <Foreign.html>` module.
+The FFI libraries are documented in the accompanying  library
+documentation; see for example the :base-ref:`Foreign.` module.
 
 GHC differences to the FFI Chapter
 ----------------------------------
@@ -581,7 +581,7 @@ where it is useful to have more control over which OS thread is used,
 for example when calling foreign code that makes use of thread-local
 state. For cases like this, we provide *bound threads*, which are
 Haskell threads tied to a particular OS thread. For information on bound
-threads, see the documentation for the :base-ref:`Control.Concurrent <Control-Concurrent.html>` module.
+threads, see the documentation for the :base-ref:`Control.Concurrent.` module.
 
 Foreign exports and multi-threading
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/users_guide/ghc_config.py.in b/docs/users_guide/ghc_config.py.in
index 7be8783dcf..113d1b022f 100644
--- a/docs/users_guide/ghc_config.py.in
+++ b/docs/users_guide/ghc_config.py.in
@@ -1,12 +1,18 @@
 extlinks = {
-    'base-ref': ('../libraries/base-@LIBRARY_base_VERSION@/%s', ''),
-    'cabal-ref': ('../libraries/Cabal-@LIBRARY_Cabal_VERSION@/%s', ''),
-    'compact-ref': ('../libraries/ghc-compact-@LIBRARY_ghc_compact_VERSION@/%s', ''),
-    'ghc-prim-ref': ('../libraries/ghc-prim-@LIBRARY_ghc_prim_VERSION@/%s', ''),
-    'th-ref': ('../libraries/template-haskell-@LIBRARY_template_haskell_VERSION@/%s', ''),
-
     'ghc-ticket': ('https://ghc.haskell.org/trac/ghc/ticket/%s', 'Trac #'),
     'ghc-wiki': ('https://ghc.haskell.org/trac/ghc/wiki/%s', 'Trac #'),
 }
 
+libs_base_uri = '../libraries'
+lib_versions = {
+    'base': '@LIBRARY_base_VERSION@',
+    'ghc-prim': '@LIBRARY_ghc_prim_VERSION@',
+    'template-haskell': '@LIBRARY_template_haskell_VERSION@',
+    'ghc-compact': '@LIBRARY_ghc_compact_VERSION@',
+    'ghc': '@LIBRARY_ghc_VERSION@',
+    'parallel': '@LIBRARY_parallel_VERSION@',
+    'Cabal': '@LIBRARY_Cabal_VERSION@',
+    'array': '@LIBRARY_array_VERSION@',
+}
+
 version = '@ProjectVersion@'
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst
index dce790416a..fe481ae799 100644
--- a/docs/users_guide/ghci.rst
+++ b/docs/users_guide/ghci.rst
@@ -505,8 +505,8 @@ not to replace module loading but to make definitions in .ghci-files
 
 Any exceptions raised during the evaluation or execution of the
 statement are caught and printed by the GHCi command line interface (for
-more information on exceptions, see the module ``Control.Exception`` in
-the libraries :base-ref:`documentation <Control-Exception.html>`).
+more information on exceptions, see the module :base-ref:`Control.Exception.` in
+the libraries documentation.
 
 Every new binding shadows any existing bindings of the same name,
 including entities that are in scope in the current module context.
diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index eb99959dbd..70960897c4 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -73,7 +73,7 @@ case. And if it isn't, we'd like to know about it.
 
 All these primitive data types and operations are exported by the
 library ``GHC.Prim``, for which there is
-:ghc-prim-ref:`detailed online documentation <GHC-Prim.html>`. (This
+:ghc-prim-ref:`detailed online documentation <GHC.Prim.>`. (This
 documentation is generated from the file ``compiler/prelude/primops.txt.pp``.)
 
 If you want to mention any of the primitive data types or operations in
@@ -1342,7 +1342,7 @@ Monad comprehensions support:
 
    Parallel statements are translated using the ``mzip`` function, which
    requires a ``MonadZip`` instance defined in
-   :base-ref:`Control.Monad.Zip <Control-Monad-Zip.html>`:
+   :base-ref:`Control.Monad.Zip.`:
 
    ::
 
@@ -3273,7 +3273,7 @@ More details:
 Record field selector polymorphism
 ----------------------------------
 
-The module :base-ref:`GHC.Records <GHC-Records.html>` defines the following: ::
+The module :base-ref:`GHC.Records.` defines the following: ::
 
   class HasField (x :: k) r a | x r -> a where
     getField :: r -> a
@@ -6382,7 +6382,7 @@ argument in GHC 8.0, but this was removed in GHC 8.2 as a type application (see
 
 There are no predefined instances of this class.  It is not in scope by default,
 but can be brought into scope by importing
-:base-ref:`GHC.OverloadedLabels <GHC-OverloadedLabels.html>`.  Unlike
+:base-ref:`GHC.OverloadedLabels.`.  Unlike
 ``IsString``, there are no special defaulting rules for ``IsLabel``.
 
 During typechecking, GHC will replace an occurrence of an overloaded label like
@@ -8750,10 +8750,9 @@ The ``Coercible`` constraint
 
 The constraint ``Coercible t1 t2`` is similar to ``t1 ~ t2``, but
 denotes representational equality between ``t1`` and ``t2`` in the sense
-of Roles (:ref:`roles`). It is exported by
-:base-ref:`Data.Coerce <Data-Coerce.html>`, which also
-contains the documentation. More details and discussion can be found in
-the paper
+of Roles (:ref:`roles`). It is exported by :base-ref:`Data.Coerce.`, which also
+contains the documentation. More details and discussion can be found in the
+paper
 `"Safe Coercions" <http://www.cis.upenn.edu/~eir/papers/2014/coercible/coercible.pdf>`__.
 
 .. _constraint-kind:
@@ -10610,7 +10609,7 @@ for constructing pretty-printed error messages, ::
         | ErrorMessage :<>: ErrorMessage     -- Put two chunks of error message next to each other
         | ErrorMessage :$$: ErrorMessage     -- Put two chunks of error message above each other
 
-in the ``GHC.TypeLits`` :base-ref:`module <GHC-TypeLits.html>`.
+in the :base-ref:`GHC.TypeLits.` module.
 
 For instance, we might use this interface to provide a more useful error
 message for applications of ``show`` on unsaturated functions like this, ::
@@ -10748,7 +10747,7 @@ Haskell <http://research.microsoft.com/~simonpj/papers/meta-haskell/>`__"
 
 The `Template Haskell <http://www.haskell.org/haskellwiki/Template_Haskell>`__
 page on the GHC Wiki has a wealth of information. You may also consult the
-:th-ref:`Haddock reference documentation <Language-Haskell-TH.html>`.
+:th-ref:`Haddock reference documentation <Language.Haskell.TH.>`.
 Many changes to the original
 design are described in `Notes on Template Haskell version
 2 <http://research.microsoft.com/~simonpj/papers/meta-haskell/notes2.ps>`__.
@@ -11495,7 +11494,7 @@ more details, see
 
 With the :ghc-flag:`-XArrows` flag, GHC supports the arrow notation described in
 the second of these papers, translating it using combinators from the
-:base-ref:`Control.Arrow <Control-Arrow.html>` module.
+:base-ref:`Control.Arrow.` module.
 What follows is a brief introduction to the notation; it won't make much
 sense unless you've read Hughes's paper.
 
@@ -11595,8 +11594,8 @@ You can read this much like ordinary ``do``-notation, but with commands
 in place of monadic expressions. The first line sends the value of
 ``x+1`` as an input to the arrow ``f``, and matches its output against
 ``y``. In the next line, the output is discarded. The arrow ``returnA``
-is defined in the :base-ref:`Control.Arrow <Control-Arrow.html>` module as ``arr
-id``. The above example is treated as an abbreviation for ::
+is defined in the :base-ref:`Control.Arrow.` module as ``arr id``. The above
+example is treated as an abbreviation for ::
 
     arr (\ x -> (x, x)) >>>
             first (arr (\ x -> x+1) >>> f) >>>
@@ -11610,8 +11609,7 @@ id``. The above example is treated as an abbreviation for ::
 
 Note that variables not used later in the composition are projected out.
 After simplification using rewrite rules (see :ref:`rewrite-rules`)
-defined in the :base-ref:`Control.Arrow <Control-Arrow.html>` module, this
-reduces to ::
+defined in the :base-ref:`Control.Arrow.` module, this reduces to ::
 
     arr (\ x -> (x+1, x)) >>>
             first f >>>
@@ -11853,7 +11851,7 @@ to check arrow programs with GHC; tracing type errors in the
 preprocessor output is not easy. Modules intended for both GHC and the
 preprocessor must observe some additional restrictions:
 
--  The module must import :base-ref:`Control.Arrow <Control-Arrow.html>`.
+-  The module must import :base-ref:`Control.Arrow.`.
 
 -  The preprocessor cannot cope with other Haskell extensions. These
    would have to go in separate modules.
@@ -12388,7 +12386,7 @@ will be rewritten to ``e``. You can also disable assertions using the
 allows enabling assertions even when optimisation is turned on.
 
 Assertion failures can be caught, see the documentation for the
-:base-ref:`Control.Exception <Control-Exception.html>` library for the details.
+:base-ref:`Control.Exception` library for the details.
 
 .. _static-pointers:
 
@@ -12425,12 +12423,11 @@ Using static pointers
 ---------------------
 
 Each reference is given a key which can be used to locate it at runtime
-with
-:base-ref:`unsafeLookupStaticPtr <GHC-StaticPtr.html#v%3AunsafeLookupStaticPtr>`
+with :base-ref:`GHC.StaticPtr.unsafeLookupStaticPtr`
 which uses a global and immutable table called the Static Pointer Table.
 The compiler includes entries in this table for all static forms found
 in the linked modules. The value can be obtained from the reference via
-:base-ref:`deRefStaticPtr <GHC-StaticPtr.html#v%3AdeRefStaticPtr>`.
+:base-ref:`GHC.StaticPtr.deRefStaticPtr`.
 
 The body ``e`` of a ``static e`` expression must be a closed expression. Where
 we say an expression is *closed* when all of its free (type) variables are
@@ -12491,7 +12488,7 @@ The only predefined instance is the obvious one that does nothing: ::
     instance IsStatic StaticPtr where
         fromStaticPtr sptr = sptr
 
-See :base-ref:`IsStatic <GHC-StaticPtr.html#t%3AIsStatic>`.
+See :base-ref:`GHC.StaticPtr.IsStatic`.
 
 Furthermore, type ``t`` is constrained to have a ``Typeable`` instance.
 The following are therefore illegal: ::
@@ -12587,9 +12584,8 @@ A list of all supported language extensions can be obtained by invoking
 ``ghc --supported-extensions`` (see :ghc-flag:`--supported-extensions`).
 
 Any extension from the ``Extension`` type defined in
-:cabal-ref:`Language.Haskell.Extension <Language-Haskell-Extension.html>`
-may be used. GHC will report an error if any of the requested extensions
-are not supported.
+:cabal-ref:`Language.Haskell.Extension.` may be used. GHC will report an error
+if any of the requested extensions are not supported.
 
 .. _options-pragma:
 
@@ -13870,14 +13866,12 @@ Special built-in functions
 
 GHC has a few built-in functions with special behaviour. In particular:
 
--  :base-ref:`inline <GHC-Exts.html#v%3Ainline>`
-   allows control over inlining on a per-call-site basis.
+-  :base-ref:`GHC.Exts.inline` allows control over inlining on a per-call-site basis.
 
--  :base-ref:`lazy <GHC-Exts.html#v%3Alazy>` restrains the strictness analyser.
+-  :base-ref:`GHC.Exts.lazy` restrains the strictness analyser.
 
--  :base-ref:`oneShot <GHC-Exts.html#v%3AoneShot>`
-   gives a hint to the compiler about how often a function is being
-   called.
+-  :base-ref:`GHC.Exts.oneShot` gives a hint to the compiler about how often a
+   function is being called.
 
 .. _generic-classes:
 
@@ -13896,11 +13890,9 @@ Generic programming
 ===================
 
 Using a combination of :ghc-flag:`-XDeriveGeneric`,
-:ghc-flag:`-XDefaultSignatures`, and
-:ghc-flag:`-XDeriveAnyClass`, you can easily do
-datatype-generic programming using the :base-ref:`GHC.Generics
-<GHC-Generics.html>` framework. This section gives a very brief overview of how
-to do it.
+:ghc-flag:`-XDefaultSignatures`, and :ghc-flag:`-XDeriveAnyClass`, you can
+easily do datatype-generic programming using the :base-ref:`GHC.Generics.`
+framework. This section gives a very brief overview of how to do it.
 
 Generic programming support in GHC allows defining classes with methods
 that do not need a user specification when instantiating: the method
diff --git a/docs/users_guide/packages.rst b/docs/users_guide/packages.rst
index de7cc464d8..c728acbd08 100644
--- a/docs/users_guide/packages.rst
+++ b/docs/users_guide/packages.rst
@@ -24,8 +24,7 @@ package. All you need to do is write a simple configuration file, put a
 few files in the right places, and you have a package. See the `Cabal
 documentation <http://www.haskell.org/cabal/users-guide/>`__ for
 details, and also the Cabal libraries
-(:cabal-ref:`Distribution.Simple <Distribution-Simple.html>`,
-for example).
+(:cabal-ref:`Distribution.Simple.`, for example).
 
 .. _using-packages:
 
@@ -1033,8 +1032,7 @@ package as well.
 -------------------------------------------------
 
 A package specification is a Haskell record; in particular, it is the
-record
-:cabal-ref:`InstalledPackageInfo <Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo>`
+record :cabal-ref:`Distribution.InstalledPackageInfo.InstalledPackageInfo`
 in the module Distribution.InstalledPackageInfo, which is part of the
 Cabal package distributed with GHC.
 
@@ -1142,7 +1140,7 @@ The allowed fields, with their types, are:
 
     (string) The type of license under which this package is
     distributed. This field is a value of the
-    :cabal-ref:`License <Distribution-License.html#t:License>` type.
+    :cabal-ref:`Distribution.License.License` type.
 
 ``license-file``
     .. index::
diff --git a/docs/users_guide/parallel.rst b/docs/users_guide/parallel.rst
index 68cbebf0d6..f334e1be38 100644
--- a/docs/users_guide/parallel.rst
+++ b/docs/users_guide/parallel.rst
@@ -37,8 +37,7 @@ squad <http://research.microsoft.com/%7Esimonpj/papers/marktoberdorf/>`__.
 
 To the programmer, Concurrent Haskell introduces no new language
 constructs; rather, it appears simply as a library,
-:base-ref:`Control.Concurrent <Control-Concurrent.html>`.
-The functions exported by this library include:
+:base-ref:`Control.Concurrent.`. The functions exported by this library include:
 
 -  Forking and killing threads.
 
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index 3d25e4699b..3f2e592944 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -349,9 +349,9 @@ for all modules in a program.
 
     Adds an automatic ``SCC`` annotation to all *call sites*. This is
     particularly useful when using profiling for the purposes of
-    generating stack traces; see the function :base-ref:`traceStack <Debug-Trace.html#traceShow>` in the
-    module ``Debug.Trace``, or the :rts-flag:`-xc` RTS flag
-    (:ref:`rts-options-debugging`) for more details.
+    generating stack traces; see the function :base-ref:`Debug.Trace.traceShow`,
+    or the :rts-flag:`-xc` RTS flag (:ref:`rts-options-debugging`) for more
+    details.
 
 .. ghc-flag:: -fprof-cafs
 
diff --git a/docs/users_guide/runtime_control.rst b/docs/users_guide/runtime_control.rst
index 5f64409b5a..422eaa2ceb 100644
--- a/docs/users_guide/runtime_control.rst
+++ b/docs/users_guide/runtime_control.rst
@@ -247,7 +247,7 @@ Miscellaneous RTS options
     :default: 100k
 
     This option relates to allocation limits; for more about this see
-    :base-ref:`enableAllocationLimit <GHC-Conc.html#v%3AenableAllocationLimit>`.
+    :base-ref:`GHC.Conc.enableAllocationLimit`.
     When a thread hits its allocation limit, the RTS throws an exception
     to the thread, and the thread gets an additional quota of allocation
     before the exception is raised again, the idea being so that the
@@ -439,7 +439,7 @@ performance.
     parallel GC completely, reverting to sequential GC.
 
     The default parallel GC settings are usually suitable for parallel programs
-    (i.e. those using :base-ref:`par <GHC-Conc.html#v:par>`, Strategies, or with
+    (i.e. those using :base-ref:`GHC.Conc.par`, Strategies, or with
     multiple threads). However, it is sometimes beneficial to enable the
     parallel GC for a single-threaded sequential program too, especially if the
     program has a large amount of heap data and GC is a significant fraction of
@@ -732,7 +732,7 @@ RTS options to produce runtime statistics
     output is sent to ``stderr``.
 
     If you use the ``-T`` flag then, you should access the statistics
-    using :base-ref:`GHC.Stats <GHC-Stats.html>`.
+    using :base-ref:`GHC.Stats.`.
 
     If you use the ``-t`` flag then, when your program finishes, you
     will see something like this:
diff --git a/docs/users_guide/sooner.rst b/docs/users_guide/sooner.rst
index 529e06213f..fbbb61da59 100644
--- a/docs/users_guide/sooner.rst
+++ b/docs/users_guide/sooner.rst
@@ -298,9 +298,9 @@ Don't use ``Float``\s:
 Use unboxed arrays (``UArray``)
     GHC supports arrays of unboxed elements, for several basic
     arithmetic element types including ``Int`` and ``Char``: see the
-    ``Data.Array.Unboxed`` library for details. These arrays are likely
-    to be much faster than using standard Haskell 98 arrays from the
-    ``Data.Array`` library.
+    :array-ref:`Data.Array.Unboxed.` library for details. These arrays are
+    likely to be much faster than using standard Haskell 98 arrays from the
+    :array-ref:`Data.Array.` library.
 
 Use a bigger heap!
     If your program's GC stats (:rts-flag:`-S [⟨file⟩]` RTS option) indicate
@@ -312,7 +312,7 @@ Use a bigger heap!
     to let GHC calculate a value based on the amount of live data.
 
 Compact your data:
-    The :ghc-compact-ref:`GHC.Compact <GHC-Compact.html>` module
+    The :ghc-compact-ref:`GHC.Compact.` module
     provides a way to make garbage collection more efficient for
     long-lived data structures. Compacting a data structure collects
     the objects together in memory, where they are treated as a single
@@ -334,7 +334,7 @@ Warning: except in certain specialised cases (like Happy parsers) this is likely
 to actually *increase* the size of your program, because unfolding generally
 enables extra simplifying optimisations to be performed.
 
-Avoid ``Read``.
+Avoid :base-ref:`Prelude.Read`.
 
 Use :command:`strip` on your executables.
 
diff --git a/docs/users_guide/using-concurrent.rst b/docs/users_guide/using-concurrent.rst
index 270d0c1855..32e24256c3 100644
--- a/docs/users_guide/using-concurrent.rst
+++ b/docs/users_guide/using-concurrent.rst
@@ -9,9 +9,8 @@ Using Concurrent Haskell
 GHC supports Concurrent Haskell by default, without requiring a special
 option or libraries compiled in a certain way. To get access to the
 support libraries for Concurrent Haskell, just import
-:base-ref:`Control.Concurrent <Control-Concurrent.html>`.
-More information on Concurrent Haskell is provided in the documentation
-for that module.
+:base-ref:`Control.Concurrent.`. More information on Concurrent Haskell is
+provided in the documentation for that module.
 
 Optionally, the program may be linked with the :ghc-flag:`-threaded` option (see
 :ref:`options-linker`. This provides two benefits:
@@ -104,8 +103,7 @@ RTS options for SMP parallelism
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There are two ways to run a program on multiple processors: call
-:base-ref:`Control.Concurrent.setNumCapabilities
-<Control.Concurrent.html#v:setNumCapabilities>` from your program, or
+:base-ref:`Control.Concurrent.setNumCapabilities` from your program, or
 use the RTS :rts-flag:`-N ⟨x⟩` options.
 
 .. rts-flag:: -N ⟨x⟩
@@ -174,7 +172,7 @@ CPUs:
 
     This option is probably only of use for concurrent programs that
     explicitly schedule threads onto CPUs with
-    :base-ref:`Control.Concurrent.forkOn <Control-Concurrent.html#v:forkOn>`.
+    :base-ref:`Control.Concurrent.forkOn`.
 
 Hints for using SMP parallelism
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/users_guide/win32-dlls.rst b/docs/users_guide/win32-dlls.rst
index 59c66683fa..26c3ffe3b0 100644
--- a/docs/users_guide/win32-dlls.rst
+++ b/docs/users_guide/win32-dlls.rst
@@ -53,8 +53,7 @@ afterwards has no effect on the shell.
 
 This problem doesn't just affect GHCi, it affects any GHC-compiled
 program that wants to catch console events. See the
-:base-ref:`GHC.ConsoleHandler <GHC-ConsoleHandler.html>`
-module.
+:base-ref:`GHC.ConsoleHandler.` module.
 
 .. _terminal-interaction: