iankelling.org Git - spray/blob - README.org

   1 * spray.el
   2
   3 A speed reading mode for Emacs
   4
   5
   6 ** Screencast
   7
   8 [[screencast.gif]]
   9
  10 The story continues at [[https://www.gnu.org/philosophy/right-to-read.html][gnu.org]]
  11
  12 ** Installation
  13
  14 Put spray.el into a "load-path"ed directory, and load it in your init
  15 file.
  16
  17 : (require 'spray)
  18
  19 Then you can start spraying from the cursor position with =M-x
  20 spray-mode=. Binding some keys may also be useful.
  21
  22 : (global-set-key (kbd "<f6>") 'spray-mode)
  23
  24 ** Commands
  25
  26 In spray-mode buffers, following commands are available.
  27
  28 - =spray-start/stop= (SPC) ::
  29      pause or resume spraying
  30
  31 - =spray-backward-word= (h, <left>) ::
  32      pause and back to the last word
  33
  34 - =spray-forward-word= (l, <right>) ::
  35      inverse of =spray-backward-word=
  36
  37 - =spray-faster= (f) ::
  38      increases speed
  39
  40 - =spray-slower= (s) ::
  41      decreases speed
  42
  43 - =spray-quit= (q, <return>) ::
  44      quit =spray-mode=
  45
  46
  47 ** Customization
  48
  49 You may customize spray by modifying following items:
  50
  51 - [Variable] spray-wpm
  52 - [Variable] spray-height
  53 - [Variable] spray-margin-top
  54 - [Variable] spray-margin-left
  55 - [Variable] spray-ramp
  56 - [Keymap] spray-mode-map
  57 - [Face] spray-base-face
  58 - [Face] spray-accent-face
  59
  60 ** If your emacs color theme does not work well with spray
  61
  62 You could create a function to toggle the emacs theme to one that
  63 works with spray, and then put that in the spray mode hook. For example:
  64
  65 #+begin_src emacs-lisp
  66 (defun toggle-night ()
  67  (interactive)
  68   (if (equal (car custom-enabled-themes) 'naquadah)
  69       (override-theme 'leuven)
  70   (override-theme 'naquadah)))
  71 (add-hook 'spray-mode-hook 'toggle-night)
  72 #+end_src
  73
  74 Alternatively, one user found ways to setup a single buffer with better colors, using
  75 - http://www.emacswiki.org/emacs/BufferBackgroundColor
  76 - https://github.com/vic/color-theme-buffer-local
  77
  78 He also found this library useful:
  79 https://github.com/ShingoFukuyama/ov.el
  80
  81
  82 ** Feedback, bugs, contributions, all welcome
  83
  84 All on: https://gitlab.com/iankelling/spray
  85
  86 There's lots of features and enhancements to do. The algorithm and interface could certainly be improved in various ways.
  87
  88
  89 ** Similar emacs package: speedread
  90
  91 Available in marmalade or [[https://github.com/vapniks/speedread/blob/master/speedread.el][github]] It has several nice features and does
  92 not align on an accent character. Eventually I'd like to merge the two
  93 packages.
  94
  95 ** Deficiencies in similar projects which spray.el solves:
  96
  97 The algorithm is inspired from [[https://github.com/Miserlou/OpenSpritz][OpenSpritz]].
  98
  99 Mostly as of June 28, 2014.
 100
 101 For all other projects:
 102 - It is very difficult to save your place and come back later. Emacs has
 103   lots of built in features like bookmarks or just making a note which
 104   make this easy.
 105 - No keybinds. This is especially useful for common, quickly used
 106   functionality like pause and back up.
 107
 108 Specific projects:
 109 - [[https://github.com/jbmartinez/speed-readerff][speed-readerff]] firefox extension.
 110 - [[https://github.com/cameron/squirt][squirt]] javascript bookmarklet.
 111 - [[https://github.com/Miserlou/OpenSpritz][OpenSpritz]] javascript bookmarklet.
 112   - Very difficult selecting where to start / what exactly to read.
 113   - Very difficult to figure out where you are within a document.
 114
 115 - [[https://github.com/chaimpeck/spray][spray]] website you paste text into.
 116   - Very difficult to figure out where you are within a document.
 117
 118 - [[https://github.com/xypiie/spread0r][spread0r]] Perl program.
 119   - No apparent way to resize text.
 120   - Very difficult to figure out where you are within a document.
 121
 122 - [[https://github.com/the-happy-hippo/sprits-it][sprits-it]] website or bookmarklet. Looks most promising of the web based projects.
 123   - Very difficult selecting where to start / what exactly to read.
 124   - Somewhat difficult to figure out where you are in a document.
 125
 126 Programs that I, Ian Kelling, didn't try, and why. They also probably have a lot of the problems listed above.
 127 - https://github.com/pasky/speedread No simple way to resize text from default of too small.
 128 - https://github.com/ds300/jetzt Chrome plugin: Chrome is proprietary, and its open source version is unfriendly to linux distros so they don't package it, and it's readme does not list any benefit to this program over others.
 129 - https://github.com/Fr4ncis/openspritz-ios ios program. I don't have an ios device, and this does not appear to have any compelling features.
 130 - https://github.com/OnlyInAmerica/OpenSpritz-Android android program. If I knew how to quickly move reading material to my phone, I would try this out. But, it's readme shows that the program is pretty sparse and would have some of the same problems as listed above, so not worth it.
 131
 132
 133 Downsides compared to similar projects:
 134 - The emacs learning curve.
 135 - Would be hard to get running on a phone.
 136
 137
 138 ** Algorithm details
 139
 140 *** Main algorithm code location
 141 In =./spray.el=, the functions =spray--word-at-point=, =spray--update= and =spray-start= contain the main algorithm of choosing a word, an accent character and an interval to display it. Word splitting is also duplicated the same way as in those functions throughout ./spray.el.
 142
 143 *** Algorithm translated from code to english
 144
 145 Words are split at space, tab, newline, and emdash characters.
 146
 147 Each word is displayed for (60 / the choosen wpm) seconds, except if the
 148 word ends with =.!?,;:—= or is greater than 9 characters long, in which
 149 case it is displayed for twice as long.
 150
 151 When started, an added delay is optionally added, based on the
 152 spray-ramp variable. See it's documentation for details.
 153
 154 The accent location is chosen as the nth character in a word, depending
 155 on its length, based on the following table
 156 | length | accent position |
 157 |      1 |               1 |
 158 |    2-5 |               2 |
 159 |    6-9 |               3 |
 160 |  10-13 |               4 |
 161 |    14+ |               5 |