Merge remote-tracking branch 'upstream/ghc-9.2' into ghc-head

11 files changed, 102 insertions, 106 deletions

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c2aa9f3c..dafcdc74 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -13,7 +13,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        cabal: ["3.4.0.0"]
+        cabal: ["3.6"]
         ghc:
           - "head"
 
@@ -41,12 +41,11 @@ jobs:
         cabal freeze
  
     - uses: actions/cache@v2
-      name: Cache ~/.cabal/store and .ghcup
+      name: Cache ~/.cabal/store
       with:
         path: |
           ${{ steps.setup-haskell-cabal.outputs.cabal-store }}
-          .ghcup
-        key: ${{ runner.os }}
+        key: ${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('cabal.project.freeze') }}
 
     - name: Build
       run: |
diff --git a/README.md b/README.md
index 69763a52..530e752d 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 Haddock is the standard tool for generating documentation from Haskell code.
 Full documentation about Haddock itself can be found in the `doc/` subdirectory,
-in [reStructedText format][ReST] format.
+in [reStructuredText][reST] format.
 
 ## Project overview
 
@@ -25,10 +25,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) to see how to make contributions to the
 project.
 
 
-[CI page]: https://travis-ci.org/haskell/haddock
-[CI badge]: https://travis-ci.org/haskell/haddock.svg?branch=ghc-8.10
+[CI page]: https://github.com/haskell/haddock/actions/workflows/ci.yml
+[CI badge]: https://github.com/haskell/haddock/actions/workflows/ci.yml/badge.svg
 [Hackage page]: https://hackage.haskell.org/package/haddock
 [Hackage badge]: https://img.shields.io/hackage/v/haddock.svg
-[ReST]: http://www.sphinx-doc.org/en/stable/rest.html
+[reST]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
 [Documentation.Haddock]: http://hackage.haskell.org/package/haddock-api/docs/Documentation-Haddock.html
-[cabal v2]: http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+[cabal v2]: https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
diff --git a/doc/common-errors.rst b/doc/common-errors.rst
new file mode 100644
index 00000000..9afa4ea7
--- /dev/null
+++ b/doc/common-errors.rst
@@ -0,0 +1,19 @@
+Common Errors
+=============
+
+``parse error on input ‘-- | xxx’``
+-----------------------------------
+
+This is probably caused by the ``-- | xxx`` comment not following a declaration. I.e. use ``-- xxx`` instead. See :ref:`top-level-declaration`.
+
+``parse error on input ‘-- $ xxx’``
+----------------------------------
+
+You've probably commented out code like::
+
+  f x
+    $ xxx
+    
+``-- $`` is a special syntax for named chunks, see :ref:`named-chunks`. You can fix this by escaping the ``$``::
+
+  -- \$ xxx
diff --git a/doc/index.rst b/doc/index.rst
index 0d1b8b48..f370e42f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -12,6 +12,7 @@ Contents:
    intro
    invoking
    markup
+   common-errors
    multi-components
 
 
diff --git a/doc/intro.rst b/doc/intro.rst
index fc1269f9..1f4234cb 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -25,7 +25,7 @@ in mind:
    The easier it is to write documentation, the more likely the
    programmer is to do it. Haddock therefore uses lightweight markup in
    its annotations, taking several ideas from
-   `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact,
+   `IDoc <https://web.archive.org/web/20180621053227/http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact,
    Haddock can understand IDoc-annotated source code.
 
 -  The documentation should not expose any of the structure of the
@@ -59,8 +59,8 @@ in mind:
 Obtaining Haddock
 -----------------
 
-Distributions (source & binary) of Haddock can be obtained from its `web
-site <http://www.haskell.org/haddock/>`__.
+Haddock is distributed with GHC distributions, and will automatically be provided if you use 
+`ghcup <https://www.haskell.org/ghcup>`__, for instance.
 
 Up-to-date sources can also be obtained from our public GitHub
 repository. The Haddock sources are at
@@ -72,77 +72,38 @@ License
 The following license covers this documentation, and the Haddock source
 code, except where otherwise indicated.
 
