From 3e5d0f188d6c8633e55e9ba6c8941c07e459fa4b Mon Sep 17 00:00:00 2001
From: Ben Gamari <bgamari.foss@gmail.com>
Date: Mon, 24 Jul 2017 19:00:24 -0400
Subject: [PATCH] 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
---
docs/users_guide/8.2.1-notes.rst | 4 +-
docs/users_guide/conf.py | 41 ++++++++++++++++++
docs/users_guide/debug-info.rst | 2 +-
docs/users_guide/ffi-chap.rst | 6 +--
docs/users_guide/ghc_config.py.in | 18 +++++---
docs/users_guide/ghci.rst | 4 +-
docs/users_guide/glasgow_exts.rst | 62 ++++++++++++---------------
docs/users_guide/packages.rst | 8 ++--
docs/users_guide/parallel.rst | 3 +-
docs/users_guide/profiling.rst | 6 +--
docs/users_guide/runtime_control.rst | 6 +--
docs/users_guide/sooner.rst | 10 ++---
docs/users_guide/using-concurrent.rst | 10 ++---
docs/users_guide/win32-dlls.rst | 3 +-
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 43134faeba87..76fcc49f9d7f 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 3af6ac109ea0..9c75d5bf9706 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 b4056007b1d7..6a34431c843d 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 c65359664639..311146c4d974 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 7be8783dcf93..113d1b022f34 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 dce790416a14..fe481ae799d8 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 eb99959dbdbc..70960897c4c4 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 de7cc464d8be..c728acbd089f 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 68cbebf0d679..f334e1be3852 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 3d25e4699b0c..3f2e592944d0 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 5f64409b5a87..422eaa2ceb09 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 529e06213f7f..fbbb61da597d 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 270d0c1855aa..32e24256c33a 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 59c66683fa8b..26c3ffe3b012 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:
--
GitLab