minor fixes to readme

README.md

@@ -9,7 +9,7 @@
 go get github.com/alexflint/go-arg
 ```
 
-Declare the command line arguments your program accepts by defining a struct.
+Declare command line arguments for your program by defining a struct.
 
 ```go
 var args struct {
@@ -137,9 +137,6 @@ Options:
   --help, -h               print this help message
 ```
 
-As the example above shows, the `help` tag can be used in conjunction with `arg`, or instead. When used
-together, they can appear in either order.
-
 ### Default values
 
 ```go
@@ -190,14 +187,14 @@ var args struct {
 }
 p := arg.MustParse(&args)
 if args.Foo == "" && args.Bar == "" {
-	p.Fail("you must provide one of --foo and --bar")
+	p.Fail("you must provide either --foo or --bar")
 }
 ```
 
 ```shell
 ./example
 Usage: samples [--foo FOO] [--bar BAR]
-error: you must provide one of --foo and --bar
+error: you must provide either --foo or --bar
 ```
 
 ### Version strings
@@ -252,18 +249,9 @@ As usual, any field tagged with `arg:"-"` is ignored.
 
 ### Custom parsing
 
-You can implement your own argument parser by implementing `encoding.TextUnmarshaler`:
+Implement `encoding.TextUnmarshaler` to define your own parsing logic.
 
 ```go
-package main
-
-import (
-	"fmt"
-	"strings"
-
-	"github.com/alexflint/go-arg"
-)
-
 // Accepts command line arguments of the form "head.tail"
 type NameDotName struct {
 	Head, Tail string
@@ -280,18 +268,47 @@ func (n *NameDotName) UnmarshalText(b []byte) error {
 	return nil
 }
 
-// optional: implement in case you want to display a default value in the usage string
-func (n *NameDotName) MarshalText() (text []byte, err error) {
-	text = []byte(fmt.Sprintf("%s.%s", n.Head, n.Tail))
-	return
+func main() {
+	var args struct {
+		Name NameDotName
+	}
+	arg.MustParse(&args)
+	fmt.Printf("%#v\n", args.Name)
+}
+```
+```shell
+$ ./example --name=foo.bar
+main.NameDotName{Head:"foo", Tail:"bar"}
+
+$ ./example --name=oops
+Usage: example [--name NAME]
+error: error processing --name: missing period in "oops"
+```
+
+### Custom parsing with default values
+
+Implement `encoding.TextMarshaler` to define your own default value strings:
+
+```go
+// Accepts command line arguments of the form "head.tail"
+type NameDotName struct {
+	Head, Tail string
+}
+
+func (n *NameDotName) UnmarshalText(b []byte) error {
+	// same as previous example
+}
+
+// this is only needed if you want to display a default value in the usage string
+func (n *NameDotName) MarshalText() ([]byte, error) {
+	return []byte(fmt.Sprintf("%s.%s", n.Head, n.Tail)), nil
 }
 
 func main() {
 	var args struct {
 		Name NameDotName
 	}
-	// set default
-	args.Name = NameDotName{"file", "txt"}
+	args.Name = NameDotName{"file", "txt"}  // set default value
 	arg.MustParse(&args)
 	fmt.Printf("%#v\n", args.Name)
 }
@@ -306,13 +323,6 @@ Options:
 
 $ ./example
 main.NameDotName{Head:"file", Tail:"txt"}
-
-$ ./example --name=foo.bar
-main.NameDotName{Head:"foo", Tail:"bar"}
-
-$ ./example --name=oops
-Usage: example [--name NAME]
-error: error processing --name: missing period in "oops"
 ```
 
 ### Description strings
@@ -350,12 +360,12 @@ https://godoc.org/github.com/alexflint/go-arg
 
 There are many command line argument parsing libraries for Go, including one in the standard library, so why build another?
 
-The shortcomings of the `flag` library that ships in the standard library are well known. Positional arguments must preceed options, so `./prog x --foo=1` does what you expect but `./prog --foo=1 x` does not. Arguments cannot have both long (`--foo`) and short (`-f`) forms.
+The `flag` library that ships in the standard library I have found awkward to use. For example, positional arguments must preceed options, so `./prog x --foo=1` does what you expect but `./prog --foo=1 x` does not, and it does not allow arguments with both long (`--foo`) and short (`-f`) forms.
 
-Many third-party argument parsing libraries are geared for writing sophisticated command line interfaces. The excellent `codegangsta/cli` is perfect for working with multiple sub-commands and nested flags, but is probably overkill for a simple script with a handful of flags.
+Many third-party argument parsing libraries are great for writing sophisticated command line interfaces, but feel to me like overkill for a simple script with a few flags.
 
-The main idea behind `go-arg` is that Go already has an excellent way to describe data structures using Go structs, so there is no need to develop more levels of abstraction on top of this. Instead of one API to specify which arguments your program accepts, and then another API to get the values of those arguments, why not replace both with a single struct?
+The idea behind `go-arg` is that Go already has an excellent way to describe data structures using structs, so there is no need to develop additional levels of abstraction. Instead of one API to specify which arguments your program accepts, and then another API to get the values of those arguments, `go-arg` replaces both with a single struct.
 
-### Backward Compatibility Notes
+### Backward compatibility notes
 
-The tags have changed recently. Earlier versions required the help text to be part of the `arg` tag. This is still supported but is now deprecated. Instead, you should use a separate `help` tag, described above, which removes most of the limits on the text you can write. In particular, you will need to use the new `help` tag if your help text includes any commas.
+Earlier versions of this library required the help text to be part of the `arg` tag. This is still supported but is now deprecated. Instead, you should use a separate `help` tag, described above, which removes most of the limits on the text you can write. In particular, you will need to use the new `help` tag if your help text includes any commas.