Skip to content
/ spray Public
forked from zk-phi/spray

[Emacs] an elisp implementation of OpenSpritz

License

Notifications You must be signed in to change notification settings

oscarfv/spray

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

53 Commits
 
 
 
 
 
 
 
 

Repository files navigation

spray.el

A speed reading mode for Emacs.

The algorithm is inspired from OpenSpritz.

Screencast

screencast.gif

The story continues at gnu.org

Installation

Put spray.el into a “load-path”ed directory, and load it in your init file.

(require 'spray)

Then you can start spraying from the cursor position with M-x spray-mode. Binding some keys may also be useful.

(global-set-key (kbd "<f6>") 'spray-mode)

Commands

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

Customization

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

Similar emacs package: speedread

Available in marmalade or github It has several nice features and does not align on an accent character. Eventually I’d like to merge the two packages.

Deficiencies in similar projects which spray.el solves:

Mostly as of June 28, 2014.

For all other projects:

  • 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.
  • No keybinds. This is especially useful for common, quickly used functionality like pause and back up.

Specific projects:

  • speed-readerff firefox extension.
  • squirt javascript bookmarklet.
  • OpenSpritz javascript bookmarklet.
    • Very difficult selecting where to start / what exactly to read.
    • Very difficult to figure out where you are within a document.
  • spray website you paste text into.
    • Very difficult to figure out where you are within a document.
  • spread0r Perl program.
    • No apparent way to resize text.
    • Very difficult to figure out where you are within a document.
  • sprits-it website or bookmarklet. Looks most promising of the web based projects.
    • Very difficult selecting where to start / what exactly to read.
    • Somewhat difficult to figure out where you are in a document.

Programs that I, Ian Kelling, didn’t try, and why. They also probably have a lot of the problems listed above.

Downsides compared to similar projects:

  • The emacs learning curve.
  • Would be hard to get running on a phone.

Algorithm details

Main algorithm code location

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.

Algorithm translated from code to english

Words are split at space, tab, newline, and emdash characters. If any of the characters .!?; appear at the end of the word, a blank word is appended to the current word.

Each word is displayed for (60 / the choosen wpm) seconds, except if the word ends with ,:— or is greater than 9 characters long, in which case it is displayed for twice as long.

When started, an added delay is optionally added, based on the spray-ramp variable. See it’s documentation for details.

The accent location is chosen as the nth character in a word, depending on its length, based on the following table

lengthaccent position
11
2-52
6-93
10-134
14+5

Why?

Based on a quick count, similar programs are implemented in 6 languages, 9 platforms and 11+ projects. Every one has a similar algorithm to choose a word, an accent character and an interval to display it. How to do that best is quite important. However, how each project does it is generally buried in unrelated code, and mostly undocumented. It is prohibitively time consuming to figure out the algorithm and differences between them for each project. This sucks. Users would like to know so they can pick one. Developers would like to know so they can get ideas and spread improvements among different projects.

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. This section is an example.

Contributions are welcome!

There’s lots of features and enhancements to do. The algorithm and interface could certainly be improved in various ways.

About

[Emacs] an elisp implementation of OpenSpritz

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published