1 files changed, 185 insertions, 0 deletions
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..743c42b
--- /dev/null
+++ b/README.org
@@ -0,0 +1,185 @@
+* Trident Mode
+
+This is an [[http://www.gnu.org/software/emacs/][Emacs]] minor mode and collection of commands for working with
+[[http://common-lisp.net/project/parenscript/][Parenscript]] code in [[http://common-lisp.net/project/slime/][SLIME]] and sending it to the browser via [[https://github.com/skeeto/skewer-mode][Skewer]]. The goal is
+to create an environment for hacking Parenscript which fits as naturally as
+possible into the Lisp style of interactive development.
+
+Note that this is very young code and there are certain to be serious problems.
+
+There's at least one other project with related goals, [[https://github.com/3b/slime-proxy][slime-proxy]], though at
+the time of writing it's unclear whether it's still being actively developed.
+
+** Installation
+
+Trident has both [[http://en.wikipedia.org/wiki/Common_Lisp][Common Lisp]] and Emacs dependencies.
+
+- Common Lisp dependencies
+  - Your preferred [[http://en.wikipedia.org/wiki/Common_Lisp][Common Lisp]] implementation
+  - [[http://common-lisp.net/project/parenscript/][Parenscript]]
+
+You almost certainly want to use [[http://www.quicklisp.org/beta/][Quicklisp]] to install Parenscript.
+
+- Emacs dependencies
+  - [[http://common-lisp.net/project/slime/][SLIME]]
+  - [[https://github.com/skeeto/skewer-mode][Skewer]]
+  - [[https://github.com/magnars/dash.el][dash.el]]
+
+My recommendation is to install SLIME via the [[https://github.com/quicklisp/quicklisp-slime-helper][Quicklisp SLIME Helper]] and
+the others through [[http://www.emacswiki.org/emacs/ELPA][ELPA]].
+
+** Setup
+
+To enable =trident-mode= in a SLIME buffer: =M-x trident-mode=.
+
+To have =lisp-mode=, =slime-mode=, and =trident-mode= all enable automatically
+for any file with an extension of ".paren":
+
+#+BEGIN_SRC emacs-lisp
+  (add-to-list 'auto-mode-alist (cons "\\.paren\\'" 'lisp-mode))
+  (add-hook 'lisp-mode-hook
+            #'(lambda ()
+                (when (and buffer-file-name
+                           (s-ends-with? ".paren" buffer-file-name))
+                  (unless (slime-connected-p)
+                    (save-excursion (slime)))
+                  (trident-mode +1))))
+#+END_SRC
+
+=slime-mode= must be active for both expansion and evaluation commands. For
+evaluation commands, =skewer-mode= is also required. (See below for a list of
+the available commands).
+
+Parenscript must be loaded in your Common Lisp image, and you'll probably also
+want to import its symbols:
+
+#+BEGIN_SRC common-lisp
+  (ql:quickload :parenscript)
+  (use-package :parenscript)
+#+END_SRC
+
+** Commands
+
+*** Code expansion commands
+
+These commands generate JavaScript from the Parenscript code and display it but
+don't send it to the browser for evaluation:
+
+    - =trident-expand-sexp=
+    - =trident-expand-last-expression=
+    - =trident-expand-defun=
+    - =trident-expand-region=
+    - =trident-expand-buffer=
+    - =trident-expand-dwim=
+
+From within an expansion buffer you can press =e= to send the JavaScript to the
+browser, =w= to copy it to the kill ring, =s= to save it to a file (you'll be
+prompted for the destination) or =q= to dismiss the buffer. The copy command,
+=w=, acts on the region if it's active or the entire buffer otherwise.
+
+Additionally, you can use =M-x trident-compile-buffer-to-file= to expand the
+current buffer and save the generated code directly to a file.
+
+*** Code evaluation commands
+
+These commands first compile the Parenscript code to JavaScript and then
+immediately send to it the browser to be evaluated:
+
+    - =trident-eval-sexp=
+    - =trident-eval-last-expression=
+    - =trident-eval-defun=
+    - =trident-eval-region=
+    - =trident-eval-buffer=
+    - =trident-eval-dwim=
+
+** Key bindings
+
+The traditional set of code evaluation key bindings is a poor fit for Trident,
+since they would shadow SLIME's equivalent commands and that's probably not
+what you want. That leaves us without a clear convention to follow, so by
+default we don't establish any key bindings at all. However, the function
+=trident-add-keys-with-prefix= will add two-key key bindings for all commands
+behind a prefix of your choice.
+
+For example:
+
+#+BEGIN_SRC emacs-lisp
+  (trident-add-keys-with-prefix "C-c C-e")
+  ;; The key sequence for trident-eval-region is "e r", so it's now bound to "C-c
+  ;; C-e er"
+#+END_SRC
+
+The full list of key bindings =trident-add-keys-with-prefix= will establish is:
+
+    - =e RET= -- =trident-eval-sexp=
+    - =e e= -- =trident-eval-last-expression=
+    - =e d= -- =trident-eval-defun=
+    - =e r= -- =trident-eval-region=
+    - =e b= -- =trident-eval-buffer=
+    - =e SPC= -- =trident-eval-dwim=
+    - =x RET= -- =trident-expand-sexp=
+    - =x e= -- =trident-expand-last-expression=
+    - =x d= -- =trident-expand-defun=
+    - =x r= -- =trident-expand-region=
+    - =x b= -- =trident-expand-buffer=
+    - =x SPC= -- =trident-expand-dwim=
+
+Evaluation commands begin with an "e", expansion commands with "x". The second
+letter is generally mnemonic but not always. The =-sexp= commands use =RET= in
+correspondence to =slime-expand-1=, and the =-dwim= commands use the space bar
+because it's easy and comfortable to hit.
+
+Please consider these keys provisional, and let me know if you have any ideas
+for improving the arrangement.
+
+If you really want to shadow SLIME's key bindings in buffers where
+=trident-mode= is active you could do something like this:
+
+#+BEGIN_SRC emacs-lisp
+  (defun steal-slime-keys-for-trident! ()
+    ;; Don't affect all SLIME buffers, just where invoked
+    (make-local-variable 'slime-mode-map)
+    (let ((map slime-mode-map))
+      (define-key map (kbd "C-x C-e") nil)
+      (define-key map (kbd "C-c C-r") nil)
+      (define-key map (kbd "C-M-x")   nil)
+      (define-key map (kbd "C-c C-k") nil)
+      (define-key map (kbd "C-c C-m") nil))
+    (let ((map trident-mode-map))
+      (define-key map (kbd "C-x C-e") 'trident-eval-last-expression)
+      (define-key map (kbd "C-c C-r") 'trident-eval-region)
+      (define-key map (kbd "C-M-x")   'trident-eval-defun)
+      (define-key map (kbd "C-c C-k") 'trident-eval-buffer)
+      (define-key map (kbd "C-c C-m") 'trident-expand-sexp)))
+  
+  (add-hook 'trident-mode-hook 'steal-slime-keys-for-trident!)
+#+END_SRC
+
+** Other amenities
+
+=slime-selector= is a great feature and Trident can optionally integrate with
+it. If you call =trident-add-slime-selector-methods=, two entries related to
+=trident-mode= will be added. One, invoked with =p=, will take you to the most
+recently visited buffer where =trident-mode= is active (excluding buffers which
+are already visible). The other, on =P=, will take you to a scratch buffer with
+=trident-mode= enabled, creating the buffer if necessary.
+
+Speaking of the scratch buffer, the =trident-scratch= command will take you
+straight there.
+
+** Still do be done
+
+    - Test against a wider array of code. Are there problems with quoting?
+    - Better documentation.
+    - Look into adding a REPL.
+    - See if more integration with SLIME is possible.
+    - Command(s) for compiling to a file.
+    - Similar support for [[http://weitz.de/cl-who/][CL-WHO]] and/or [[https://github.com/paddymul/css-lite][CSS-LITE]]?
+    - Get to know ELPA and packaging.
+    - Add support for Customize.
+
+** Contributing
+
+Contributions are very welcome. Since I've just started working on this and
+don't have everything figured out yet, please first contact me on GitHub or
+send me an email so we can talk before you start working on something.