-    Copyright 2002-2010, Simon Marlow. All rights reserved.
+    Copyright (c) 2002-2010, Simon Marlow
+    All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions
-    are met:
+    modification, are permitted provided that the following conditions are
+    met:
 
-    -  Redistributions of source code must retain the above copyright
+    1. Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.
 
-    -  Redistributions in binary form must reproduce the above copyright
-       notice, this list of conditions and the following disclaimer in
-       the documentation and/or other materials provided with the
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the
        distribution.
 
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS IS" AND ANY
-    EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE
-    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
-    BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
-    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 Contributors
 ------------
 
-Haddock was originally written by Simon Marlow. Since it is an open
-source project, many people have contributed to its development over the
-years. Below is a list of contributors in alphabetical order that we
-hope is somewhat complete. If you think you are missing from this list,
-please contact us.
-
--  Ashley Yakeley
--  Benjamin Franksen
--  Brett Letner
--  Clemens Fruhwirth
--  Conal Elliott
--  David Waern
--  Duncan Coutts
--  George Pollard
--  George Russel
--  Hal Daume
--  Ian Lynagh
--  Isaac Dupree
--  Joachim Breitner
--  Krasimir Angelov
--  Lennart Augustsson
--  Luke Plant
--  Malcolm Wallace
--  Manuel Chakravarty
--  Marcin Szamotulski
--  Mark Lentczner
--  Mark Shields
--  Mateusz Kowalczyk
--  Mike Thomas
--  Neil Mitchell
--  Oliver Brown
--  Roman Cheplyaka
--  Ross Paterson
--  Sigbjorn Finne
--  Simon Hengel
--  Simon Marlow
--  Simon Peyton-Jones
--  Stefan O'Rear
--  Sven Panne
--  Thomas Schilling
--  Wolfgang Jeltsch
--  Yitzchak Gale
+A list of contributors to the project can be seen at
+``https://github.com/haskell/haddock/graphs/contributors``.
 
 Acknowledgements
 ----------------
@@ -150,11 +111,11 @@ Acknowledgements
 Several documentation systems provided the inspiration for Haddock, most
 notably:
 
--  `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__
+-  `IDoc <https://web.archive.org/web/20180621053227/http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__
 
--  `HDoc <http://www.fmi.uni-passau.de/~groessli/hdoc/>`__
+-  `HDoc <https://mail.haskell.org/pipermail/haskelldoc/2001-April/000067.html>`__
 
--  `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__
+-  `Doxygen <https://www.doxygen.nl/index.html>`__
 
 and probably several others I've forgotten.
 
diff --git a/doc/markup.rst b/doc/markup.rst
index c0b08a40..abfeb52a 100644
--- a/doc/markup.rst
+++ b/doc/markup.rst
@@ -950,24 +950,30 @@ apostrophes themselves: to hyperlink ``foo'`` one would simply type
 
     -- | A prefix operator @'(++)'@ and an infix identifier @'`elem`'@.
 
-Emphasis, Bold and Monospaced Text
+Emphasis, Bold and Monospaced styled Text
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Emphasis may be added by surrounding text with ``/.../``. Other markup
-is valid inside emphasis. To have a forward slash inside of emphasis,
-just escape it: ``/fo\/o/``
+Text can be emphasized, made bold (strong) or monospaced (typewriter font) 
+by surrounding it with slashes, double-underscores or at-symbols: ::
 
-Bold (strong) text is indicated by surrounding it with ``__...__``.
-Other markup is valid inside bold. For example, ``__/foo/__`` will make
-the emphasised text ``foo`` bold. You don't have to escape a single
-underscore if you need it bold:
-``__This_text_with_underscores_is_bold__``.
+    -- | This is /emphasized text/, __bold text__ and @monospaced text@.
 
