From e37f8f89b044f769573752dca7b00416299efc15 Mon Sep 17 00:00:00 2001
From: Marius <maerious@gmail.com>
Date: Fri, 11 Mar 2016 21:50:00 +0100
Subject: [PATCH] Improve README's content

---
 README.md | 57 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 44 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 509a43e..f40e0b2 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,10 @@
 # tusd
 
-[![Build Status](https://travis-ci.org/tus/tusd.svg?branch=master)](https://travis-ci.org/tus/tusd)
-[![Build status](https://ci.appveyor.com/api/projects/status/2y6fa4nyknoxmyc8/branch/master?svg=true)](https://ci.appveyor.com/project/Acconut/tusd/branch/master)
+> **tus** is a protocol based on HTTP for *resumable file uploads*. Resumable
+> means that an upload can be interrupted at any moment and can be resumed without
+> re-uploading the previous data again. An interruption may happen willingly, if
+> the user wants to pause, or by accident in case of an network issue or server
+> outage.
 
 tusd is the official reference implementation of the [tus resumable upload
 protocol](http://www.tus.io/protocols/resumable-upload.html). The protocol
@@ -13,6 +16,14 @@ moment allowing to continue seamlessly after e.g. network interruptions.
 
 ## Getting started
 
+### Download pre-builts binaries (recommended)
+
+You can download ready-to-use packages including binaries for OS X, Linux and
+Windows in various formats of the
+[latest release](https://github.com/tus/tusd/releases/latest).
+
+### Compile from source
+
 **Requirements:**
 
 * [Go](http://golang.org/doc/install) (1.3 or newer)
@@ -35,7 +46,7 @@ go run cmd/tusd/main.go
 ## Using tusd manually
 
 Besides from running tusd using the provided binary, you can embed it into
-your own Golang program:
+your own Go program:
 
 ```go
 package main
@@ -56,20 +67,26 @@ func main() {
 		Path: "./uploads",
 	}
 
-	// Create a new HTTP handler for the tusd server by providing
-	// a configuration object. The DataStore property must be set
-	// in order to allow the handler to function.
+	// A storage backend for tusd may consist of multiple different parts which
+	// handle upload creation, locking, termination and so on. The composer is a
+	// place where all those seperated pieces are joined together. In this example
+	// we only use the file store but you may plug in multiple.
+	composer := tusd.NewStoreComposer()
+	store.UseIn(composer)
+
+	// Create a new HTTP handler for the tusd server by providing a configuration.
+	// The StoreComposer property must be set to allow the handler to function.
 	handler, err := tusd.NewHandler(tusd.Config{
-		BasePath:              "files/",
-		DataStore:             store,
+		BasePath:      "files/",
+		StoreComposer: composer,
 	})
 	if err != nil {
 		panic("Unable to create handler: %s", err)
 	}
 
-	// Right now, nothing has happened since we need to start the
-	// HTTP server on our own. In the end, tusd will listen on
-	// and accept request at http://localhost:8080/files
+	// Right now, nothing has happened since we need to start the HTTP server on
+	// our own. In the end, tusd will start listening on and accept request at
+	// http://localhost:8080/files
 	http.Handle("files/", http.StripPrefix("files/", handler))
 	err = http.ListenAndServe(":8080", nil)
 	if err != nil {
@@ -78,8 +95,8 @@ func main() {
 }
 ```
 
-If you need to customize the GET and DELETE endpoints use
-`tusd.NewUnroutedHandler` instead of `tusd.NewHandler`.
+Please consult the [online documentation](https://godoc.org/github.com/tus/tusd)
+for more details about tusd's APIs and its sub-packages.
 
 ## Implementing own storages
 
@@ -95,8 +112,22 @@ interface and using the new struct in the [configuration object](https://godoc.o
 Please consult the documentation about detailed information about the
 required methods.
 
+## Packages
+
+This repository does not only contain the HTTP server's code but also other
+useful tools:
+
+* [**s3store**](https://godoc.org/github.com/tus/tusd/s3store): A storage backend using AWS S3
+* [**filestore**](https://godoc.org/github.com/tus/tusd/filestore): A storage backend using the local file system
+* [**memorylocker**](https://godoc.org/github.com/tus/tusd/memorylocker): An in-memory locker for handling concurrent uploads
+* [**consullocker**](https://godoc.org/github.com/tus/tusd/consullocker): A locker using the distributed Consul service
+* [**limitedstore**](https://godoc.org/github.com/tus/tusd/limitedstore): A storage wrapper limiting the total used space for uploads
+
 ## Running the testsuite
 
+[![Build Status](https://travis-ci.org/tus/tusd.svg?branch=master)](https://travis-ci.org/tus/tusd)
+[![Build status](https://ci.appveyor.com/api/projects/status/2y6fa4nyknoxmyc8/branch/master?svg=true)](https://ci.appveyor.com/project/Acconut/tusd/branch/master)
+
 ```bash
 go test -v ./...
 ```