minor doc update

[spray] / Readme.org

diff --git a/Readme.org b/Readme.org
index b4b78db26cabedda8b104327bd223f0c812c961e..fe159426fcd29bfcf6ae76ec8be84a11a74ef9c7 100644 (file)
--- a/Readme.org
+++ b/Readme.org
@@ -6,6 +6,8 @@ The algorithm is inspired from [[https://github.com/Miserlou/OpenSpritz][OpenSpr
 
 ** 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.
@@ -94,4 +96,32 @@ You may customize spray by modifying following items:
 - [Face] spray-base-face
 - [Face] spray-accent-face
 
+** Algorithm details
+
+*** Why?
+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.
+
+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.
+
+*** Algorithm code location
+This project's implementation is located in ./spray.el
+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.
+
+*** Algorithm translated from code to english
+
+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.
+
+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.
+
+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 |
+|    6-9 |               3 |
+|  10-13 |               4 |
+|    14+ |               5 |
+  
+
+** Contributions are welcome!
 
+There's lots of features and enhancements to do. The algorithm and interface could certainly be improved in various ways.