Merge pull request #99 from dakra/tests-refactoring

66 Improve Testing, Refactoring and Documentation

Author: lordnik22

README.md

@@ -34,26 +34,44 @@ happens automatically, the clock starts on the first character typed and ends
 with the last. Statistics like characters typed, words-per-minute, and total
 time will be shown as soon as the last character is entered.
 
-You can use any buffer or part of it to run speed-type. `M-x speed-type-region`
-and `M-x speed-type-buffer` will do the same thing as speed-type-text, except they
-take the text sample you've picked.
-This works for programming code buffers/regions as well.
+Random samples are taken from [Project Gutenberg](https://www.gutenberg.org/).
+A small number of books will be downloaded on demand and stored in
+`~/emacs.d/speed-type`. They will only be downloaded once.
+
+You can configure a language (var `speed-type-default-lang`) which
+will pick books of this language. Beaware that gutenberg does not have
+hundreds of books for all supported languages.
 
-`speed-type-buffer` by default will only take a random portion of the buffer - If
-you want the whole buffer, use `C-u speed-type-buffer`.
+If you'd like to type a book from start to finish while saving your
+progress you can set `speed-type-randomize` to `nil`.
+
+You can use any buffer or part of it to run speed-type. `M-x speed-type-region` and `M-x speed-type-buffer` will do the same thing
+as `speed-type-text`, except they take the text sample you've picked.
+This works for programming code buffers/regions as well.
 
-Random samples are taken from Project Gutenberg. A small number of books will be
-downloaded on demand and stored in "~/emacs.d/speed-type". They will only be
-downloaded once.
+`speed-type-buffer` by default will only take a random portion of the
+buffer - If you want the whole buffer, use `C-u speed-type-buffer`.
+You can also call `speed-type-buffer-top-x` which will calculate a
+frequency list of the current buffer and assemble text from the top
+words.
 
 `speed-type-region` will start a speed-type session with the text from
 the selected region.
 
 `speed-type-top-x` (or -100/-1000) lets you practice the top X words
-for the selected language.
+for the selected language. If your language isn't supported by this
+command you can try using `speed-type-text-top-x` (setting
+var `speed-type-default-lang` beforehand). Which will calculate a
+frequency list of a gutenberg book.
 
-`speed-type-quote` by default will take a random quote from a random quote-url listed in `speed-type-quote-urls`. You can `C-u speed-type-quote` to specify the url.
+`speed-type-quote` by default will take a random quote from a random
+quote-url listed in `speed-type-quote-urls`. You can `C-u
+speed-type-quote` to specify the url.
 
+`speed-type-pandoc` will prompt you for a URL (e.g. wikipedia) which
+will be downloaded. The contents will be used for setting up the text
+to type. `speed-type-pandoc-top-x` is also included and works similar
+to the other top-x-commands.
 
 ## Contribution
 
@@ -126,3 +144,116 @@ included.
 [melpa-stable-link]: https://stable.melpa.org/#/speed-type
 [melpa-badge]: https://melpa.org/packages/speed-type-badge.svg
 [melpa-stable-badge]: https://stable.melpa.org/packages/speed-type-badge.svg
+
+## Documentation
+A little diagram because [uniline](https://github.com/tbanel/uniline) is fun:
+```uniline
+                          ╭────╮   ╭─────╮         ╭────────────╮
+                          │undo│   │pause│         │median stats│
+                          ╰┬──┬╯   ╰┬───┬╯         ╰┬─────────┬─╯
+                           △  │     △   │   display △         │
+                           │  │     │   │           │         │
+                           │  ▽     │   ▽ resume    │         ▽
+  ╭─────╮   ╭─────╮       ╭┴──┴─────┴───┴────╮    ╭─┴─────────┴─╮     ╭────╮
+  │start├──▷┤setup├──────▷┤speed-type session├───▷┤complete/menu├────▷┤quit│
+  ╰─────╯   ╰─┬───╯       ╰──────────────────╯    ╰──────┬──────╯     ╰────╯
+              △                                          │
+              │                                          ▽
+              │                            ╭─────────────┴──────╮
+              ╰────────────────────────────┤replay/next/continue│
+                                           ╰────────────────────╯
+```
+
+
+### Start
+The flow is started by calling one of the autoloaded commands:
+- `speed-type-text`
+- `speed-type-text-top-x`
+- `speed-type-top-x`
+- `speed-type-top-100`
+- `speed-type-top-1000`
+- `speed-type-buffer`
+- `speed-type-buffer-top-x`
+- `speed-type-region`
+- `speed-type-quotes`
+- `speed-type-pandoc`
+- `speed-type-pandoc-top-x`
+- `speed-type-continue`
+
+### Setup
+
+Every speed-type buffer is created via the function
+`speed-type--setup`. This is a large, configurable function with many
+optional parameters that define how the flow should behave. Through
+these parameters you can control which buffer-local variables are
+initialized, which menu entries appear, and how new words are
+inserted. It also connects the various speed-type buffers and
+initializes all buffer-local variables required for a consistent
+typing session. In short, `speed-type--setup` is the blueprint for
+every typing session.
+
+#### Buffers:
+- `speed-type-buffer`: The buffer in which typing takes places
+- `speed-type-content-buffer`: Contains the original content from which the flow was started. It's used for adding words and "continue" the content.
+- `speed-type-preview-buffer`: Buffer which "records" typed characters and "unusual" point movement
+
+
+### Speed-type session
+
+This phase is the core of speed-type. While a typing session is
+active, hooks and timers run continuously. With every keystroke, the
+user's input is compared to the buffer contents. Based on the
+difference (match vs. mismatch), various buffer-local variables are
+updated, and characters update their status and color accordingly.
+
+Performance is crucial in this phase: hooks must remain lightweight so
+that typing remains responsive and the user is not restricted in how
+they move or what commands they use to complete the session.
+
+#### Hooks:
+- first-change-hook: Used to start the timer
+- before-change-functions: Used to store characters which are going be compared against.
+- after-change-functions: Used to compare the inserted characters with the actual characters
+
+#### Overlay and Faces:
+To color the characters a overlay is used:
+- speed-type-correct-face
+- speed-type-error-face
+- speed-type-consecutive-error-face
+
+#### Text Properties:
+- speed-type-orig-pos: Used for "continue" and add new words
+  - car: start
+  - cdr: end
+- speed-type-char-status: Used to ignore characters and determine complete
+  - ignore
+  - correct
+  - error
+
+### Completion and Menu
+
+A typing session is considered complete when every character in the
+buffer has a `speed-type-char-status` property. Once all characters
+have such a value, completion is triggered.
+
+At this point, the `speed-type-buffer` becomes read-only and only the
+menu-control keys remain active.
+
+### Replay / Continue / Next
+
+These actions are available from the menu. Based on the key the user
+presses, the corresponding action is invoked. The actions are
+processed in a similar way how a speed-type session was started. The
+action calls `speed-type--setup` with mostly the same parameters
+again, which starts a new session.
+
+After setup is complete it kills the completed `speed-type-buffer` and
+`speed-type-preview-buffer`. It may reuse the existing content-buffer.
+
+### Median Stats
+Calculates and displays the median stats of various buffer-local vars
+from current and previous speed-type sessions.
+
+### Quit
+Kills the `speed-type-buffer` and all related buffers (content-buffer,
+preview-buffer, etc.).