aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md41
1 files changed, 36 insertions, 5 deletions
diff --git a/README.md b/README.md
index bfc2261b..51642aab 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,32 @@ Full documentation can be found in the `doc/` subdirectory, in
[reStructedText format](http://www.sphinx-doc.org/en/stable/rest.html)
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-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.
+
+
## Contributing
Please create issues when you have any problems and pull requests if you have some code.
@@ -33,7 +59,7 @@ and then proceed using your favourite build tool.
```bash
cabal new-build -w ghc-8.4.1
# build & run the test suite
-cabal new-test -w ghc-8.4.1
+cabal new-test -w ghc-8.4.1 all
```
#### Using Cabal sandboxes
@@ -65,11 +91,16 @@ 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.
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.
+### Updating `html-test`
+
+When accepting any changes in the output of `html-test`, it is important
+to use the `--haddock-path` option. For example:
+
+```
+cabal new-run -- html-test --haddock-path $(find dist-newstyle/ -executable -type f -name haddock) --accept
+```