Make custom formatters easier to use

Add MarshalWithFormatter, MarshalIndentWithFormatter and
NewEncoderWithFormatter functions which make it easier to generate
colorized output using a custom Formatter.  See the docs above these
functions for caveats.

Also, performed an all-around cleanup to improve package
documentation.

README.md

@@ -4,8 +4,9 @@ jsoncolor
 [![GoDoc](https://godoc.org/github.com/nwidger/jsoncolor?status.svg)](https://godoc.org/github.com/nwidger/jsoncolor)
 
 `jsoncolor` is a drop-in replacement for `encoding/json`'s `Marshal`
-and `MarshalIndent` functions which produce colorized output using
-fatih's [color](https://github.com/fatih/color) package.
+and `MarshalIndent` functions and `Encoder` type which produce
+colorized output using fatih's [color](https://github.com/fatih/color)
+package.
 
 ## Installation
 
@@ -19,58 +20,48 @@ To use as a replacement for `encoding/json`, exchange
 
 `import "encoding/json"` with `import json "github.com/nwidger/jsoncolor"`.
 
-`json.Marshal` and `json.MarshalIndent` will now produce colorized
-output.
+`json.Marshal`, `json.MarshalIndent` and `json.NewEncoder` will now
+produce colorized output.
 
 ## Custom Colors
 
 The colors used for each type of token can be customized by creating a
-custom `Formatter` and changing its `XXXColor` fields.  See
+custom `Formatter`, changing its `XXXColor` fields and then passing it
+to `MarshalWithFormatter`, `MarshalIndentWithFormatter` or
+`NewEncoderWithFormatter`.  If a `XXXColor` field of the custom
+`Formatter` is not set, the corresponding `DefaultXXXColor` package
+variable is used.  See
 [color.New](https://godoc.org/github.com/fatih/color#New) for creating
 custom color values and the
 [GoDocs](https://godoc.org/github.com/nwidger/jsoncolor#pkg-variables)
 for the default colors.
 
 ``` go
 import (
-        "bytes"
-		"encoding/json"
-		"fmt"
-		"log"
+        "fmt"
+        "log"
 
         "github.com/fatih/color"
-        "github.com/nwidger/jsoncolor"
+        json "github.com/nwidger/jsoncolor"
 )
 
-// marshal v into src using encoding/json
-src, err := json.Marshal(v)
-if err != nil {
-        log.Fatal(err)
-}
-
-// create custom formatter,
-f := jsoncolor.NewFormatter()
+// create custom formatter
+f := json.NewFormatter()
 
 // set custom colors
-f.SpaceColor = color.New(color.FgRed, color.Bold)
-f.CommaColor = color.New(color.FgWhite, color.Bold)
-f.ColonColor = color.New(color.FgBlue)
-f.ObjectColor = color.New(color.FgBlue, color.Bold)
-f.ArrayColor = color.New(color.FgWhite)
-f.FieldColor = color.New(color.FgGreen)
 f.StringColor = color.New(color.FgBlack, color.Bold)
 f.TrueColor = color.New(color.FgWhite, color.Bold)
 f.FalseColor = color.New(color.FgRed)
 f.NumberColor = color.New(color.FgWhite)
 f.NullColor = color.New(color.FgWhite, color.Bold)
 
-// colorized output is written to dst
-dst := &bytes.Buffer{}
-err := f.Format(dst, src)
+// marshal v with custom formatter,
+// dst contains colorized output
+dst, err := json.MarshalWithFormatter(v, f)
 if err != nil {
         log.Fatal(err)
 }
 
 // print colorized output to stdout
-fmt.Println(dst.String())
+fmt.Println(string(dst))
 ```