readme updated

Author: hpihkala

README.md

@@ -1,43 +1,50 @@
-<!-- Note that this readme is embedded on API Documentation page within Streamr. Please don't use first-level headings (h1). -->
-<!-- You should write this document so that it will work both as a stand-alone document in the public GitHub repo and as a section in the API docs. -->
+<!-- Note that this readme is embedded on API Documentation page within Streamr. Please don't use first-level headings (h1). You should write this document so that it will work both as a stand-alone document in the public GitHub repo and as a section in the API docs. -->
+<a name="js-client"></a>
+## Streamr JavaScript Client
 
-# streamr-client
+By using this client, you can easily subscribe to realtime [Streamr](http://www.streamr.com) streams from JavaScript-based environments, such as browsers and [node.js](https://nodejs.org). This enables you to use Streamr as an over-the-internet pub/sub engine with powerful analytics and automation features.
 
-This is a JavaScript client for subscribing to realtime streams from [Streamr](http://www.streamr.com). Streamr is a realtime stream processing and analytics platform. This client allows you to write JS applications that leverage the stream computing and pub/sub features of Streamr. It works both in the browser and in node.js.
+The client uses [socket.io](http://socket.io/) under the hood for streaming message delivery. It works in virtually all browsers by using websockets where available, or fallback methods on legacy browsers.
 
-The streamr-client uses [socket.io](http://socket.io/) under the hood for streaming message delivery. It works in virtually all browsers by using websockets where available, or fallback methods on legacy browsers.
+### Installation
 
-## Dependencies
+The client is available on [npm](https://www.npmjs.com/package/streamr-client) and can be installed simpy by:
+
+`npm install streamr-client`
+
+### Dependencies
 
 * [socket.io-client](https://cdn.socket.io/socket.io-1.3.7.js)
 * [debug](https://github.com/visionmedia/debug) (optional)
 
-In node.js, dependencies will be installed automatically with `npm install`. In the browser, make sure you include `socket.io-client` before `streamr-client`.
+In node.js, dependencies will be installed automatically with `npm install`. In the browser, make sure you include `socket.io-client` before `streamr-client` in your HTML.
 
-## Usage
+### Usage
 
-The `examples` directory contains snippets for both browser and node.js.
+The included `examples` directory contains snippets for both browser and node.js.
 
 ```javascript
-var client = new StreamrClient({ 
-	// Connection options can be omitted, these are the default values
-	server: 'https://data.streamr.com',
-	autoConnect: true,
-	autoDisconnect: true
+// Create a StreamrClient instance
+var client = new StreamrClient({
+    // Connection options can be omitted, these are the default values
+    server: 'https://data.streamr.com',
+    autoConnect: true,
+    autoDisconnect: true
 })
+
+// Subscribe to a stream
 var sub = client.subscribe(
-	'stream-id', 
-	function(message, streamId, timestamp, counter) {
-		// Do something with the message, which is an object
-	},
-	{ 
-		// Resend options, see below
-	}
+    'stream-id',
+    function(message, streamId, timestamp, counter) {
+        // Do something with a message, which is an object
+    },
+    {
+        // Resend options, see below
+    }
 )
-client.connect()
 ```
 
-## Handling messages
+### Handling messages
 
 The second argument to `client.subscribe(streamId, callback, resendOptions)` is the callback function that will be called for each message as they arrive. Its arguments are as follows:
 
@@ -49,7 +56,7 @@ timestamp| (optional) A javascript Date object containing the timestamp for this
 counter  | (optional) A sequence number for this message, if available.
 
 
-## Connection options
+### Connection options
 
 Option | Default value | Description
 ------ | ------------- | -----------
@@ -59,7 +66,7 @@ autoDisconnect | true  | If set to `true`, the client automatically disconnects
 transports | null | Override default transport selection / upgrade scheme. For example, value `["websocket"]` will force use of sockets right from the beginning, while value `["polling"]` will allow only long-polling to be used.
 
 
-## Resend options
+### Resend options
 
 Note that only one of the resend options can be used for a particular subscription. The default functionality is to resend nothing, only subscribe to messages from the subscription moment onwards.
 
@@ -71,7 +78,7 @@ resend_from | undefined | Resend from a specific message number.
 resend_from_time | undefined | Resend from a specific Date (or millisecond timestamp).
 resend_to | undefined | Can be used in conjunction with `resend_from` to limit the end of the resend. By default it is the newest message.
 
-## Methods
+### Methods
 
 Name | Description
 ---- | -----------
@@ -85,7 +92,7 @@ getSubscriptions(`streamId`) | Returns a list of `Subscriptions` for `streamId`.
 bind(eventName, function) | Binds a `function` to an event called `eventName`
 unbind(eventName, function) | Unbinds the `function` from events called `eventName`
 
-## Binding to events
+### Binding to events
 
 The client and the subscriptions can fire events as detailed below. You can bind to them using `bind`:
 
@@ -109,14 +116,14 @@ You can unbind using `unbind`:
 ```
 
 
-## Events on the StreamrClient instance
+### Events on the StreamrClient instance
 
 Name | Handler Arguments | Description
 ---- | ----------------- | -----------
 connected |  | Fired when the client has connected (or reconnected).
 disconnected |  | Fired when the client has disconnected (or paused).
 
-## Events on the Subscription object
+### Events on the Subscription object
 
 Name | Handler Arguments | Description
 ---- | ----------------- | -----------
@@ -126,9 +133,9 @@ resending |  | Fired when the subscription starts resending.
 resent |  | Fired after `resending` when the subscription has finished resending.
 no_resend |  | Fired after `resending` in case there was nothing to resend.
 
-## Logging
+### Logging
 
-This library supports the [debug](https://github.com/visionmedia/debug) library for logging.
+The Streamr JavaScript client library supports [debug](https://github.com/visionmedia/debug) for logging.
 
 In node.js, start your app like this: `DEBUG=StreamrClient node your-app.js`