all: update the docs a bit

Rework the features section in the README, leaving optional features at
the end of the list. Simplify the caveats list, too; the build cache and
exported field/method bits only need one point each. Overall, the
section was far too wordy for little reason.

Also redo the help text a bit. There's now a line to briefly introduce
the tool, as well as a link to the README with all the details. Finally,
the flags have shorter and more consistent help strings.

While at it, remove two unused global vars as spotted by staticcheck.

README.md

@@ -2,8 +2,8 @@
 
 	GO111MODULE=on go get mvdan.cc/garble
 
-Obfuscate a Go build. Requires Go 1.15 or later, since Go 1.14 uses an entirely
-different object format.
+Obfuscate Go code by wrapping the Go toolchain. Requires Go 1.15 or later, since
+Go 1.14 uses an entirely different object format.
 
 	garble build [build flags] [packages]
 
@@ -29,10 +29,10 @@ order to:
 * Replace package paths with short base64 hashes
 * Remove all [build](https://golang.org/pkg/runtime/#Version) and [module](https://golang.org/pkg/runtime/debug/#ReadBuildInfo) information
 * Strip filenames and shuffle position information
-* Obfuscate literals, if the `-literals` flag is given
 * Strip debugging information and symbol tables
-* Expose additional functions in the runtime that can optionally hide
-  information during execution
+* Obfuscate literals, if the `-literals` flag is given
+* Expose [additional functions](#runtime-api) in the runtime package that can
+  optionally hide information during execution
 
 ### Options
 
@@ -45,26 +45,16 @@ packages to garble, set `GOPRIVATE`, documented at `go help module-private`.
 Most of these can improve with time and effort. The purpose of this section is
 to document the current shortcomings of this tool.
 
-* The `-a` flag for `go build` is required, since `-toolexec` doesn't work well
-  with the build cache; see [golang/go#27628](https://github.com/golang/go/issues/27628).
-
-* Since no caching at all can take place right now (see the link above), fast
-  incremental builds aren't possible. Large projects might be slow to build.
-
-* Deciding what method names to garble is always going to be difficult, due to
-  interfaces that could be implemented up or down the package import tree. At
-  the moment, exported methods are never garbled.
+* Build caching is not supported, so large projects will likely be slow to
+  build. See [golang/go#41145](https://github.com/golang/go/issues/41145).
 
-* Similarly to methods, exported struct fields are difficult to garble, as the
-  names might be relevant for reflection work like `encoding/json`. At the
-  moment, exported methods are never garbled.
+* Exported methods and fields are never garbled at the moment, since they could
+  be required by interfaces and reflection. This area is a work in progress.
 
 * Functions implemented outside Go, such as assembly, aren't garbled since we
   currently only transform the input Go source.
 
-* ~~Since `garble` forces `-trimpath`, plugins built with `-garble` must be loaded
-  from Go programs built with `-trimpath` too.~~ Plugins currently do not always
-  work with well with `garble`; see [#87](https://github.com/mvdan/garble/issues/87).
+* Go plugins are not currently supported; see [#87](https://github.com/mvdan/garble/issues/87).
 
 ### Runtime API
 

import_obfuscation.go

@@ -538,7 +538,7 @@ func garbleSymData(data []byte, privImports privateImports, garbledImports map[s
 	return buf.Bytes()
 }
 
-//createImportPathData creates reflection data for an
+// createImportPathData creates reflection data for an
 // import path
 func createImportPathData(importPath string) []byte {
 	l := 3 + len(importPath)

internal/literals/literals.go

@@ -12,11 +12,7 @@ import (
 	ah "mvdan.cc/garble/internal/asthelper"
 )
 
-var (
-	usesUnsafe     bool
-	universalTrue  = types.Universe.Lookup("true")
-	universalFalse = types.Universe.Lookup("false")
-)
+var usesUnsafe bool
 
 func randObfuscator() obfuscator {
 	randPos := mathrand.Intn(len(obfuscators))

main.go

@@ -46,27 +46,30 @@ var (
 
 func init() {
 	flagSet.Usage = usage
-	flagSet.BoolVar(&flagGarbleLiterals, "literals", false, "Encrypt all literals with AES, currently only literal strings are supported")
+	flagSet.BoolVar(&flagGarbleLiterals, "literals", false, "Obfuscate literals such as strings")
 	flagSet.BoolVar(&flagGarbleTiny, "tiny", false, "Optimize for binary size, losing the ability to reverse the process")
-	flagSet.StringVar(&flagDebugDir, "debugdir", "", "Write the garbled source to a given directory: '-debugdir=./debug'")
-	flagSet.StringVar(&flagSeed, "seed", "", "Provide a custom base64-encoded seed: '-seed=o9WDTZ4CN4w=' \nFor a random seed provide: '-seed=random'")
+	flagSet.StringVar(&flagDebugDir, "debugdir", "", "Write the garbled source to a directory, e.g. -debugdir=out")
+	flagSet.StringVar(&flagSeed, "seed", "", "Provide a base64-encoded seed, e.g. -seed=o9WDTZ4CN4w=\nFor a random seed, provide -seed=random")
 }
 
 func usage() {
 	fmt.Fprintf(os.Stderr, `
-Usage of garble:
+Garble obfuscates Go code by wrapping the Go toolchain.
 
-garble [flags] build [build flags] [packages]
+Usage:
 
-The tool supports wrapping the following Go commands - run "garble cmd [args]"
-instead of "go cmd [args]" to add obfuscation:
+	garble [flags] build [build flags] [packages]
 
-	build
-	test
+Aside from "build", the "test" command mirroring "go test" is also supported.
 
 garble accepts the following flags:
+
 `[1:])
 	flagSet.PrintDefaults()
+	fmt.Fprintf(os.Stderr, `
+
+For more information, see https://github.com/mvdan/garble.
+`[1:])
 	os.Exit(2)
 }
 

testdata/scripts/help.txt

@@ -1,24 +1,24 @@
 ! garble
-stderr -count=1 'Usage of garble'
-stderr 'garble cmd'
+stderr -count=1 'Usage'
+stderr 'garble \[flags\] build'
 ! stderr 'usage: go build'
 ! stdout .
 
 ! garble -h
-stderr 'Usage of garble'
+stderr 'garble \[flags\] build'
 ! stdout .
 
 ! garble help
-stderr 'Usage of garble'
+stderr 'garble \[flags\] build'
 ! stdout .
 
 ! garble build -h
-stderr 'Usage of garble'
+stderr 'garble \[flags\] build'
 ! stderr 'usage: go build'
 ! stdout .
 
 ! garble -badflag
-stderr 'Usage of garble'
+stderr 'garble \[flags\] build'
 ! stdout .
 
 ! garble badcmd