Updated Readme to highlight new features in 3.0

Author: stig

Changes.md

@@ -4,7 +4,7 @@
 
 ### Changes
 
-* Fleshed out [API documentation](http://stig.github.com/json-framework/3.0/)
+* Fleshed out the [API documentation][api].
 * Remove the (admittedly rather cool) JavaScript hack from the Contrib directory, as I don't want to get stuck maintaining JavaScript I don't understand after 3.0.
 * Moved content of Installation file to Readme.
 * [Issue 73][#73]: Project rename, to avoid clashing with Apple's internal JSON.framework
@@ -320,3 +320,4 @@ http://code.google.com/p/json-framework/wiki/ReleaseNotes
 [#1]: http://github.com/stig/json-framework/issues/1
 
 [bench]: http://github.com/samsoffes/json-benchmarks
+[api]: http://stig.github.com/json-framework/api/3.0

Readme.md

@@ -1,40 +1,60 @@
 SBJson (aka json-framework)
 ===========================
 
-JSON (JavaScript Object Notation) is a light-weight data interchange
-format that's easy to read and write for humans and computers alike.
-This framework implements a strict JSON parser and generator in
-Objective-C.
+JSON (JavaScript Object Notation) is a light-weight data interchange format that's easy to read and write for humans and computers alike. This library implements strict JSON parsing and generation in Objective-C.
 
-Features
---------
+New Features, Changes, and Notable Enhancements in 3.0
+------------------------------------------------------
+
+### JSON Stream Support
+
+We now support parsing of documents split into several NSData chunks, like those returned by *NSURLConnection*. This means you can start parsing a JSON document before it is fully downloaded. Depending how you configure the delegates you can chose to have the entire document delivered to your process when it's finished parsing, or delivered bit-by-bit as records on a particular level finishes downloading. For more details see *SBJsonStreamParser* and *SBJsonStreamParserAdapter* in the [API docs][api].
+
+There is also support for *writing to* JSON streams. This means you can write huge JSON documents to disk, or an HTTP destination, without having to hold the entire structure in memory. You can use this to generate a stream of tick data for a stock trading simulation, for example. For more information see *SBJsonStreamWriter* in the [API docs][api].
+
+### Parse and write UTF8-encoded NSData
+
+The internals of *SBJsonParser* and *SBJsonWriter* have been rewritten to be NSData based. It is no longer necessary to convert data returned by NSURLConnection into an NSString before feeding it to the parser. The old NSString-oriented API methods still exists, but now converts their inputs to NSData objects and delegates to the new methods.
+
+### Project renamed to SBJson
+
+The project was renamed to avoid clashing with Apple's private JSON.framework. (And to make it easier to Google for.)
+
+* If you copy the classes into your project then all you need to update is to change the header inclusion from `#import "JSON.h"` to `#import "SBJson.h"`.
+* If you link to the library rather than copy the classes you have to change the library you link to. On the Mac `JSON.framework` became `SBJson.framework`. On iOS `libjson.a` became `libsbjson-ios.a`. In both cases you now have to `#import <SBJson/SBJson.h>` in your code.
+
+### API documentation integrated with Xcode
+
+The *InstallDocumentation.sh* script allows you to generate [API documentation][api] from the source and install it into Xcode, so it's always at your fingertips. (This script requires [Doxygen][] to be installed.) After running the script from the top-level directory, open Xcode's documentation window and search for SBJson. (You might have to close and re-open Xcode for the changes to take effect.)
+
+### TweetStream Example Project
+
+An example project showing how to use the new streaming functionality to interact with Twitter's multi-document streams. This also shows how to link to the iOS static lib rather than having to copy the classes into your project.
+
+### DisplayPretty Example Project
+
+A small Mac example project showing how to link to an external JSON framework rather than copying the sources into your project. This is a fully functional (though simplistic) application that takes JSON input from a text field and presents it nicely formatted into another text field.
+
+Features also present in previous versions
+------------------------------------------
 
 * BSD license.
-* Super-simple high-level API:
-  * Calling `-JSONValue` on any NSString instance parses the JSON text in that string.
-  * Calling `-JSONRepresentation` on any NSArray or NSDictionary returns an NSString with the JSON representation of the object.
-* Object-oriented API providing a good balance between simplicity and flexibility. Check out:
-  * `SBJsonParser`
-  * `SBJsonWriter`
-* Streaming JSON support. You can start parsing a JSON document--*and return parsed chunks of it to your program*--before it has finished downloading from the server. Check out:
-  * `SBJsonStreamParser`
-  * `SBJsonStreamWriter`
-* Works with/without garbage collection.
-* Pretty-printing of JSON output.
-* Sorted dictionary keys in JSON output.
+* Super-simple high-level API: Calling `-JSONValue` on any NSString instance parses the JSON text in that string, and calling `-JSONRepresentation` on any NSArray or NSDictionary returns an NSString with the JSON representation of the object.
+* The *SBJsonParser* and *SBJsonWriter* classes provides an object-oriented API providing a good balance between simplicity and flexibility.
 * Configurable recursion depth limit for added security.
+* Supports (but does not require) garbage collection.
+* Sorted dictionary keys in JSON output.
+* Pretty-printing of JSON output.
 
-Simple Installation
-===================
+Installation
+============
 
-The simplest way to start using JSON in your application is to simply
-copy all the source files (the contents of the `Classes` folder) into
-your own Xcode project.
+The simplest way to start using JSON in your application is to copy all the source files (the contents of the `Classes` folder) into your own Xcode project.
 
 1. In the Finder, navigate to the `$PATH_TO_SBJSON/Classes` folder and select all the files.
 1. Drop-and-drop them into your Xcode project.
 1. Tick the **Copy items into destination group's folder** option.
-1. Use `#import "SBJson.h"` in  your source files. (or simply include the particular classes you wish to use.)
+1. Use `#import "SBJson.h"` in  your source files.
 
 That should be it. Now create that Twitter client!
 
@@ -43,25 +63,23 @@ Upgrading
 
 If you're upgrading from a previous version, make sure you're deleting the old SBJson classes first, moving all the files to Trash.
 
-Install API documentation into Xcode
-====================================
-
-From the top-level project directory, run the `./InstallDocumentation.sh` program. This compiles the documentation and installs it so it integrates with Xcode. Now open Xcode documentation and search for SBJson. You should see a lot of the classes. (Generating the documentation requires [Doxygen](http://doxygen.org) to be installed.)
 
+Linking rather than copying
+---------------------------
 
-Alternative installation instructions
-=====================================
-
-Copying the SBJson classes into your project isn't the only way to use this framework. (Though it is the simplest.) I've created a couple of examples that link to this framework rather than copy the sources. Check them out at github:
+Copying the SBJson classes into your project isn't the only way to use this framework. (Though it is the simplest.) With Xcode 4's workspaces it has become much simpler to link to dependant projects. The examples in the distribution link to the iOS library and Mac framework, respectively.
 
 * [Linking to JSON Framework on iOS](http://github.com/stig/JsonSampleIPhone)
 * [Linking to JSON Framework on the Mac](http://github.com/stig/JsonSampleMac)
 
 
 Links
------
+=====
 
 * [GitHub project page](http://github.com/stig/json-framework).
 * [Example Projects](http://github.com/stig/json-framework/Examples).
 * [Online API docs](http://stig.github.com/json-framework/api).
 * [Frequently Asked Questions](http://github.com/stig/json-framework/wiki/FrequentlyAskedQuestions)
+
+[api]: http://stig.github.com/json-framework/api/3.0/
+[Doxygen]: http://doxygen.org