Merge remote-tracking branch 'origin/ghc-head' into ghc-9.4

4 files changed, 78 insertions, 80 deletions

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
 ~~~~~~