@@ 0,0 1,53 @@
+# litmus
+
+litmus serves Go import meta tags like described at
+the [Go Wiki](https://golang.org/cmd/go/#hdr-Remote_import_paths).
+
+## usage
+
+create a file containing the package definitions as JSON, `packages.json` being the default filename
+(an example for this file can also be written to stdout using `-packagesExample`):
+
+	cat << EOF > packages.json
+	[
+		{
+			"name":"litmus",
+			"vcs":"git",
+			"path":"https://git.sr.ht/~rbn/litmus",
+			"website":"https://git.sr.ht/~rbn/litmus"
+		},
+		{
+			"name":"neinp",
+			"vcs":"git",
+			"path":"https://git.sr.ht/~rbn/neinp",
+			"website":"https://git.sr.ht/~rbn/neinp"
+		},
+		{
+			"name":"rssfs",
+			"vcs":"git",
+			"path":"https://git.sr.ht/~rbn/rssfs",
+			"website":"https://git.sr.ht/~rbn/rssfs"
+		},
+		{
+			"name":"fit",
+			"vcs":"git",
+			"path":"https://git.sr.ht/~rbn/fit",
+			"website":"https://git.sr.ht/~rbn/fit"
+		}
+	]
+	EOF
+
+and run litmus:
+
+	litmus
+
+it should now serve at `localhost:1337`. either run it using another `-addr` or reverse proxy it.
+if a reverse proxy is used, you should either give the `-prefix` parameter containing the FQDN where
+litmus is reached, or the reverse proxy should hand down the right value in the `Host` HTTP-header.
+
+with the packages defined as above, the litmus package would have the import path
+`go.rbn.im/litmus`.
+
+## bugs & patches
+
+bugs and patches can be submitted to [code ate rbn.im](mailto:code ate rbn.im).<
\ No newline at end of file

@@ 1,13 1,14 @@
+/*Command litmus serves Go import meta tags */
 package main
 
 import (
 	"encoding/json"
 	"flag"
 	"go.rbn.im/litmus"
+	"io"
 	"log"
 	"net/http"
 	"os"
-	"io"
 )
 
 var examplePkgs = []litmus.Pkg{{


@@ 32,7 33,7 @@ func main() {
 	addr := flag.String("addr", "127.0.0.1:1337", "listen address")
 	packagesPath := flag.String("packages", "packages.json", "packages definition")
 	example := flag.Bool("packagesExample", false, "print packages definition example")
-	prefix := flag.String("prefix", "", `prefix prepended to request path, returned as 'import-prefix' field in the meta tag.
+	prefix := flag.String("prefix", "", `prefix to use in 'import-prefix' field in the meta tag.
 	this is useful if litmus is used behind a reverse-proxy and can't figure out the host from the request.`)
 	flag.Parse()
 

@@ 81,5 81,3 @@ func TestLoadPackages(t *testing.T) {
 		}
 	}
 }
-
-

@@ 1,3 1,4 @@
+/*Package litmus contains a http.Handler to serve go import metatags*/
 package litmus
 
 import (


@@ 8,11 9,12 @@ import (
 	"strings"
 )
 
+// Pkg is a package definition containing pointers to the VCS and the website.
 type Pkg struct {
-	Name    string `json:"name"`
-	Vcs     string `json:"vcs"`
-	Path    string `json:"path"`
-	Website string `json:"website"`
+	Name    string `json:"name"`    // package name, this is the path served
+	Vcs     string `json:"vcs"`     // vcs type, one of "bzr", "fossil", "git", "hg", "svn"
+	Path    string `json:"path"`    // path to the repository, eg. https://git.sr.ht/~rbn/litmus
+	Website string `json:"website"` // url to redirect to if go-get url parameter isn't set
 }
 
 func mapping(pkgs []Pkg, name string) (Pkg, bool) {


@@ 30,15 32,22 @@ func mapping(pkgs []Pkg, name string) (Pkg, bool) {
 	return Pkg{}, false
 }
 
+// Handler serves the information for packages
 type Handler struct {
 	pkgs     []Pkg
 	hostName string
 }
 
+// NewHandler creates a new Handler
+//
+// pkgs is the list of packages to serve.
+// While the handler tries to get the host name from the requests,
+// it can be overridden using the hostName parameter.
 func NewHandler(pkgs []Pkg, hostName string) *Handler {
 	return &Handler{pkgs: pkgs, hostName: hostName}
 }
 
+// host selects either the set host name if not empty or the host name from the request.
 func (l *Handler) host(r *http.Request) string {
 	switch {
 	case l.hostName != "":


@@ 48,6 57,7 @@ func (l *Handler) host(r *http.Request) string {
 	}
 }
 
+// ServeHTTP implements interface http.Handler
 func (l *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	log.Printf("%p new request", r)
 	name := r.URL.Path


@@ 117,5 127,3 @@ func (l *Handler) serveWebsite(w http.ResponseWriter, r *http.Request, p Pkg) {
 	log.Printf("%p serving web redirect for %v", r, p.Name)
 	http.Redirect(w, r, p.Website, http.StatusSeeOther)
 }
-
-