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

   1 * spray.el
   2
   3 A speed reading mode for Emacs.
   4
   5 The algorithm is inspired from [[https://github.com/Miserlou/OpenSpritz][OpenSpritz]].
   6
   7
   8 ** Screencast
   9
  10 [[screencast.gif]]
  11
  12 The story continues at [[https://www.gnu.org/philosophy/right-to-read.html][gnu.org]]
  13
  14 ** Installation
  15
  16 Put spray.el into a "load-path"ed directory, and load it in your init
  17 file.
  18
  19 : (require 'spray)
  20
  21 Then you can start spraying from the cursor position with =M-x
  22 spray-mode=. Binding some keys may also be useful.
  23
  24 : (global-set-key (kbd "<f6>") 'spray-mode)
  25
  26 ** Commands
  27
  28 In spray-mode buffers, following commands are available.
  29
  30 - =spray-start/stop= (SPC) ::
  31      pause or resume spraying
  32
  33 - =spray-backward-word= (h, <left>) ::
  34      pause and back to the last word
  35
  36 - =spray-forward-word= (l, <right>) ::
  37      inverse of =spray-backward-word=
  38
  39 - =spray-faster= (f) ::
  40      increases speed
  41
  42 - =spray-slower= (s) ::
  43      decreases speed
  44
  45 - =spray-quit= (q, <return>) ::
  46      quit =spray-mode=
  47
  48
  49 ** Customization
  50
  51 You may customize spray by modifying following items:
  52
  53 - [Variable] spray-wpm
  54 - [Variable] spray-height
  55 - [Variable] spray-margin-top
  56 - [Variable] spray-margin-left
  57 - [Variable] spray-ramp
  58 - [Keymap] spray-mode-map
  59 - [Face] spray-base-face
  60 - [Face] spray-accent-face
  61
  62 ** Feedback, bugs, etc.
  63
  64 Bug tracking is on github.
  65 Mailing list for any feedback, questions, etc: https://lists.iankelling.org/listinfo/spray
  66
  67
  68 ** Similar emacs package: speedread
  69
  70 Available in marmalade or [[https://github.com/vapniks/speedread/blob/master/speedread.el][github]] It has several nice features and does
  71 not align on an accent character. Eventually I'd like to merge the two
  72 packages.
  73
  74 ** Deficiencies in similar projects which spray.el solves:
  75
  76 Mostly as of June 28, 2014.
  77
  78 For all other projects:
  79 - It is very difficult to save your place and come back later. Emacs has
  80   lots of built in features like bookmarks or just making a note which
  81   make this easy.
  82 - No keybinds. This is especially useful for common, quickly used
  83   functionality like pause and back up.
  84
  85 Specific projects:
  86 - [[https://github.com/jbmartinez/speed-readerff][speed-readerff]] firefox extension.
  87 - [[https://github.com/cameron/squirt][squirt]] javascript bookmarklet.
  88 - [[https://github.com/Miserlou/OpenSpritz][OpenSpritz]] javascript bookmarklet.
  89   - Very difficult selecting where to start / what exactly to read.
  90   - Very difficult to figure out where you are within a document.
  91
  92 - [[https://github.com/chaimpeck/spray][spray]] website you paste text into.
  93   - Very difficult to figure out where you are within a document.
  94
  95 - [[https://github.com/xypiie/spread0r][spread0r]] Perl program.
  96   - No apparent way to resize text.
  97   - Very difficult to figure out where you are within a document.
  98
  99 - [[https://github.com/the-happy-hippo/sprits-it][sprits-it]] website or bookmarklet. Looks most promising of the web based projects.
 100   - Very difficult selecting where to start / what exactly to read.
 101   - Somewhat difficult to figure out where you are in a document.
 102
 103 Programs that I, Ian Kelling, didn't try, and why. They also probably have a lot of the problems listed above.
 104 - https://github.com/pasky/speedread No simple way to resize text from default of too small.
 105 - 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.
 106 - 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.
 107 - 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.
 108
 109
 110 Downsides compared to similar projects:
 111 - The emacs learning curve.
 112 - Would be hard to get running on a phone.
 113
 114
 115 ** Algorithm details
 116
 117 *** Main algorithm code location
 118 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.
 119
 120 *** Algorithm translated from code to english
 121
 122 Words are split at space, tab, newline, and emdash characters.
 123
 124 Each word is displayed for (60 / the choosen wpm) seconds, except if the
 125 word ends with =.!?,;:—= or is greater than 9 characters long, in which
 126 case it is displayed for twice as long.
 127
 128 When started, an added delay is optionally added, based on the
 129 spray-ramp variable. See it's documentation for details.
 130
 131 The accent location is chosen as the nth character in a word, depending
 132 on its length, based on the following table
 133 | length | accent position |
 134 |      1 |               1 |
 135 |    2-5 |               2 |
 136 |    6-9 |               3 |
 137 |  10-13 |               4 |
 138 |    14+ |               5 |
 139
 140
 141 ** Contributions are welcome!
 142
 143 There's lots of features and enhancements to do. The algorithm and interface could certainly be improved in various ways.