Update README.md.

Author: natestedman

README.md

@@ -3,10 +3,7 @@
 [![Build Status](https://travis-ci.org/natestedman/Attributed.svg?branch=master)](https://travis-ci.org/natestedman/Attributed)
 [![License](https://img.shields.io/badge/license-Creative%20Commons%20Zero%20v1.0%20Universal-blue.svg)](https://creativecommons.org/publicdomain/zero/1.0/)
 
-A Swift DSL for `NSAttributedString`.
-
-## Usage
-Attributed strings are composed through function calls on extensions of attribute value types, where the parameter is a list of attributed string values to apply the attributes to. The return values of these function calls can be included within lists passed to other function calls, creating a nested structure.
+A small, flexible framework for expressing `NSAttributedString` values structurally.
 
 ```swift
 label.attributedText = [
@@ -27,25 +24,34 @@ label.attributedText = [
 ].join().attributedString
 ```
 
-The `join` extension of `SequenceType` can be used to combine attributed strings without applying any additional attributes.
+## Usage
 
-Any value that conforms to the `AttributedStringConvertible` protocol can be passed as an argument. Implementations for `NSAttributedString` and `String` are included, so it shouldn't be necessary to implement this type. All attribute functions return a value of this protocol type. It can be unwrapped into a `NSAttributedString` with the `attributedString` property.
+### Attributed String Convertibles
+Attributed defines the `AttributedStringConvertible` protocol, which allows clients to create an `NSAttributedString` value with the `attributedString` property. `String` and `NSAttributedString` are extended to conform to this protocol.
 
-### Scoping
-Outer attributed values *do not* override inner values, so this code works as expected:
+### Attribute Functions
+The most important values in Attributed are _attribute functions_, which take an `AttributedStringConvertible` value as a parameter, and return a second `AttributedStringConvertible` value, with additional attributes applied. A basic attribute function can be created with the `attribute(_:withValue:)` function:
 
 ```swift
-UIColor.greenColor().foregroundAttribute([
-    "There is some ",
-    UIColor.blueColor().foregroundAttribute(
-        "blue text "
-    ),
-    "embedded in this green text."
-].join())
+let attributeFunction = attribute("Foo", withValue: "Bar")
+let attributedString = attributeFunction("Baz").attributedString
 ```
 
-### Attributes
-Attribute functions take an array of attributed string convertibles, which are joined to form an attributed string.
+Multiple attributes can also be set at once:
+
+```swift
+let attributeFunction = attributesWithValues([
+    "Foo": "Bar",
+    "Bar": "Foo"
+])
+
+let attributedString = attributeFunction("Baz").attributedString
+```
+
+The `AttributeFunction` `typealias` is provided to define this function type.
+
+### Extension Attribute Functions
+The core of Attributed's functionality is in the extensions added to support the [standard attributes](https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/AttributedStrings/Articles/standardAttributes.html).
 
 #### Colors
 `NSColor` and `UIColor` are extended with these attribute functions:
@@ -98,17 +104,58 @@ To enforce valid values for the ligature attribute, the `Ligature` type is decla
 
 The `Ligature` enumeration is extended with the `attribute` function, which maps to `NSLigatureAttributeName`.
 
-#### Custom Attributes
-Custom attributes can be added with the `attribute` and `attributes` functions.
+### Composition
+Attributed extends `SequenceType` with `join()` functions, which make flattening sequences of `AttributedStringConvertible` and `AttributeFunction` values possible.
+
+```swift
+let attributedString = [
+    UIColor.redColor().foregroundAttribute("Red"),
+    UIColor.greenColor().foregroundAttribute("Green")
+].join().attributedString
+```
+
+```swift
+let attributes = [
+    UIColor.redColor().foregroundAttribute,
+    UIColor.greenColor().backgroundAttribute
+].join()
+
+let attributedString = attributes("Complementary").attributedString
+```
+
+If you are writing an extension that composes with Attributed, it's best to work in terms of these two types. Here's an extension that applies [Photoshop tracking values](http://www.devsign.co/notes/tracking-and-character-spacing), which require knowledge of both the current font and the tracking value, and thus cannot be implemented as an `AttributeFunction`-compatible extension of either type:
 
 ```swift
-UIColor.blueColor().foregroundColor([
-    "This is a blue string with a ",
-    attributes(
-        ["Custom": "Value"],
-        "custom attribute included"
+extension UIFont
+{
+    public func photoshopTrackingAttributes(tracking: CGFloat) -> AttributeFunction
+    {
+        return [attribute, (pointSize * tracking / 1000).kernAttribute].join()
+    }
+}
+```
+
+This is better than a function taking the tracking value and an attributed string convertible as two arguments and returning an `AttributedStringConvertible` because it can be composed with other attribute functions:
+
+```swift
+let attributes = [
+    UIColor.redColor().foregroundAttribute,
+    font.photoshopTrackingAttributes(500)
+].join()
+
+let attributedString = attributes("Tracked Red").attributedString
+```
+
+### Attribute Scoping
+Outer attributed values *do not* override inner values, so this code works as expected:
+
+```swift
+UIColor.greenColor().foregroundAttribute([
+    "There is some ",
+    UIColor.blueColor().foregroundAttribute(
+        "blue text "
     ),
-    "."
+    "embedded in this green text."
 ].join())
 ```