Merge branch 'ghc-8.8' into ghc-8.10

2 files changed, 15 insertions, 10 deletions

diff --git a/doc/invoking.rst b/doc/invoking.rst
index 9fd8f961..4e4b8764 100644
--- a/doc/invoking.rst
+++ b/doc/invoking.rst
@@ -330,7 +330,7 @@ The following options are available:
     reader can switch between themes with browsers that support
     alternate style sheets, or with the "Style" menu that gets added
     when the page is loaded. If no themes are specified, then just the
-    default built-in theme ("NewOcean") is used.
+    default built-in theme ("Linuwial") is used.
 
     The path parameter can be one of:
 
@@ -342,11 +342,11 @@ The following options are available:
     -  A *CSS file*: The base name of the file becomes the name of the
        theme.
 
-    -  The *name* of a built-in theme ("NewOcean", "Ocean", or "Classic").
+    -  The *name* of a built-in theme ("Linuwial", "Ocean", or "Classic").
 
 .. option:: --built-in-themes
 
-    Includes the built-in themes ("NewOcean", "Ocean", and "Classic"). Can be
+    Includes the built-in themes ("Linuwial", "Ocean", and "Classic"). Can be
     combined with :option:`--theme`. Note that order matters: The first
     specified theme will be the default.
 
diff --git a/doc/markup.rst b/doc/markup.rst
index 8f926961..08510804 100644
--- a/doc/markup.rst
+++ b/doc/markup.rst
@@ -913,6 +913,16 @@ If ``M.T`` is not otherwise in scope, then Haddock will simply emit a
 link pointing to the entity ``T`` exported from module ``M`` (without
 checking to see whether either ``M`` or ``M.T`` exist).
 
+Since values and types live in different namespaces in Haskell, it is
+possible for a reference such as ``'X'`` to be ambiguous. In such a case,
+Haddock defaults to pointing to the type. The ambiguity can be overcome by explicitly specifying a namespace, by way of a ``v`` (for value) or ``t``
+(for type) immediately before the link: ::
+
+    -- | An implicit reference to  'X', the type constructor
+    --   An explicit reference to v'X', the data constructor
+    --   An explicit reference to t'X', the type constructor
+    data X = X
+
 To make life easier for documentation writers, a quoted identifier is
 only interpreted as such if the quotes surround a lexically valid
 Haskell identifier. This means, for example, that it normally isn't
@@ -922,14 +932,9 @@ necessary to escape the single quote when used as an apostrophe: ::
 
 Nothing special is needed to hyperlink identifiers which contain
 apostrophes themselves: to hyperlink ``foo'`` one would simply type
-``'foo''``. Hyperlinking operators works in exactly the same way.
-
-Note that it is not possible to directly hyperlink an identifier in infix
-form or an operator in prefix form. The next best thing to do is to wrap
-the whole identifier in monospaced text and put the parentheses/backticks
-outside of the identifier, but inside the link: ::
+``'foo''``. Hyperlinking operators works in exactly the same way. ::
 
-    -- | A prefix operator @('++')@ and an infix identifier @\``elem`\`@.
+    -- | A prefix operator @'(++)'@ and an infix identifier @'`elem`'@.
 
 Emphasis, Bold and Monospaced Text
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~