add docs to elisp file, use customize interface

diff --git a/Readme.org b/Readme.org
index 18ea79b2b554c5bf002bda14f1e18121cb98102d..9485f1b8a0fc0b75528176e12f0b3652a8e17f58 100644 (file)
--- a/Readme.org
+++ b/Readme.org
@@ -130,8 +130,3 @@ So, I am opening a bug on every project I find, asking them to document what fil
 ** Contributions are welcome!
 
 There's lots of features and enhancements to do. The algorithm and interface could certainly be improved in various ways.
-
-** Freedom To Read
-
-It is important to use and develop free software for this kind or program. Proprietary software of this kind usually collects information about what you read, which often ends up being used for purposes you would rather it not: personal spying, government spying, advertising profiling, discrimination by corporations and government, and more. This kind of proprietary software can also be used as a tool for drm and censorship. You can read more comprehensively about these and other issues at places like https://www.gnu.org/philosophy/right-to-read.html, https://www.gnu.org/philosophy/the-danger-of-ebooks.html, https://www.eff.org, https://fsf.org.
-

diff --git a/spray.el b/spray.el
index 95951ca2d05ab9c4b8dca6e624e0c4143c1643ab..5ce76ebe66704ffa66a7ad27b832cbf72b4b200d 100644 (file)
--- a/spray.el
+++ b/spray.el
@@ -1,6 +1,6 @@
 ;;; spray.el --- a speed reading mode
 
-;; Copyright (C) 2014 zk_phi
+;; Copyright (C) 2014 Ian Kelling <ian@iankelling.org>
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
@@ -16,32 +16,74 @@
 ;; along with this program; if not, write to the Free Software
 ;; Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 
-;; Author: zk_phi
-;; URL: http://hins11.yu-yake.com/
+;; Maintainer: Ian Kelling <ian@iankelling.org>
 ;; Author: Ian Kelling <ian@iankelling.org>
+;; Author: zk_phi
+;; Created: 18 Jun 2014
 ;; Version: 0.0.2
+;; URL: https://github.com/ian-kelling/spray
+;; Keywords: convenience
 
 ;;; Commentary:
 
-;; Put this script into a "load-path"ed directory, and load it in your
-;; init file.
-;;
+;; For speed reading, or just more enjoyable reading. Narrows the buffer to show
+;; one word at a time. Adjust speed / pause as needed.
+;; 
+;; Download from Melpa or put this script into a "load-path"ed directory, and
+;; load it in your init file:
+
 ;;   (require 'spray)
-;;
+
 ;; Then you may run spray with "M-x spray-mode". Binding some keys may
 ;; also be useful.
-;;
+
 ;;   (global-set-key (kbd "<f6>") 'spray-mode)
-;;
-;; For more informations, see Readme.org.
 
-;; Known bugs.
+;; In spray-mode buffers, following commands are available.
+
+;; - =spray-start/stop= (SPC) ::
+;; pause or resume spraying
+
+;; - =spray-backward-word= (h, <left>) ::
+;; pause and back to the last word
+
+;; - =spray-forward-word= (l, <right>) ::
+;; inverse of =spray-backward-word=
+
+;; - =spray-faster= (f) ::
+;; increases speed
+
+;; - =spray-slower= (s) ::
+;; decreases speed
+
+;; - =spray-quit= (q, <return>) ::
+;; quit =spray-mode=
+
+;; You may customize spray by modifying following items:
+
+;; - [Variable] spray-wpm
+;; - [Variable] spray-height
+;; - [Variable] spray-margin-top
+;; - [Variable] spray-margin-left
+;; - [Variable] spray-ramp
+;; - [Keymap] spray-mode-map
+;; - [Face] spray-base-face
+;; - [Face] spray-accent-face
+
+;; Readme.org from the package repository has some additional information:
+;; A gif screencast.
+;; Algorithm specification.
+;; Comparison with similar projects.
+
+;;; Known bugs:
+
 ;; repeated words are indistinguishable, for example
 ;; "going, going, gone" reads like going, gone, with a slight delay.
 ;;
 ;; sentences (like this) should trigger a pause for ( and )
 
 ;;; Change Log:
+
 ;; 0.0.0 test release
 ;; 0.0.1 add spray-set-margins
 ;; 0.0.2 margin options, speed control, better quit
@@ -52,23 +94,56 @@
 
 ;; * customizable vars
 
-(defvar spray-wpm 400
-  "words/min")
+(defcustom spray-wpm 400
+  "Words per minute"
+  :group 'spray
+  :type 'integer)
+
+(defcustom spray-height 400
+  "Height of characters"
+  :group 'spray
+  :type 'integer)
+
+(defcustom spray-margin-top 1
+  "Character margin at top of buffer. Characters are as big as
+  spray text characters."
+  :group 'spray
+  :type 'integer)
+
+(defcustom spray-margin-left 1
+  "Character margin at left of buffer. Characters are as big as
+  spray text characters."
+  :group 'spray
+  :type 'integer)
+
+(defcustom spray-ramp 2
+  "Initial words before ramping up to full speed. Pauses for
+this multiple of wpm on the first word,
+decreasing by one for each subsequent word."
+  :group 'spray
+  :type 'integer)
+
+(defcustom spray-unsupported-minor-modes
+  '(buffer-face-mode smartparens-mode highlight-symbol-mode)
+  "Minor modes to toggle off when in spray mode."
+  :group 'spray
+  :type '(list symbol))
 
-(defvar spray-height 400
-  "height of characters")
 
-(defvar spray-margin-top 1
-  "character margin at top of buffer. Characters are as big as
-  spray text characters.")
+;; * faces
+
+(defface spray-base-face
+  '((t (:inherit default)))
+  "Face for non-accent characters."
+  :group 'spray)
 
-(defvar spray-margin-left 1
-  "character margin at left of buffer. Characters are as big as
-  spray text characters.")
+(defface spray-base-face
+  '((t (:foreground "red" :inherit spray-base-face)))
+  "Face for accent character."
+  :group 'spray)
 
-(defvar spray-ramp 2
-  "Ramp up to full speed. Pause for this multiple of wpm on the first word,
-decreasing by one for each subsequent word.")
+
+;; keymap
 
 (defvar spray-mode-map
   (let ((km (make-sparse-keymap)))
@@ -89,19 +164,6 @@ decreasing by one for each subsequent word.")
     km)
   "keymap for spray-mode buffers")
 
-(defvar spray-unsupported-minor-modes
-  '(buffer-face-mode smartparens-mode highlight-symbol-mode))
-
-;; * faces
-
-(make-face 'spray-base-face)
-(set-face-attribute 'spray-base-face nil
-                    :inherit 'default)
-
-(make-face 'spray-accent-face)
-(set-face-attribute 'spray-accent-face nil
-                    :inherit 'spray-base-face
-                    :foreground "red")
 
 ;; * internal vars