Merge branch 'master' of github.com:rich-murphey/twidor

Author: rich-murphey

README.md

@@ -36,7 +36,7 @@ In the lesson shown on the right, the letter "m" is formed by the "SP" (space) a
 
 Twidor will optionally show a map of the two-button chords, when the menu item <kbd>View | Show chords</kbd> is selected.
 
-## View | Show Chords
+## View | Show chords
 
 When <kbd>View | Show chords</kbd> is selected, an expanded key-map is shown, containing 2-button chords.
 <img src="https://raw.githubusercontent.com/rich-murphey/twidor/master/web.assets/Twidor_chord_map.png" width="40%" align="right">
@@ -47,35 +47,39 @@ Let's consider typing the letter "m".
 
 The first button of the chord for "m" is small box labeled "m".  The position of the first button is relative to the array of small buttons.  This is the button under the ring finger, middle column.  On the twiddler, that button is labeled "g".
 
-The second button of the chord is the large box to the immediate right of the given small button, labeled "SP".  The location of the first button is relative to the array of large buttons.
-<img src="https://raw.githubusercontent.com/rich-murphey/twidor/master/web.assets/Twidor_screenshot.png" width="20%" align="right">
+<img src="https://raw.githubusercontent.com/rich-murphey/twidor/master/web.assets/Twidor_SCC_full.png" width="30%" align="right"> The second button of the chord is the large box to the immediate right, labeled "SP".  The location of the first button is relative to the array of large buttons: index figure, left column.
 
-Here are some of the two-button chords:
-* <kbd>g   + SP</kbd> sends "m".
+Here are some of the two-button chords on the left column of buttons:
 * <kbd>DEL + SP</kbd> sends "o".
 * <kbd>BS  + SP</kbd> sends "p".
-* <kbd>f   + SP</kbd> sends "l".
+* <kbd>NL  + SP</kbd> sends "q".
 
+## View | Show multiple character chords
 
+Some chords send more than one letter, such as "ed" and "ing".  They are called multiple character chords (MCCs).  Twidor does not show MCCs by default. By default Twidor shows red highlights only for single letters, as shown for the highlighted letter "d", above in "Keyboard Layout".  Lyons [2,3] has shown that, at the beginning, learning is faster when the incremental amount of learning material smaller.
 
-## Multiple Character Chords (MCCs)
+When <kbd>View | Show multiple character chords</kbd> is selected. Twidor shows hints for chords such as "ed" and "ing" (MCCs).
 
-<img src="https://raw.githubusercontent.com/rich-murphey/twidor/master/web.assets/Twidor_MCC.png" width="30%" align="right"> Some chords send more than one letter, such as "is", "in" and "it" in the key-map above. These are called multiple character chords (MCCs). 
+<img src="https://raw.githubusercontent.com/rich-murphey/twidor/master/web.assets/Twidor_MCC.png" width="30%" align="right"> For example, given the text "ed", shown on the right. Twidor highlights the chord that sends "ed", rather than just "e".  Note that this is different from the keymap shown above in "The Keyboard Layout", where the option was not selected by default, and only "e" is highlighted.
 
-Twidor can optionally show hints for multiple character chords if you enable it.  However, by default Twidor shows green highlights only for chords that send a single character, as shown for the highlighted letter "d", above.  This is intended to make learning easier initially.
+If you wish to learn all available chords, select this option.  Twidor will show red highlighted buttons for the longest possible chorrd that matches the lesson text.  For example, given the text, "the", Twidor will highlight the chord that sends "the", rather than "th" or "t".
 
-If you wish to learn all available chords, un-check the box <kbd>View | Hint single letters only</kbd>.
-This will show green highlighted  buttons for the longest matching multiple character chord.
-For example, given the text, "the", Twidor will highlight the chord that sends "the", rather than "th" or "t".
-
-Note that this affects only the green highlighted "hints".  Regardless, the Twiddler can send MCCs, and Twidor accepts input MCCs.
+Note that this option affects only the red highlighted "hints".  Regardless, the Twiddler can send MCCs, and Twidor accepts input MCCs.
 
 ## Alternate Keymaps
 
-By default, Twidor loads the the
-[Backspice layout](https://raw.githubusercontent.com/AlexBravo/Twiddler/master/Backspice2%20cheat%20sheet.txt).
-Users may select the Default, TabSpace, or Typemax layouts in the <kbd>Keymaps</kbd> menu, or may load a custom key-map generated by the 
-the [Twiddler Tuner](https://twiddler.tekgear.com/tuner/edit.xhtml).
+By default, Twidor loads the the default keymap that comes factory installed on a new Twiddler.  
+
+There are a number of keymaps that have become popular over the years since the Twiddler was first introduced.  A few of these are bundled with Twidor. Users may select the Backspice, Default, TabSpace, or Typemax layouts in the <kbd>Keymaps</kbd> menu.
+
+Arbitrary keymap files can be loaded by the user. To load a custom key-map, export it from the 
+the [Twiddler Tuner](https://twiddler.tekgear.com/tuner/edit.xhtml) and load it as follows:
+* open https://twiddler.tekgear.com/tuner/edit.xhtml,
+* import a keymap.cfg if not already present there.
+* select 'Edit Configuration' for a given configuration file,
+* with the configuration file open, select Export, and then CSV.
+* download the CSV file.
+* In Twidor, select <kbd>File | Load Keymap</kbd> and select the CSV file.
 
 ## Other Usage
 
@@ -92,15 +96,6 @@ Menu options include:
 * <kbd>View | Highlight...</kbd> toggles show/hide which keys to press to send the next letter of the lesson.
 * <kbd>Keymaps</kbd> loads certain key-maps: Backspice, Default_V5, TabSpace, or Typemax.
 
-To load a custom key-map, users may:
-
-* open https://twiddler.tekgear.com/tuner/edit.xhtml,
-* import a keymap.cfg if not already present there.
-* select 'Edit Configuration' for a given configuration file,
-* with the configuration file open, select Export, and then CSV.
-* download the CSV file.
-* In Twidor, select <kbd>File | Load Keymap</kbd> and select the CSV file.
-
 ## How to Install
 
 Download the releases from here:
@@ -126,12 +121,13 @@ welcome [here](https://github.com/rich-murphey/twidor/issues).
 
 * Key-Map labels are shortened to the first three letters, which is currently sufficient for all of the popular key-maps.
 * The visual key-map does not show the mouse buttons.
+* Lessons 1-7 are tailored to the Deafult key-map. Specifically, lesson one uses only single button keys of the Default key-map.  Other key-maps will require chords in lesson one.
 
 ## How to Build
 
-To compile and build Twidor.jar, one may use:
+To compile and build Twidor.jar and the debian package (.deb), one may use:
 
-    sudo apt install git openjdk-8-jdk ant make
+    sudo apt install git openjdk-8-jdk ant make fakeroot
     git clone https://github.com/rich-murphey/twidor.git
     cd twidor
     make