Get ready to list this thing on MELPA

2 files changed, 170 insertions, 6 deletions

diff --git a/README.org b/README.org
index 1530f25..b64cf6a 100644
--- a/README.org
+++ b/README.org
@@ -5,8 +5,6 @@ This is an [[http://www.gnu.org/software/emacs/][Emacs]] minor mode and collecti
 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.
 
diff --git a/trident-mode.el b/trident-mode.el
index 6f1dc44..9ddedca 100644
--- a/trident-mode.el
+++ b/trident-mode.el
@@ -3,7 +3,8 @@
 ;; This is free and unencumbered software released into the public domain.
 
 ;; Author: John Mastro <john.b.mastro@gmail.com>
-;; Version: 0.0.1
+;; URL: https://github.com/johnmastro/trident-mode.el
+;; Version: 0.9.1
 ;; Keywords: languages, lisp, processes, tools
 ;; Package-Requires: ((slime "2013-05-26") (skewer-mode "1.5.0") (dash "1.0.3"))
 
@@ -14,10 +15,175 @@
 ;; is to create an environment for hacking Parenscript which fits as naturally
 ;; as possible into the Lisp style of interactive development.
 
-;; See https://github.com/johnmastro/trident-mode.el for additional information.
+;; ** Installation
 
-;; Note that this is very young code and there are certain to be serious
-;; problems.
+;; Trident has both Common Lisp and Emacs dependencies.
+
+;; - Common Lisp dependencies
+;;   - Your preferred Common Lisp implementation
+;;   - Parenscript
+
+;; You almost certainly want to use Quicklisp to install Parenscript.
+
+;; - Emacs dependencies
+;;   - SLIME
+;;   - Skewer
+;;   - dash.el
+
+;; My recommendation is to install SLIME via the Quicklisp SLIME Helper and the
+;; others, including Trident itself, through Emacs's package.el infrastructure.
+
+;; ** 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":
+
+;;   (add-to-list 'auto-mode-alist (cons "\\.paren\\'" 'lisp-mode))
+;;   (add-hook 'lisp-mode-hook
+;;             #'(lambda ()
+;;                 (when (and buffer-file-name
+;;                            (string-match-p "\\.paren\\>" buffer-file-name))
+;;                   (unless (slime-connected-p)
+;;                     (save-excursion (slime)))
+;;                   (trident-mode +1))))
+
+;; Parenscript must be loaded in your Common Lisp image, and you'll probably
+;; also want to import its symbols:
+
+;;   (ql:quickload :parenscript)
+;;   (use-package :parenscript)
+
+;; With the above taken care of it's time to skewer the browser. See Skewer's
+;; README for detailed information on the multiple ways you can connect to a
+;; site - including sites on servers you don't control.
+
+;; The fastest way to simply try things out is to run M-x run-skewer. Skewer
+;; will load an empty page in your browser and connect to it. You can
+;; immediately begin using Trident's evaluation commands (described below); to
+;; additionally open a JavaScript REPL you can run M-x skewer-repl.
+
+;; ** 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: (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"
+
+;; 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:
+
+;;   (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!)
+
+;; ** 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 CL-WHO and/or 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.
 
 ;;; Code: