aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorHerbert Valerio Riedel <hvr@gnu.org>2017-07-20 12:32:16 +0200
committerHerbert Valerio Riedel <hvr@gnu.org>2017-07-20 12:32:16 +0200
commitcc1577ae29763dfeb9483b5c7dcc723bb3a014f0 (patch)
treee42d7e4d51ee7239c4555411e088a328915ee2c0
parent53598f89117d3a860eaf11ec44f93acf708b93c1 (diff)
Update README
Also improves markup and removes/fixes redundant/obsolete parts [skip ci]
-rw-r--r--README.md58
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.