[elpa] master 1ceb460 139/271: Documentation.

[Jackson Ray Hamilton]

branch: master
commit 1ceb4600f0eda8d5b85076abe22ebb31d4eb6d2a
Author: Jackson Ray Hamilton <address@hidden>
Commit: Jackson Ray Hamilton <address@hidden>

    Documentation.
---
 README.md             |   48 +++++++++++++++++++++++++++++++++++++++---------
 scopifier-example.png |  Bin 0 -> 2516 bytes
 2 files changed, 39 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 2d950f4..4a380be 100644
--- a/README.md
+++ b/README.md
@@ -31,16 +31,48 @@ code*.
 ## Features
 
 - Supported languages: JavaScript
-- Light and dark color schemes.
+- Light and dark (customizable) color schemes.
 - Fast async AST parsing. Some total parse + recolor times:
   - jQuery (9191 lines): 0.63 seconds
   - Lodash (6786 lines): 0.37 seconds
   - Async (1124 lines): 0.17 seconds
   - mkdirp (98 lines): 0.09 seconds
-- Extensible. Just write a scopifier for the language of your choice and add an
-  entry to `context-coloring-scopifier-plist`.
-- Customizable. If you don't like the color schemes, or you want them to match
-  your favorite theme, just `M-x customize` and search for "context-coloring".
+
+## Extending
+
+It would be great if this package supported more languages. I welcome any pull
+request that adds new language support.
+
+Extension is relatively straightforward. Write a "scopifier" for the language 
of
+your choice, add an entry to `context-coloring-scopifier-plist`, and the plugin
+should handle the rest.
+
+A "scopifier" is a CLI program that reads a buffer's contents from stdin, and
+then writes a JSON array of integers to stdout. Every three numbers in the 
array
+represent a range of color. For instance, if I fed the following string of
+JavaScript code to a scopifier,
+
+```js
+var a = function () {};
+```
+
+then the scopifier would produce the following array:
+
+```js
+[
+  1, 24, 0,
+  9, 23, 1
+]
+```
+
+Where, for every three numbers, the first number is a 1-indexed start 
[point][],
+the second number is an exclusive end point, and the third number is a scope
+level. The result of applying level 0 coloring to the range
+\[1, 24) and then applying level 1 coloring to the range \[9, 23) would result 
in the following coloring:
+
+<p align="center">
+  <img alt="Screenshot of ranges [1, 24) and [9, 23)." 
src="scopifier-example.png" title="Screenshot">
+</p>
 
 ## Usage
 
@@ -55,10 +87,7 @@ cd ~/.emacs.d/
 git clone https://github.com/jacksonrayhamilton/context-coloring.git
 ```
 
-- Add it to your [load path][].
-- Add a mode hook for `context-coloring-mode`.
-
-In your `~/.emacs` file:
+- Add the following to your `~/.emacs` file:
 
 ```lisp
 (add-to-list 'load-path "~/.emacs.d/context-coloring")
@@ -68,5 +97,6 @@ In your `~/.emacs` file:
 
 [linter]: https://github.com/jacksonrayhamilton/jslinted
 [integration]: https://github.com/jacksonrayhamilton/jslinted#emacs-integration
+[point]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html
 [node]: http://nodejs.org/download/
 [load path]: 
https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html
diff --git a/scopifier-example.png b/scopifier-example.png
new file mode 100644
index 0000000..1d690cb
Binary files /dev/null and b/scopifier-example.png differ