Suggested README enhancements

README.md

@@ -11,42 +11,84 @@ cite processor, please refer to the documentation of the
 [![Dependency Status](https://gemnasium.com/badges/github.com/inukshuk/citeproc-ruby.svg)](https://gemnasium.com/github.com/inukshuk/citeproc-ruby)
 [![Code Climate](https://codeclimate.com/github/inukshuk/citeproc-ruby/badges/gpa.svg)](https://codeclimate.com/github/inukshuk/citeproc-ruby)
 
-Quickstart
-----------
+
 Install CiteProc-Ruby and all official CSL styles (optional).
 
     $ [sudo] gem install citeproc-ruby
     $ [sudo] gem install csl-styles
 
-Start rendering you references with any CSL style!
+### Using a Processor for full bibliography and citations
+
+A CiteProc::Processor can generate a full bibliography and citations to it. First, you can create one with a certain style, locale, and format.
 
     require 'citeproc'
-    require 'csl/styles'
+    require 'csl/styles'  # optional, for quick access to styles
 
     # Create a new processor with the desired style,
     # format, and locale.
-    cp = CiteProc::Processor.new style: 'apa', format: 'text'
+    cp = CiteProc::Processor.new style: 'apa', format: 'text', locale: "en-US"
 
     # To see what styles are available in your current
     # environment, run `CSL::Style.ls'; this also works for
     # locales as `CSL::Locale.ls'.
 
-    # Tell the processor where to find your references. In this
-    # example we load them from a BibTeX bibliography using the
-    # bibtex-ruby gem.
+The `format` is generally `html` or `text`.
+
+As an alternative to loading `csl/styles` and passing a string as the `style`, you can also pass a filepath, or a URL. In either case pointing to a CSL style document. See https://github.com/citation-style-language/styles
+
+Next, you need to load your references into the CiteProc::Processor. These need to be in an array of CSL Data Input formatted hashes (See https://github.com/citation-style-language/schema/blob/master/csl-data.json).  The bibtex-ruby gem can convert bibtex to CSL data input:
+
     cp.import BibTeX.open('./references.bib').to_citeproc
 
-    # Now you are ready for rendering; the processor API
-    # provides three main rendering methods: `process',
-    # `append', or `bibliography'.
+Now, you can render. The processor API provides three main rendering methods: `process`, `append`, or `bibliography`, eg:
+
+    cp.bibligraphy
+
+For simple one-off renditions, you can also call `render` in bibliography or citation mode.
 
-    # For simple one-off renditions, you can also call
-    # `render' in bibliography or citation mode:
     cp.render :bibliography, id: 'knuth'
 
-    # This will return a rendered reference, like:
+This will return a rendered reference, like:
+
     #-> Knuth, D. (1968). The art of computer programming. Boston: Addison-Wesley.
 
+However, see the Renderer API below for a lighter-weight way to approach this.
+
+### Using a Renderer to render single references or citations
+
+If you don't need to create a full bibliography, but only render citations one at a time, you may find it more convenient, and get better performance, by using a `CiteProc::Ruby::Renderer` directly.
+
+You first have to create a renderer, which has a fixed format (text or html) and locale.
+
+    renderer = CiteProc::Ruby::Renderer.new :format => 'html', :locale => 'en-US'
+
+Now you can pass it individual CSL data input hashes as input, along with a ruby
+object representing a style and it's particular rendering mode (citation or bibliography):
+
+    renderer.render csl_data_input_hash, CSL::Style.load("apa").bibliography
+
+### Caching Style, Locale, and other arguments to maximize performance
+
+Loading the Style and Locale from XML files can be a fairly expensive operation. Even more so if you load from a remote URI of course.
+
+While neither the `CiteProc::Processor` nor the `CiteProc::Ruby::Renderer` are thread-safe, Style and Locale objects should be, so long as you aren't mutating them once loaded. To get maximum performance if you are creating multiple Processors or Renderers, you may want to load the Style and Locale objects once, and then pass them in when you create new Processors or Renderers.
+
+Every method shown above that can take a name (or path, or URI) for a locale or style, can also take an already loaded style or locale object.  You can use `CSL::Style#load` and `CSL::Locale.load` to load these.  Both of those methods can take identifiers from the `csl-styles` gem, local filepaths or URIs.
+
+    style = CSL::Style.load("apa")
+    locale = CSL::Locale.load("en-US")
+
+    cp = CiteProc::Processor.new style: style, format: 'text', locale: locale
+
+    renderer = CiteProc::Ruby::Renderer.new :format => 'html', :locale => 'en-US'
+    renderer.render csl_data_input_hash, style.bibliography
+
+In fact, for the `format` args, instead of passing a string `'html'` or `'text;`, you can pass ruby objects: `CiteProc::Ruby::Formats::Html.new` or `CiteProc::Ruby::Formats::Text.new` as well, although the performance difference is probably minimal.
+
+
+
+### Full CSL API
+
     # CiteProc-Ruby exposes a full CSL API to you; this
     # makes it possible to just alter CSL styles on the
     # fly. For example, what if we want names not to be