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 ** Deficiencies in similar projects which spray.el solves:
   8
   9 Mostly as of June 28, 2014.
  10
  11 For all other projects:
  12 - It is very difficult to save your place and come back later. Emacs has lots of built in features like bookmarks or just making a note which make this easy.
  13 - No keybinds. This is especially useful for common, quickly used functionality like pause and back up.
  14
  15 Specific projects:
  16 - https://github.com/jbmartinez/speed-readerff firefox extension.
  17 - https://github.com/cameron/squirt javascript bookmarklet.
  18 - https://github.com/Miserlou/OpenSpritz javascript bookmarklet.
  19   - Very difficult selecting where to start / what exactly to read.
  20   - Very difficult to figure out where you are within a document.
  21
  22
  23 - https://github.com/chaimpeck/spray website you paste text into.
  24   - Very difficult to figure out where you are within a document.
  25
  26 - https://github.com/xypiie/spread0r Perl program.
  27   - No apparent way to resize text.
  28   - Very difficult to figure out where you are within a document.
  29
  30
  31 - https://github.com/the-happy-hippo/sprits-it website or bookmarklet. Looks most promising of the web based projects.
  32   - Very difficult selecting where to start / what exactly to read.
  33   - Somewhat difficult to figure out where you are in a document.
  34
  35
  36 Programs that I, Ian Kelling, didn't try, and why. They also probably have a lot of the problems listed above.
  37 - https://github.com/pasky/speedread No simple way to resize text from default of too small.
  38 - 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.
  39 - 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.
  40 - 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.
  41
  42
  43 Downsides compared to similar projects:
  44 - The emacs learning curve.
  45 - Would be hard to get running on a phone.
  46
  47
  48 ** Screencast
  49
  50 [[screencast.gif]]
  51
  52 ** Installation
  53
  54 Put spray.el into a "load-path"ed directory, and load it in your init
  55 file.
  56
  57 : (require 'spray)
  58
  59 Then you can start spraying from the cursor position with =M-x
  60 spray-mode=. Binding some keys may also be useful.
  61
  62 : (global-set-key (kbd "<f6>") 'spray-mode)
  63
  64 ** Commands
  65
  66 In spray-mode buffers, following commands are available.
  67
  68 - =spray-start/stop= (SPC) ::
  69      pause or resume spraying
  70
  71 - =spray-backward-word= (h, <left>) ::
  72      pause and back to the last word
  73
  74 - =spray-forward-word= (l, <right>) ::
  75      inverse of =spray-backward-word=
  76
  77 - =spray-faster= (f) ::
  78      increases speed
  79
  80 - =spray-slower= (s) ::
  81      decreases speed
  82
  83 - =spray-quit= (q, <return>) ::
  84      quit =spray-mode=
  85
  86
  87 ** Customization
  88
  89 You may customize spray by modifying following items:
  90
  91 - [Variable] spray-wpm
  92 - [Variable] spray-height
  93 - [Variable] spray-margin-top
  94 - [Variable] spray-margin-left
  95 - [Keymap] spray-mode-map
  96 - [Face] spray-base-face
  97 - [Face] spray-accent-face
  98
  99 ** Algorithm details
 100
 101 *** Why?
 102 Based on a quick count, similar programs are implemented in 6 languages, 9 platforms and 15+ projects. The core algorithm is choosing a word, an accent character and an interval to display it, and how to do that best is quite important. However, how exactly each project implements that algorithm is generally buried in unrelated code, and mostly undocumented.  It is extremely difficult and time consuming to figure out the exact algorithm and differences between them for each project, and I don't think it's hardly ever been done. This sucks. Users would like to know so they can pick one. Developers would like to know so that they can improve their implementation of the algorithm.
 103
 104 So, I am opening a bug on every project I find, asking them to document what file and function(s) their algorithm is implemented in, and preferably to document it in english as well. The following is an example.
 105
 106 *** Algorithm code location
 107 This project's implementation is located in ./spray.el
 108 The functions =spray--word-at-point=, =spray--update= and =spray-start= contain the main of the algorithm. Word splitting is also duplicated the same way as in those functions throughout ./spray.el.
 109
 110 *** Algorithm translated from code to english
 111
 112 Words are split at space, tab and newline characters, and if any of the characters =.!?;= appear in a word, a blank word is appended to the current word.
 113
 114 Each word is displayed for (60 / the choosen wpm) seconds, except if the word contains : or , or is greater than 9 characters long, in which case it is displayed for twice as long.
 115
 116 The accent location is chosen as the nth character in a word, depending on its length, based on the following table
 117 | length | accent position |
 118 |      1 |               1 |
 119 |    2-5 |               2 |
 120 |    6-9 |               3 |
 121 |  10-13 |               4 |
 122 |    14+ |               5 |
 123
 124
 125 ** Contributions are welcome!
 126
 127 There's lots of features and enhancements to do. The algorithm and interface could certainly be improved in various ways.