Cleaned up developer doc

Proof'd everything and improved flow
Renamed advanced to events
Reordered sending/receiving
Added text type to languages for prism plugin

developer/sending/caches.md

@@ -1,9 +1,13 @@
 # Caches, Flush and Ping
 
-For performance reasons, most if not all, of the client libraries will cache outgoing data so that bigger chunks can be written to the network at one time. This may be as simple as a byte buffer that stores up a few messages before being pushed to the network. It is the libraries job to make sure messages flow in a high performance manner. But there may be times when an application needs to know that a message has "hit the wire." In this case, applications can use a flush call to tell the library to move data through the system.
+For performance reasons, most if not all, of the client libraries will cache outgoing data so that bigger chunks can be written to the network at one time. This may be as simple as a byte buffer that stores up a few messages before being pushed to the network.
+
+These buffers do not hold messages forever, generally they are designed to hold messages in high throughput scenarios, while still providing good latency in low throughput situations.
+
+It is the libraries job to make sure messages flow in a high performance manner. But there may be times when an application needs to know that a message has "hit the wire." In this case, applications can use a flush call to tell the library to move data through the system.
 
 !INCLUDE "../../_examples/flush.html"
 
 ## Flush and Ping/Pong
 
-Many of the client libraries use the PING/PONG interaction built into the NATS protocol to insure that flush pushed all of the cached messages to the server. When an application calls flush, in this case, the library will put a PING on the outgoing queue of messages, and wait for the server to send PONG before saying that the flush was successful.
+Many of the client libraries use the PING/PONG interaction built into the NATS protocol to insure that flush pushed all of the cached messages to the server. When an application calls flush most libraries will put a PING on the outgoing queue of messages, and wait for the server to send PONG before saying that the flush was successful.

developer/sending/intro.md

@@ -1,5 +1,7 @@
 # Sending Messages
 
-NATS sends and receives messages using a protocol that includes a target subject, an optional reply subject and an array of bytes. Some libraries may provide helpers to convert other data formats to and from bytes, but the NATS server will treat all messages as opaque byte arrays. All of the NATS clients are designed to make sending a message simple. For example, to send the string “All is Well” to the “updates” subject as a UTF-8 string of bytes you would do:
+NATS sends and receives messages using a protocol that includes a target subject, an optional reply subject and an array of bytes. Some libraries may provide helpers to convert other data formats to and from bytes, but the NATS server will treat all messages as opaque byte arrays.
+
+All of the NATS clients are designed to make sending a message simple. For example, to send the string “All is Well” to the “updates” subject as a UTF-8 string of bytes you would do:
 
 !INCLUDE "../../_examples/publish_bytes.html"

developer/sending/request_reply.md

@@ -1,9 +1,94 @@
 # Request-Reply
 
-The pattern of sending a message and receiving a response is encapsulated in most client libraries into a request method. Under the covers this method will publish a message with a unique reply-to subject and wait for the response before returning. In the older versions of some libraries a completely new reply-to subject is created each time. In newer versions, a subject hierarchy is used so that a single subscriber in the client library listens for a wildcard, and requests are sent with a unique child subject of a single subject.
+The pattern of sending a message and receiving a response is encapsulated in most client libraries into a request method. Under the covers this method will publish a message with a unique reply-to subject and wait for the response before returning.
 
-The primary difference between the request method and publishing with a reply-to is that the library is only going to accept one response, and in most libraries the request will be treated as a synchronous action. The library may provide a way to set the timeout. For example, updating the previous publish example we may request `time` with a one second timeout:
+In the older versions of some libraries a completely new reply-to subject is created each time. In newer versions, a subject hierarchy is used so that a single subscriber in the client library listens for a wildcard, and requests are sent with a unique child subject of a single subject.
+
+The primary difference between the request method and publishing with a reply-to is that the library is only going to accept one response, and in most libraries the request will be treated as a synchronous action. The library may even provide a way to set the timeout.
+
+For example, updating the previous publish example we may request `time` with a one second timeout:
 
 !INCLUDE "../../_examples/request_reply.html"
 
-You can also build your own request-reply using publish-subscribe if you need a different semantic or timing.
+You can think of request-reply in the library as a subscribe, get one message, unsubscribe pattern. In Go this might look something like:
+
+```go
+sub, err := nc.SubscribeSync(replyTo)
+if err != nil {
+    log.Fatal(err)
+}
+nc.Flush()
+
+// Send the request
+nc.PublishRequest(subject, replyTo, []byte(input))
+
+// Wait for a single response
+for {
+    msg, err := sub.NextMsg(1 * time.Second)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    response = string(msg.Data)
+    break
+}
+sub.Unsubscribe()
+```
+
+## Scatter-Gather
+
+You can expand the request-reply pattern into something often called scatter-gather. To receive multiple messages, with a timeout, you could do something like the following, where the loop getting messages is using time as the limitation, not the receipt of a single message:
+
+```go
+sub, err := nc.SubscribeSync(replyTo)
+if err != nil {
+    log.Fatal(err)
+}
+nc.Flush()
+
+// Send the request
+nc.PublishRequest(subject, replyTo, []byte(input))
+
+// Wait for a single response
+max := 100 * time.Millisecond
+start := time.Now()
+for time.Now().Sub(start) < max {
+    msg, err := sub.NextMsg(1 * time.Second)
+    if err != nil {
+        break
+    }
+
+    responses = append(responses, string(msg.Data))
+}
+sub.Unsubscribe()
+```
+
+Or, you can loop on a counter and a timeout to try to get _at least N_ responses:
+
+```go
+sub, err := nc.SubscribeSync(replyTo)
+if err != nil {
+    log.Fatal(err)
+}
+nc.Flush()
+
+// Send the request
+nc.PublishRequest(subject, replyTo, []byte(input))
+
+// Wait for a single response
+max := 500 * time.Millisecond
+start := time.Now()
+for time.Now().Sub(start) < max {
+    msg, err := sub.NextMsg(1 * time.Second)
+    if err != nil {
+        break
+    }
+
+    responses = append(responses, string(msg.Data))
+
+    if len(responses) >= minResponses {
+        break
+    }
+}
+sub.Unsubscribe()
+```