Improve documentation and Makefile.

diff --git a/Makefile b/Makefile
index 5c8affcb486e2f4bfbc619f43175eb9a0d4db13f..64b7d75731bfb68c6aa181624105c28a4e9ad8a3 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -1,9 +1,4 @@
-all:
-       exit
-
-test:
-       node_modules/.bin/mocha
-       emacs -batch -l ert -l test/context-coloring-test.el -f ert-run-tests-batch-and-exit
+all: clean install compile test
 
 benchjs:
        node_modules/.bin/matcha
@@ -11,4 +6,18 @@ benchjs:
 benchel:
        emacs -Q -L . -l context-coloring -l benchmark/scenarios.el
 
-.PHONY: all test benchmark
+compile:
+       emacs -batch -f batch-byte-compile *.el
+
+clean:
+       rm -rf node_modules
+       rm *.elc
+
+install:
+       npm install --production
+
+test:
+       node_modules/.bin/mocha
+       emacs -batch -L . -l ert -l context-coloring -l test/context-coloring-test.el -f ert-run-tests-batch-and-exit
+
+.PHONY: all benchjs benchel compile clean install test

diff --git a/README.md b/README.md
index 9d83b97f7338c8cb6bf956cafd25a448074d79d8..63e33b3886624cb90db8bcd25c62a03e0c4de5b8 100644 (file)
--- a/README.md
+++ b/README.md
@@ -4,23 +4,40 @@
   <img alt="Screenshot of JavaScript code highlighted by context." src="screenshot.png" title="Screenshot">
 </p>
 
-Highlights JavaScript code according to function context. Code in the global
-scope is white. Code in functions within the global scope is yellow, and code
-within such functions is green, etc. Identifiers retain the color of the scope
-in which they were defined. Comments are gray.
+Highlights JavaScript code according to function context.
+
+- Code in the global scope is one color. Code in functions within the global
+  scope is a different color, and code within such functions is another color,
+  and so on.
+- Identifiers retain the color of the scope in which they were declared.
+- Identifiers are bold when first declared.
+- Comments are gray and italic.
 
 This coloring scheme is probably more useful than conventional JavaScript
-*syntax* highlighting. Lexical scope information at-a-glance is probably more
-useful than detecting if you spelled "function" wrong, or determing that you
-forgot to close a string literal. (A [linter][] would serve you better in that
-regard.)
+*syntax* highlighting. Highlighting keywords can help detect spelling errors, or
+alert one to unclosed string literals; but so can a [linter][]. (If you haven't
+already, you should [integrate][emacs integration] one into your editor.)
+
+In JavaScript, we are constantly leveraging closures to bind nearby
+data. Lexical scope information at-a-glance can assist a programmer in
+understanding the overall structure of a program. It can also help curb nasty
+bugs like implicit globals and name shadowing, and act as an indicator of
+excessive complexity.
+
+There are some breakthrough advantages, too. Context coloring could enable a
+programmer to write in a functional style. It would be easy to tell when he had
+escaped the boundaries of his function and produced side-effects.
+
+Context coloring also improves a programmer's ability to write functions that
+construct objects with implicit private state (which is a good way to avoid
+`this` too).
 
 ## Usage
 
 Requires Emacs 24+ and [Node.js 0.10+][node].
 
 - Clone this repository.
-- Run `npm install --production` in it.
+- Run `make` in it.
 - Add it to your [load path][].
 - Add the following to your `~/.emacs`:
 
@@ -30,5 +47,6 @@ Requires Emacs 24+ and [Node.js 0.10+][node].
 ```
 
 [linter]: https://github.com/jacksonrayhamilton/jslinted
+[emacs integration]: https://github.com/jacksonrayhamilton/jslinted#emacs-integration
 [node]: http://nodejs.org/download/
 [load path]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html

diff --git a/context-coloring.el b/context-coloring.el
index 56ded483f2897d7428820c7c3fe90a8a0dd7dc45..1c399791bb8ab19328dc579aed59588a962b0728 100644 (file)
--- a/context-coloring.el
+++ b/context-coloring.el
@@ -1,4 +1,4 @@
-;;; context-coloring.el --- JavaScript syntax highlighting for grown-ups. -*- lexical-binding: t; -*-
+;;; context-coloring.el --- JavaScript syntax highlighting for grown-ups.  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2014 Jackson Ray Hamilton
 
@@ -22,15 +22,13 @@
 
 ;;; Commentary:
 
-;; Highlights JavaScript code according to function context. Code in the global
-;; scope is white, code in functions within the global scope is yellow, code
-;; within such functions is green, etc.
+;; Highlights JavaScript code according to function context.
 ;;
 ;; Usage:
 ;;
-;; Install Node.js 0.10.
-;;
-;; Put context-coloring.el on your load path. Then, in your ~/.emacs:
+;; Install Node.js 0.10+.
+;; Run `make` in this file's directory.
+;; In your ~/.emacs:
 ;;
 ;; (require 'context-coloring)
 ;; (add-hook 'js-mode-hook 'context-coloring-mode)

diff --git a/package.json b/package.json
index 8d3982af77cc02b80d270c939a9fea8829676462..bc1db336e0b0bcbd6ee75c332c9d24f808dbd5fa 100644 (file)
--- a/package.json
+++ b/package.json
@@ -1,8 +1,8 @@
 {
   "name": "context-coloring",
   "version": "0.0.0",
-  "description": "JavaScript syntax highlighting for grown-ups.",
-  "main": "index.js",
+  "description": "JavaScript syntax highlighting, except not for syntax.",
+  "main": "scopifier.js",
   "directories": {
     "test": "test"
   },
@@ -19,12 +19,12 @@
     "url": "https://github.com/jacksonrayhamilton/context-coloring/issues"
   },
   "homepage": "https://github.com/jacksonrayhamilton/context-coloring",
-  "devDependencies": {
-    "matcha": "^0.6.0",
-    "mocha": "^2.0.1"
-  },
   "dependencies": {
     "escope": "^1.0.1",
     "esprima": "^1.2.2"
+  },
+  "devDependencies": {
+    "matcha": "^0.6.0",
+    "mocha": "^2.0.1"
   }
 }