Merge branch 'wip/ghc-head-merge' into ghc-head

1 files changed, 52 insertions, 57 deletions

diff --git a/README.md b/README.md
index 978dea3e..e9ff09ca 100644
--- a/README.md
+++ b/README.md
@@ -1,68 +1,63 @@
-# Haddock, a Haskell Documentation Tool [![Build Status](https://travis-ci.org/haskell/haddock.svg?branch=ghc-head)](https://travis-ci.org/haskell/haddock)
-
-
-## About haddock
-
-See [Description on Hackage](https://hackage.haskell.org/package/haddock).
-
-## Source code documentation
-
-Full documentation can be found in the `doc/` subdirectory, in
-[reStructedText format](http://www.sphinx-doc.org/en/stable/rest.html)
-format.
+# Haddock [![CI][CI badge]][CI page] [![Hackage][Hackage badge]][Hackage page]
 
+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.
 
 ## Project overview
 
 This project consists of three packages:
 
-* haddock
-* haddock-api
-* haddock-library
-
-### haddock
-
-The haddock package provides the `haddock` executable. It is implemented as a
-tiny wrapper around haddock-api's `Documentation.Haddock.haddock` function.
+ * `haddock`: provides the `haddock` executable. It is implemented as a tiny
+    wrapper around `haddock-api`'s `Documentation.Haddock.haddock` function.
 
-### haddock-api
-
-haddock-api contains the program logic of the `haddock` tool. [The haddocks for
-the `Documentation.Haddock` module](http://hackage.haskell.org/package/haddock-api-2.19.0.1/docs/Documentation-Haddock.html)
-offer a good overview of haddock-api's functionality.
-
-### haddock-library
-
-haddock-library is concerned with the parsing and processing of the Haddock
-markup language.
+ * `haddock-api`: contains the program logic of the `haddock` tool.
+   [The haddocks for the `Documentation.Haddock` module][Documentation.Haddock]
+   offer a good overview of the functionality.
 
+ * `haddock-library`: is concerned with the parsing and processing of the
+   Haddock markup language. Unlike the other packages, it is expected to build
+   on a fairly wide range of GHC versions.
 
 ## Contributing
 
-Please create issues when you have any problems and pull requests if you have some code.
+Please create issues when you have any problems and pull requests if you have
+some code.
 
 ## Hacking
 
-To get started you'll need a latest GHC release installed.
+To get started you'll need the latest GHC release installed.
 
 Clone the repository:
 
 ```bash
-  git clone https://github.com/haskell/haddock.git
-  cd haddock
+git clone https://github.com/haskell/haddock.git
+cd haddock
 ```
 
 and then proceed using your favourite build tool.
 
-#### Using [`cabal new-build`](http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html)
+Note: before building `haddock`, you need to build the subprojects
+`haddock-library` and `haddock-api`, in this order!
+The `cabal v2-build` takes care of this automatically.
+
+#### Using [`cabal v2-build`][cabal v2]
 
 ```bash
-cabal new-build -w ghc-head
-# build & run the test suite
-cabal new-test -w ghc-head all
+cabal v2-build -w ghc-8.10.1
+cabal v2-test -w ghc-8.10.1 all
 ```
 
-#### Using Cabal sandboxes
+#### Using `stack`
+
+```bash
+stack init
+stack build
+export HADDOCK_PATH="$(stack exec which haddock)"
+stack test
+```
+
+#### Using Cabal sandboxes (deprecated)
 
 ```bash
 cabal sandbox init
@@ -78,29 +73,29 @@ export HADDOCK_PATH="dist/build/haddock/haddock"
 cabal test
 ```
 
-#### Using Stack
-
-```bash
-stack init
-stack install
-# run the test suite
-export HADDOCK_PATH="$HOME/.local/bin/haddock"
-stack test
-```
-
 ### Git Branches
 
-If you're a GHC developer and want to update Haddock to work with your
-changes, you should be working on `ghc-head` branch.
-See instructions at
-https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git/Submodules
+If you're a GHC developer and want to update Haddock to work with your changes,
+you should be working on the `ghc-head` branch. See instructions at
+<https://gitlab.haskell.org/ghc/ghc/-/wikis/working-conventions/git/submodules>
 for an example workflow.
 
-### Updating `html-test`
+### Updating golden testsuite outputs
 
-When accepting any changes in the output of `html-test`, it is important
-to use the `--haddock-path` option. For example:
+If you've changed Haddock's output, you will probably need to accept the new
+output of Haddock's golden test suites (`html-test`, `latex-test`,
+`hoogle-test`, and `hypsrc-test`). This can be done by passing the `--accept`
+argument to these test suites. With a new enough version of `cabal-install`:
 
 ```
-cabal new-run -- html-test --haddock-path $(find dist-newstyle/ -executable -type f -name haddock) --accept
+cabal v2-test html-test latex-test hoogle-test hypsrc-test \
+  --test-option='--accept'
 ```
+
+[CI page]: https://travis-ci.org/haskell/haddock
+[CI badge]: https://travis-ci.org/haskell/haddock.svg?branch=ghc-8.10
+[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
+[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