From 5bbd647b5a24a35b8c5cbae78dd96b9e3669ecdd Mon Sep 17 00:00:00 2001
From: Philip Potter <philip.g.potter@gmail.com>
Date: Fri, 14 Feb 2020 22:12:49 +0000
Subject: [PATCH] Improve the README

---
 README.md | 132 ++++++++++++++++++++++++++++++------------------------
 1 file changed, 74 insertions(+), 58 deletions(-)

diff --git a/README.md b/README.md
index 66729a2..577fe77 100644
--- a/README.md
+++ b/README.md
@@ -1,67 +1,83 @@
 # dhall-golang
 
-Go bindings for dhall.
+[![GoDoc](https://godoc.org/github.com/philandstuff/dhall-golang?status.svg)][dhall-golang godoc]
+
+Go bindings for the [dhall configuration language][dhall].
+
+[dhall]: https://dhall-lang.org/
+
+## Quick start
+
+Here's a minimal example of how you might use dhall-golang to load a
+Dhall file into your own struct:
+
+```golang
+package main
+
+import (
+	"fmt"
+	"io/ioutil"
+
+	"github.com/philandstuff/dhall-golang"
+)
+
+// Config can be a fairly arbitrary Go datatype.  You would put your
+// application configuration in this struct.
+type Config struct {
+	Port int
+	Name string
+}
+
+func main() {
+	var config Config
+	bytes, err := ioutil.ReadFile("/path/to/config.dhall")
+	if err != nil {
+		panic(err)
+	}
+	err = dhall.Unmarshal(bytes, &config)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("Loaded config: %#v\n", config)
+}
+```
+
+## Documentation
+
+You can find more documentation in the [dhall-golang godoc][].
+
+[dhall-golang godoc]: https://godoc.org/github.com/philandstuff/dhall-golang
 
 ## Development
 
+This is a fairly standard Go project.  It uses go modules, so no
+vendoring of dependencies is required.
+
 ### Running the tests
 
     go test ./...
 
-## Progress
-
- - [X] Type, Kind, Sort
- - [X] Variables
-   - [X] de bruijn indices
-   - [x] quoted variables
- - [X] Lambdas, Pis, function application
-   - [x] Alpha normalization
- - [X] Let bindings
- - [X] Type annotations
- - [X] Bools
-   - [X] if
-   - [x] `&&`, `||`
-   - [x] `==`, `!=`
- - [X] Naturals
-   - [X] `l + r` Natural addition
-   - [x] `l * r` Natural multiplication
-   - [x] Natural/* standard functions
- - [X] Integers
-   - [x] Integer/toDouble and Integer/show
- - [X] Doubles
-   - [x] Double/show (it exists but doesn't pass tests)
- - [X] Lists
-   - [x] `l # r` list append
-   - [x] List/* functions
- - [x] Text
-   - [x] double quote literals
-   - [x] single quote literals
-   - [x] text interpolation
-   - [x] `l ++ r` text append
-   - [x] Text/show standard functions
- - [x] Optionals
-   - [x] Optional/fold and Optional/build
- - [x] Records
-   - [x] `f.a`
-   - [x] `f.{ xs… }`
-   - [x] `f.(s)`
-   - [x] `l ∧ r`
-   - [x] `l ⫽ r`
-   - [x] `l ⩓ r`
- - [x] Unions
-   - [x] types
-   - [x] constructors
-   - [x] `merge`
- - [ ] Imports
-   - [x] local imports (except home-rooted paths)
-   - [x] remote imports
-   - [x] environment variable imports
-   - [ ] `using ./headers`
-   - [x] import caching
-   - [x] importing expressions
-   - [x] importing `as Text`
-   - [x] `x ? y` alternate import operator
-   - [x] `missing`
- - [X] unmarshalling into Go types
- - [ ] better errors
- - [ ] better godoc
+    go test -short ./... # skips long-running tests
+
+### Making changes to the PEG grammar
+
+Dhall-golang uses [pigeon][] to generate the parser source file
+`parser/internal/dhall.go` from the PEG grammar at
+`parser/internal/dhall.peg`.  If you change the PEG grammar, you need
+to first install the pigeon binary if you don't already have it:
+
+    # either outside a module directory, or with GO111MODULE=off
+    go get github.com/mna/pigeon
+
+Then, to regenerate the parser:
+
+    go generate ./parser
+
+[pigeon]: https://godoc.org/github.com/mna/pigeon
+
+## Support
+
+Issues and pull requests are welcome on this repository.  If you have
+a question, you can ask it on the [Dhall discourse][].
+
+[Dhall discourse]: https://discourse.dhall-lang.org/