Common Lisp Kanji Drill (CLKD) is a learning tool designed to assist someone who is interested in memorizing the English meanings of hundreds or thousands of Kanji: Chinese/Japanese characters. CLKD is based on a drill paradigm. Learning is based on completing tests which require the meaning to be typed next to each character, and then reviewing the results when the test is graded by the computer.
Thanks to Jim Breen's fabulous Kanjidic project, without which CLKD would not be possible, the program is equipped with a dictionary of more than 6000 Kanji characters. At any given moment, CLKD is in some kind of testing mode, whereby it is working with a deck: a subset of all of these characters that is selected by the student for testing. This deck might be visualized as a deck of cards with each card bearing a unique character. To shuffle a deck means to scramble its order randomly, exactly like shuffling paper cards. CLKD can generate tests of a given size (number of questions) by drawing that many kanji from the currently configured deck. When generating a new test, CLKD can be configured to return all Kanji to the deck and shuffle them, or it can be configured to keep drawing cards when the deck is exhausted. When a deck is exhausted, CLKD can simply repeat that deck in the same order (just like turning over a discard pile in a card game) or it can shuffle. Shuffling is always performed when switching to a different deck (different subset of the 6000+ kanji).
After a test is submitted, it is graded. At this point, the student can generate a brand new test, or request to be retested. Re-testing means that all of the kanji for which the student gave incorrect answers are compiled into a new test (without being shuffled). The results of that test can also be retested, and so the student can iteratively keep retesting and reviewing until no more wrong answers remain. At that point, it is no longer possible to request a retest; only a new test can be generated. Iterative retesting has proven to the author to be a powerful learning strategy.
CLKD is a single-user application. It very much has a concept of session and state, but if multiple browser connections are made to its port, it does not treat them as distinct sessions. The session state is maintained in memory within the clkd process. If that process is terminated, the state is lost.
However, by explicit request, the state can be recorded to a file on disk, which is stored in the the .clkd/ subdirectory relative to the user's home directory. The state can be restored from this file at any time. Only one file is used, so whenever state is saved, it overwrites any previously saved state.
The state includes almost everything: the selected test deck, the values of all of the UI controls, and even the complete results of the last test.
This means that if the student is interrupted, and must stop the session, and perhaps even log out and shut down the computer, he or she can save the state at that point and continue later. The ability to do this is very important when, for instance, the student is working through a 1500-kanji deck in batches of 100, and has 800 remaining.
The state also includes the student's response history: information associated with every kanji for which the student has given one or more answers. Persisting the response history in a file is important, because it allows CLKD to deduce which characters are giving trouble to the student. These can be treated as a special deck.
CLKD provides the student with two basic ways to choose what Kanji to be tested on. Kanji can be selected using a frequency index range or a stroke count index range. Both of these methods are based on data provided by Kanjidic.
The frequency index assigns a ranking to each character based on how frequently it is believed to appear in Japanese print, such as newspapers and magazines. The most frequent character is assigned rank 1, the next most frequent 2 and so on. CLKD can be instructed to select a given frequency range for testing. For instance the range 1 through 1000 means to test the one thousand most frequently printed characters. The range 1001 through 1100 chooses the next one hundred most frequent after the first thousand.
The stroke count index works similarly to the frequency index, except that the kanji are arranged in order of ascending stroke count. The purpose of including this selection method in CLKD along with selection by frequency is that there are certain simple kanji which do not appear in print frequently enough to be covered in the lower regions of the frequency index. Yet, the student should know these kanji, because they are etymologically important and serve as components of other kanji, thereby reinforcing the learning of other kanji.
In addition to the frequency and stroke count indexed decks, CLKD offers the student two types of special decks. Special decks work slightly differently from indexed decks in the sense that they are not subject to shuffling. Each test created from these decks simply keeps drawing kanji. When the special deck is exhausted, it is repeated in the same order.
The content of the special decks depends on the student's response history. When CLKD is first started (and no previously saved state is restored from disk), the response history is empty, and so the special decks are empty, and therefore unavailable for selection.
The deck of problematic kanji consists of those kanji for which the student has been giving incorrect answers more frequently than correct answers. The program looks at as many as twenty of the most recently given answers for every kanji in the dictionary. If more than 50% of the answers were wrong, that kanji is considered to be a problem kanji and is included in the problem deck. The status of each tested kanji is re-evaluated after every test, and so kanji which cease to meet the criteria are removed from the problem deck.
The deck of confused kanji is also based on the student's response history. When the student is being tested using a given deck and gives an incorrect answer, it is possible that the student is actually thinking of another kanji which is structurally similar to the one which is misidentified. The incorrect answer is actually the meaning of some other, similar kanji which is found in the same test deck. CLKD tries to deduce this automatically and incorporates the information into the student's response history.
The deck of confused kanji is specially ordered so that when tests are drawn from it, the groups of two or more kanji which are confused for one another appear together. This is the key to why this feature is powerful in reinforcing learning. By seeing these kanji together, the student recognizes the confusion, and unravels it by memorizing the structural differences which distinguish the kanji.
The status of confused kanji is more persistent than that of trouble kanji. It takes many correct answers before a confused kanji is declassified from its designation as confused.
CLKD's user interface consists of only two forms: a main form, and a test form. By making use of only two forms, CLKD minimizes the number of forms through which the student must navigate to complete a test-and-evaluate cycle. For this reason, the main form contains both the configuration control, and a section which shows the results.
The first section of the main form is filled with controls which configure what deck is to be used for the next test, the rules for when to reshuffle, the index ranges, how strictly answers must match dictionary entries to be considered correct, and how large of a font to use in displaying the kanji. The exact content of this form depends on the type of deck. For instance if the student wants to be tested on problem kanji or confused kanji, then the input fields for typing in the index range are not shown, since they are not applicable to that type of deck.
Note: some of the list controls are configured to cause the browser to submit the form when their values are changed. The state of CLKD is updated, and the form is re-generated.
Kanji remaining in current deck The very top element in the parameter section form is a read-only status field which shows how many undrawn kanji remain in the current deck. When a new deck is selected (for instance a different frequency range is typed in), this value is reset to zero. This means that the deck is empty; it will be compiled according to the given parameters when the next test is generated. Thus for instance if the student picks kanji by frequency range, selecting 1 through 1000, and then goes through a test of 75 kanji, returning to the main form to view the test results, this field will show that 925 kanji now remain: a thousand less seventy-five.
Number of questions This is a numeric input field for configuring the number of kanji to include in the next test that is generated. This value does not affect the Retest action; the kanji included in a retest are precisely those for which incorrect or blank answers were given in the most recent test. In the frequency or stroke count modes, a generated test always contains as many questions as are configured. If the deck is emptied during the generation of the test, it is rolled over according to the setting of the Reshuffle parameter, and questions continue to be generated. If the deck from which kanji are drawn is smaller than the test size, the test will contain duplicate kanji. Each duplicate is separately evaluated, but both answers contribute to the history for that kanji. In the problematic kanji and confused kanji testing modes, a test may be generated with fewer questions than requested, since the deck does not roll over during test generation. This behavior prevents unwanted duplicates, when the number of kanji in these categories is smaller than the typical test size.
Match strictness The match strictness control determines how strictly CLKD evaluates the given answers. Each kanji has one or more entries in the dictionary. The whole entry is the strictest match. It means that the answer must exactly match one of the English entries for that character, in its entirety. If the entry is "minute of time", then the only acceptable answer is "minute of time". The words in entry setting requests an intermediate strictness. The answer must match either an entire entry or part of an entry consisting of whole words. Continuing with the same "minute of time" example, acceptable answers are now "minute of time", "minute of", "of time", "minute", "of" and "time". Note that the connective word "of" is not eliminated. Finally, the characters in entry matching strictness mode means that a non-empty answer which matches any range of charaters in a dictionary entry is acceptable. The answers "min" or "ime" both match "minute of time". These two less strict modes improve the learning time for unfamiliar dictionary entries. Once a student learns that the meaning of a certain character is "minute", the next step of remembering the exact dictionary entry "minute of time" is easier.
The matching is always performed in a case-sensitive manner.
Some Kanjidic entries contain parenthesized material. CLKD removes this parenthesized material. So for instance if the dictionary entry is "counter for chapters (of a book)" then at the whole entry strictness setting, the only answer which matches this entry is "counter for chapters". CLKD still displays the entire entry, however. The abridged version is used only internally for matching.
What to test This parameter determines what kanji are selected for testing, and influences how test generation is performed. Note that changing the value of this parameter has an instant effect. If the current mode is by frequency range or by stroke count, and a change is made to any of the other modes, the current deck is discarded.
Lowest kanji index This is a numeric input field which is only shown in the frequency range and stroke count modes, used for specifying the lowest kanji of the tested range. See the Basic Concepts section.
Highest kanji index This is a numeric input field which is only shown in the frequency range and stroke count modes, used for specifying the highest kanji of the tested range. See the explanation in the Basic Concepts section.
Reshuffle This list box control determines the rules for when the deck of tested kanji is shuffled. These rules only apply to the stroke count and frequency modes. The deck of problematic or confused kanji is never shuffled. The on range or sort order change mode selects the minimum amount of shuffling. This means that the deck is shuffled only when the order is changed from frequency to stroke count or vice versa, or when the numeric range is changed. The deck is always shuffled under those circumstances. If the when turning over deck choice is selected, then the deck is also shuffled whenever it turns over&emdash;in other words, when it is exhausted. If this is not enabled, then when the entire deck is tested, it is restored to its original order, so that the kanji are then drawn for testing in the same order as before. If the before each new test choice is selected, then before each new test is generated, the previously tested kanji are returned to the deck and it is reshuffled.
The next section of the main form contains two list box controls which affect the content and visual presentation of the main form.
Result detail level This control determines how much of the results of the previous test are shown in the results section of the main form. Regardless of the state of this control, the results section is not shown at all if no test has been taken yet. If a test has been taken, then the heading for that form section is always shown, indicating the test score. The control affects what is shown below the heading. The value full shows the full test results. This means that the correct as well as incorrect answers are shown along with each kanji, and all of its dictionary entries. For each incorrect answer, the entire row is highlighted in red. The value wrong only shows only the wrong answers. They are still highlighted in red, resulting in a condensed, but all-red display. The value score only means that the detailed test results are hidden. No kanji and no dictionary entries are displayed, only the section heading with the score.
Kanji size The kanji size control determines how large the kanji characters appear. This affects their appearance only in the result section of the main form and in the test form. It does not affect their size elsewhere, such as in tooltips. To change the size of kanji in CLKD's tooltips, it's necessary to fiddle with CLKD's cascading style sheet. Changing the kanji size has an immediate effect, which can be seen if detailed test results are currently showing.
Action buttons are provided for generating tests and managing the persistence of session state.
Save State This button saves the state of the program to a file in the user's home directory. When the button is pressed, CLKD immediately begins saving the state without asking for confirmation. The previous file will be overwritten. The file is quite large, and it may take some time to generate. When it is finished, a result page is shown indicating whether the operation was successful. The pathname of the save file is shown in this page.
The saved state includes: the response history; the results of the last test; the values of all of the UI controls in both the Test Parameters and Display Options section; and the currently active deck.
Restore State This button restores the state that was most recently saved with the Save State button. When the button is pressed, CLKD immediately begins loading the saved state. When it is finished, a result page is shown indicating whether the operation was successful. The pathname of the save file from which the state was restored is shown in this page.
New Test This button generates a new test, based on the currently configured Test Parameters. The browser navigates to the Test Form, described later in this User Guide.
Retest Wrongs This button appears whenever a test is submitted that achieves an imperfect score due to incorrect or blank answers. When it is pressed, a new, test is generated which consists only of the kanji that the student did not get right. (If the student didn't get any answers, this test is identical to the previous one, otherwise it is smaller). Each test is independent of the previous: each submission contributes separately to the response history for each affected kanji.
The result section comprises the remainder of the main form. It can be quite large if large tests are taken, and the full results are shown. This section is only visible after a test is taken, or a saved session is restored in which a test had been taken.
The section heading shows the overall score expressed as a fraction of correct answers out of the total number of questions.
Below the heading is a table with three columns. The kanji on the left, the student's answers for those kanji in the middle column, and the dictionary entries for each kanji in the wide column. For each kanji for which an incorrect or blank answer was given, the entire table row is highlighted with a red background.
The results have a special feature. When the mouse cursor is hovered over any of the student's incorrect answers, a tooltip may appear which shows one or more kanji. This will happen if the student's incorrect answer happens to match some other kanji (in the deck from which the test was drawn, not the entire dictionary!) This data is recorded as part of the response history for the kanji, and serves as the basis for generating the Confused Kanji deck. (In generating the Confused Kanji deck, additional smart filtering is applied to the data which is not applied in the selection of kanji for these tooltips).
The test form is shown as a separate page when the student clicks the one of the New Test or Retest Wrongs buttons. In this form, the tested kanji are shown, each with an input field to the right of it, aligned with the bottom of the kanji.
The student enters as many answers as he or she knows into these input fields. The tab key can be used to efficiently move from one field to the next, in left-to-right, top-to-bottom sequence. At any time, the Enter key can be used to submit the test, or the Check Responses button at the bottom of the test form can be used to do the same.
If the test was generated by the Retest Wrongs button, then the previously given answers for each kanji shown above the input field, surrounded by double quotes. The same kanji tooltips are active over these incorrect answers as in the results section of the main form. These features encourage a form of ``beneficial cheating'' on re-taken tests, for the sake of improved learning.