update documentation
authorIan Kelling <ian@iankelling.org>
Tue, 7 Jul 2015 05:37:37 +0000 (22:37 -0700)
committerIan Kelling <ian@iankelling.org>
Tue, 7 Jul 2015 05:37:37 +0000 (22:37 -0700)
Readme.org

index c69d1c627b6d5907ee8082978d861ba3d837675c..d3f80082935b987689bc6559f59b057358628ef4 100644 (file)
@@ -67,17 +67,20 @@ Mailing list for any feedback, questions, etc: https://lists.iankelling.org/list
 
 ** Similar emacs package: speedread
 
-Available in marmalade or
-[[https://github.com/vapniks/speedread/blob/master/speedread.el][github]]
-It has several nice features and does not align on an accent character. Eventually I'd like to merge the two packages.
+Available in marmalade or [[https://github.com/vapniks/speedread/blob/master/speedread.el][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.
+- 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:
 - [[https://github.com/jbmartinez/speed-readerff][speed-readerff]] firefox extension.
@@ -116,13 +119,17 @@ In =./spray.el=, the functions =spray--word-at-point=, =spray--update= and =spra
 
 *** 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. 
+Words are split at space, tab, newline, and emdash characters.
 
-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.
+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.
+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
+The accent location is chosen as the nth character in a word, depending
+on its length, based on the following table
 | length | accent position |
 |      1 |               1 |
 |    2-5 |               2 |
@@ -130,11 +137,6 @@ The accent location is chosen as the nth character in a word, depending on its l
 |  10-13 |               4 |
 |    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!