Update README

Also improves markup and removes/fixes redundant/obsolete parts

[skip ci]

1 files changed, 16 insertions, 42 deletions

diff --git a/README.md b/README.md
index a21b29e9..3e356ecc 100644
--- a/README.md
+++ b/README.md
@@ -1,52 +1,21 @@
 # Haddock, a Haskell Documentation Tool [![Build Status](https://travis-ci.org/haskell/haddock.svg?branch=master)](https://travis-ci.org/haskell/haddock)
 
 
-#### About haddock
+## About haddock
 
-This is Haddock, a tool for automatically generating documentation
-from annotated Haskell source code.  It is primary intended for
-documenting library interfaces, but it should be useful for any kind
-of Haskell code.
+See [Description on Hackage](https://hackage.haskell.org/package/haddock).
 
-Haddock lets you write documentation annotations next to the
-definitions of functions and types in the source code, in a syntax
-that is easy on the eye when writing the source code (no heavyweight
-mark-up). The documentation generated by Haddock is fully hyperlinked
-- click on a type name in a type signature to go straight to the
-definition, and documentation, for that type.
+## Source code documentation
 
-Haddock understands Haskell's module system, so you can structure your
-code however you like without worrying that internal structure will be
-exposed in the generated documentation.  For example, it is common to
-implement a library in several modules, but define the external API by
-having a single module which re-exports parts of these implementation
-modules.  Using Haddock, you can still write documentation annotations
-next to the actual definitions of the functions and types in the
-library, but the documentation annotations from the implementation
-will be propagated to the external API when the documentation is
-generated.  Abstract types and classes are handled correctly.  In
-fact, even without any documentation annotations, Haddock can generate
-useful documentation from your source code.
-
-
-#### Documentation formats
-
-Haddock can generate documentation in multiple formats; currently HTML
-is implemented, and there is partial support for generating LaTeX and
-Hoogle.
-
-
-#### Source code documentation
-
-Full documentation can be found in the doc/ subdirectory, in DocBook
+Full documentation can be found in the `doc/` subdirectory, in
+[reStructedText format](http://www.sphinx-doc.org/en/stable/rest.html)
 format.
 
-
-#### Contributing
+## Contributing
 
 Please create issues when you have any problems and pull requests if you have some code.
 
-##### Hacking
+## Hacking
 
 To get started you'll need a latest GHC release installed.
 
@@ -59,7 +28,7 @@ Clone the repository:
 
 and then proceed using your favourite build tool.
 
-###### Using [`cabal new-build`](http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html)
+#### Using [`cabal new-build`](http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html)
 
 ```bash
 cabal new-build -w ghc-8.2.1
@@ -67,7 +36,7 @@ cabal new-build -w ghc-8.2.1
 cabal new-test -w ghc-8.2.1
 ```
 
-###### Using Cabal sandboxes
+#### Using Cabal sandboxes
 
 ```bash
 cabal sandbox init
@@ -83,7 +52,7 @@ export HADDOCK_PATH="dist/build/haddock/haddock"
 cabal test
 ```
 
-###### Using Stack
+#### Using Stack
 
 ```bash
 stack init
@@ -93,9 +62,14 @@ 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 instead of master.
+changes, you should be working on `ghc-head` branch instead of `master`.
 See instructions at
 https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git/Submodules
 for an example workflow.
+
+The `master` branch usually requires a GHC from the latest GHC stable
+branch. The required GHC version can be inferred from the version
+bounds on `ghc` in the respective `.cabal` files.