From 97dd3289b010bfa9501fcbef5475a14a626eb92f Mon Sep 17 00:00:00 2001
From: Matthew Holt <mholt@users.noreply.github.com>
Date: Tue, 7 Apr 2020 18:56:30 -0600
Subject: [PATCH] Improve docs

---
 README.md          | 132 ++++++++++++++++++++++++---------------------
 cmd/xcaddy/main.go |   2 +-
 2 files changed, 72 insertions(+), 62 deletions(-)

diff --git a/README.md b/README.md
index 60c417f..40115de 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,15 @@
-Custom Caddy Builder
-====================
+`xcaddy` - Custom Caddy Builder
+===============================
 
-This package and associated CLI tool make it easy to perform custom builds of the [Caddy Web Server](https://github.com/caddyserver/caddy).
+This command line tool and associated Go package makes it easy to make custom builds of the [Caddy Web Server](https://github.com/caddyserver/caddy).
+
+It is used heavily by Caddy plugin developers as well as anyone who wishes to make custom `caddy` binaries (with or without plugins).
 
 Supports Caddy 2 and up.
 
-⚠️ Still in early development. Works; but no guarantees and prone to changes at this point. Stay updated and please submit feedback!
+⚠️ Still in development.
+
+Stay updated, be aware of changes, and please submit feedback! Thanks!
 
 ## Requirements
 
@@ -13,6 +17,67 @@ Supports Caddy 2 and up.
 - Go modules enabled
 
 
+## Command usage
+
+The `xcaddy` command has two primary uses:
+
+- Compile custom `caddy` binaries
+- A replacement for `go run` while developing Caddy plugins
+
+Install the `xcaddy` command with:
+
+```bash
+$ go get -u github.com/caddyserver/xcaddy/cmd/xcaddy
+```
+
+
+### Custom builds
+
+Syntax:
+
+```
+$ xcaddy build <caddy_version>
+    [--output <file>]
+    [--with <module[@version]>...]
+```
+
+- `<caddy_version>` is the core Caddy version to build (required, for now).
+- `--output` changes the output file.
+- `--with` can be used multiple times to add plugins by specifying the Go module name and optionally its version, similar to `go get`.
+
+For example:
+
+```bash
+$ xcaddy build v2.0.0-rc.1 \
+    --with github.com/caddyserver/ntlm-transport@v0.1.0
+```
+
+### For plugin development
+
+If you run `xcaddy` from within the folder of the Caddy plugin you're working on without the `build` subcommand described above, it will build Caddy with your current module and run it, as if you manually plugged it in and ran `go run`.
+
+The binary will be built and run from the current directory, then cleaned up.
+
+The current working directory must be inside an initialized Go module.
+
+Syntax:
+
+```
+$ xcaddy <args...>
+```
+- `<args...>` are passed through to the `caddy` command.
+
+For example:
+
+```bash
+$ xcaddy list-modules
+$ xcaddy run
+$ xcaddy run --config caddy.json
+```
+
+
+
+
 ## Library usage
 
 ```go
@@ -20,8 +85,8 @@ builder := xcaddy.Builder{
 	CaddyVersion: "v2.0.0-rc.1",
 	Plugins: []xcaddy.Dependency{
 		{
-			ModulePath: "github.com/caddyserver/nginx-adapter",
-			Version:    "bdbb6db7ff9ad6ceb0dcd93f89e396f6365aa5d4",
+			ModulePath: "github.com/caddyserver/ntlm-transport",
+			Version:    "v0.1.0",
 		},
 	},
 }
@@ -31,61 +96,6 @@ err := builder.Build("./caddy")
 Versions can be anything compatible with `go get`.
 
 
-## CLI usage
-
-The CLI can be used both to make custom builds of Caddy, but also as a replacement for `go run` while developing Caddy plugins.
-
-### Download
-
-```
-go get -u github.com/caddyserver/xcaddy/cmd/xcaddy
-```
-
-### For custom builds
-
-Syntax:
-
-```
-xcaddy build <version>
-	[--output <file>]
-	[--with <module[@version]>...]
-```
-
-Where:
-
-- `--version` is the core Caddy version to build (required, for now).
-- `--output` changes the output file.
-- `--with` can be used multiple times to add plugins by specifying the module name and optionally its version, in a way similar to `go get`.
-
-For example:
-
-```bash
-$ xcaddy build v2.0.0-rc.1 \
-	--with github.com/caddyserver/nginx-adapter@bdbb6db7ff9ad6ceb0dcd93f89e396f6365aa5d4
-```
-
-### For plugin development
-
-If you run `xcaddy` from within the folder of the Caddy plugin you're working on without the `build` subcommand, it will build Caddy with your current module and run it, similar to if you manually plugged it in and ran `go run`.
-
-The binary will be built, run from the current directory, then cleaned up.
-
-Syntax:
-
-```
-xcaddy <args...>
-```
-
-Where:
-
-- `<args...>` are passed through to the `caddy` command.
-
-For example:
-
-```bash
-$ xcaddy list-modules
-$ xcaddy run --config caddy.json
-```
 
 
 ---
diff --git a/cmd/xcaddy/main.go b/cmd/xcaddy/main.go
index 442425d..096e522 100644
--- a/cmd/xcaddy/main.go
+++ b/cmd/xcaddy/main.go
@@ -126,7 +126,7 @@ func runDev(caddyVersion string, args []string) error {
 	}
 	currentModule := strings.TrimSpace(string(out))
 
-	// get its root directory
+	// get the root directory of the main module
 	cmd = exec.Command("go", "list", "-m", "-f={{.Dir}}")
 	out, err = cmd.Output()
 	if err != nil {