diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c2aa9f3ced793d6f30e71211f94c9dbd20a3d257..dafcdc74d83063f7216f31859ce0e1f012469d7e 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 69763a5220d30610a5b8cf0c99441b2f7d5f0a75..530e752d525b5ed0eb3d7acf7f828fdbca03e934 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 0000000000000000000000000000000000000000..9afa4ea720b65dd9b2fafa59ad60b2ed3ca46040
--- /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 0d1b8b480b74aa779c6b01c280b5badd03955dc8..f370e42fd54e6b8b42a9eacd34ee8776165ce99a 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 fc1269f983cd9e485a938e13055bee421c2bc0fb..1f4234cbe7b7c1f565fd4ef7e12980d3008b9469 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 c0b08a4067ebcb4be0c27b6668cf6ba00968c97d..abfeb52ad586dbcb9d3eef6b95f0cdee6e3183c7 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 cd02bf255117ddb9bbfc4679f221c5d6ac142cc4..9770061c4995867df9a1d311c08efbc545e929e4 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 68e03fd5faa5bcff56447c12bf7e7209d3e7826e..89828e3017727ece412894ccebbde8c00548cc54 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 72c11f7564fc1fcb791569de34a8e2c2c3fcc712..f6d88c815c22cfa28fa5077556c11a1c6f031b79 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 e482958822238538fb68a26015915ba90ba50565..2905dc8f059792c4f411305b710fd227c2aa9335 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 dfb4e9a9c8f54be1f5bbe989946cfedc8bba07e5..0686289e6f1d9cb1c075152956b414ef19017829 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