-Monospaced (or typewriter) text is indicated by surrounding it with
-``@...@``. Other markup is valid inside a monospaced span: for example
-``@'f' a b@`` will hyperlink the identifier ``f`` inside the code
-fragment, but ``@__FILE__@`` will render ``FILE`` in bold with no
-underscores, which may not be what you had in mind.
+Note that those styled texts must be kept on the same line: ::
+
+    -- | Styles /do not work
+    -- | when continuing on the next line/
+
+Other markup is valid inside emphasized, bold and monospaced text.
+
+Frequent special cases: 
+
+* To have a forward slash inside of emphasis, just escape it: ``/fo\/o/``.
+* There's no need to escape a single underscore if you need it
+  bold: ``__This_text_with_underscores_is_bold__``.
+* ``@'f' a b@`` will hyperlink the identifier ``f`` inside the code
+  fragment.
+* ``@__FILE__@`` will render ``FILE`` in bold with no underscores, 
+  which may not be what you had in mind.
 
 Linking to Modules
 ~~~~~~~~~~~~~~~~~~
@@ -1121,6 +1127,17 @@ followed by the URL enclosed in regular parentheses, for example: ::
 The link text is used as a description for the URL if the output
 format supports it.
 
+Hint: There's a `known issue <https://github.com/haskell/haddock/issues/774>`_ 
+that any inline link at the beginning of a line within a multi-line comment 
+isn't rendered correctly: ::
+   
+    {-| Some multi-line comment that has a
+    [link](https://example.com) and a
+    [reference link]: https://example.com
+    -}
+    
+Adding a space or a word in front of such a link can be used as a workaround.   
+   
 Images
 ~~~~~~
 
diff --git a/haddock-api/haddock-api.cabal b/haddock-api/haddock-api.cabal
index cd02bf25..9770061c 100644
--- a/haddock-api/haddock-api.cabal
+++ b/haddock-api/haddock-api.cabal
@@ -1,6 +1,6 @@
 cabal-version:        2.0
 name:                 haddock-api
-version:              2.24.0
+version:              2.26.0
 synopsis:             A documentation-generation tool for Haskell libraries
 description:          Haddock is a documentation-generation tool for Haskell
                       libraries
@@ -13,7 +13,7 @@ bug-reports:          https://github.com/haskell/haddock/issues
 copyright:            (c) Simon Marlow, David Waern
 category:             Documentation
 build-type:           Simple
-tested-with:          GHC==9.0.*
+tested-with:          GHC==9.2.*
 
 extra-source-files:
   CHANGES.md
@@ -180,11 +180,11 @@ test-suite spec
     Haddock.Backends.Hyperlinker.Parser
     Haddock.Backends.Hyperlinker.Types
 
-  build-depends: ghc             ^>= 9.1
+  build-depends: ghc             ^>= 9.3
                , ghc-paths       ^>= 0.1.0.12
                , haddock-library ^>= 1.9.0
                , xhtml           ^>= 3000.2.2
-               , hspec           >= 2.4.4 && < 2.8
+               , hspec           ^>= 2.9
                , parsec          ^>= 3.1.13.0
                , QuickCheck      >= 2.11  && ^>= 2.14
 
@@ -201,10 +201,11 @@ test-suite spec
                , filepath
                , ghc-boot
                , ghc-boot-th
+               , mtl
                , transformers
 
   build-tool-depends:
-    hspec-discover:hspec-discover >= 2.4.4 && < 2.8
+    hspec-discover:hspec-discover ^>= 2.9
 
 source-repository head
   type:     git
diff --git a/haddock-api/src/Haddock/Backends/Hyperlinker.hs b/haddock-api/src/Haddock/Backends/Hyperlinker.hs
index 68e03fd5..89828e30 100644
--- a/haddock-api/src/Haddock/Backends/Hyperlinker.hs
+++ b/haddock-api/src/Haddock/Backends/Hyperlinker.hs
@@ -114,4 +114,3 @@ highlightScript = "highlight.js"
 -- | Path to default CSS file.
 defaultCssFile :: FilePath -> FilePath
 defaultCssFile libdir = libdir </> "html" </> "solarized.css"
-
diff --git a/haddock-library/haddock-library.cabal b/haddock-library/haddock-library.cabal
index 72c11f75..f6d88c81 100644
--- a/haddock-library/haddock-library.cabal
+++ b/haddock-library/haddock-library.cabal
@@ -28,6 +28,7 @@ tested-with:          GHC == 7.4.2
                     , GHC == 8.8.3
                     , GHC == 8.10.1
                     , GHC == 9.0.1
+                    , GHC == 9.2.0
 
 extra-source-files:
   CHANGES.md
@@ -39,10 +40,8 @@ common lib-defaults
 
   build-depends:
     , base         >= 4.5     && < 4.17
-    , bytestring   ^>= 0.9.2.1 || ^>= 0.10.0.0 || ^>= 0.11.0.0
     , containers   ^>= 0.4.2.1 || ^>= 0.5.0.0 || ^>= 0.6.0.1
-    , transformers ^>= 0.3.0.0 || ^>= 0.4.1.0 || ^>= 0.5.0.0
-    , text         ^>= 1.2.3.0
+    , text         ^>= 1.2.3.0 || ^>= 2.0
     , parsec       ^>= 3.1.13.0
 
   ghc-options: -funbox-strict-fields -Wall
@@ -87,7 +86,7 @@ test-suite spec
     Documentation.Haddock.Parser.Identifier
 
   build-depends:
-    , QuickCheck   ^>= 2.11  || ^>= 2.13.2 || ^>= 2.14
+    , QuickCheck   ^>= 2.11  || ^>= 2.13.2 || ^>= 2.14 
     , deepseq      ^>= 1.3.0.0 || ^>= 1.4.0.0
 
   -- NB: build-depends & build-tool-depends have independent
@@ -95,10 +94,10 @@ test-suite spec
   --     version of `hspec` & `hspec-discover` to ensure
   --     intercompatibility
   build-depends:
-    , hspec                          >= 2.4.4    && < 2.8
+    , hspec                          >= 2.4.4    && < 2.10
 
   build-tool-depends:
-    , hspec-discover:hspec-discover  >= 2.4.4    && < 2.8
+    , hspec-discover:hspec-discover  >= 2.4.4    && < 2.10
 
 test-suite fixtures
   type:             exitcode-stdio-1.0
@@ -116,7 +115,7 @@ test-suite fixtures
     , directory             ^>= 1.3.0.2
     , filepath              ^>= 1.4.1.2
     , optparse-applicative  ^>= 0.15
-    , tree-diff             ^>= 0.1
+    , tree-diff             ^>= 0.2
 
 source-repository head
   type:     git
diff --git a/haddock-test/src/Test/Haddock/Config.hs b/haddock-test/src/Test/Haddock/Config.hs
index e4829588..2905dc8f 100644
--- a/haddock-test/src/Test/Haddock/Config.hs
+++ b/haddock-test/src/Test/Haddock/Config.hs
@@ -18,7 +18,7 @@ import Data.Maybe
 import Distribution.Text
 import Distribution.Types.PackageName
 import Distribution.InstalledPackageInfo
-import Distribution.Simple.Compiler
+import Distribution.Simple.Compiler (PackageDB(..))
 import Distribution.Simple.GHC
 import Distribution.Simple.PackageIndex
 import Distribution.Simple.Program
diff --git a/haddock.cabal b/haddock.cabal
index dfb4e9a9..0686289e 100644
--- a/haddock.cabal
+++ b/haddock.cabal
@@ -1,6 +1,6 @@
 cabal-version:        2.4
 name:                 haddock
-version:              2.24.0
+version:              2.26.0
 synopsis:             A documentation-generation tool for Haskell libraries
 description:
   This is Haddock, a tool for automatically generating documentation
@@ -33,7 +33,7 @@ bug-reports:          https://github.com/haskell/haddock/issues
 copyright:            (c) Simon Marlow, David Waern
 category:             Documentation
 build-type:           Simple
-tested-with:          GHC==9.0.*
+tested-with:          GHC==9.2.*
 
 extra-source-files:
   CHANGES.md
@@ -148,7 +148,7 @@ executable haddock
   else
     -- in order for haddock's advertised version number to have proper meaning,
     -- we pin down to a single haddock-api version.
-    build-depends:  haddock-api == 2.24.0
+    build-depends:  haddock-api == 2.26.0
 
 test-suite html-test
   type:             exitcode-stdio-1.0