Org-Drill

Org-Drill uses the spaced repetition algorithm in org-learn to conduct interactive "drill sessions", using org files as sources of facts to be memorised. The material to be remembered is presented to the student in random order. The student rates his or her recall of each item, and this information is fed back to org-learn to schedule the item for later revision.

Each drill session can be restricted to topics in the current buffer (default), one or several files, all agenda files, or a subtree. A single topic can also be drilled.

Different "topic types" can be defined, which present their information to the student in different ways.

For more on the spaced repetition algorithm, and examples of other programs that use it, see:

• SuperMemo (the SM5 algorithm is discussed here)
• Anki
• Mnemosyne

Put the following in your .emacs. You will also need to make sure that Org's "contrib/lisp" directory is in the emacs load-path.

(require 'org-drill)

I also recommend the following, so that items are always eventually retested, even when you remember them well.

(setq org-learn-always-reschedule t)

If you want cloze-deleted text to show up in a special font within Org mode buffers, also add:

(setq org-drill-use-visible-cloze-face-p t)

Org-Drill supports two different spaced repetition algorithms – SM5 (the default, implemented by org-learn) and SM2. SM2 is an earlier algorithm which remains very popular – Anki and Mnemosyne, two of the most popular spaced repetition programs, use SM2.

If you want Org-Drill to use the SM2 algorithm, put the following in your .emacs:

(setq org-drill-spaced-repetition-algorithm 'sm2)

The intervals generated by the SM2 and SM5 algorithms are pretty deterministic. If you tend to add items in large, infrequent batches, the lack of variation in interval scheduling can lead to the problem of "lumpiness" -- one day a large batch of items are due for review, the next there is almost nothing, a few days later another big pile of items is due.

This problem can be ameliorated by adding some random "noise" to the interval scheduling algorithm. The author of SuperMemo actually recommends this approach for the SM5 algorithm, and Org-Drill's implementation uses his code.

To enable random "noise" for item intervals, set the variable org-drill-add-random-noise-to-intervals-p to true by putting the following in your .emacs:

(setq org-drill-add-random-noise-to-intervals-p t)

Load the file spanish.org. Press M-x and run the function org-drill. Follow the prompts at the bottom of the screen.

When the drill finishes, you can look at spanish.org to get some idea of how drill topics are written.

Org-Drill uses org mode topics as 'drill items'. To be used as a drill item, the topic must have a tag that matches org-drill-question-tag. This is :drill: by default. Any other org topics will be ignored.

You don't need to schedule the topics initially. However org-drill will recognise items that have been scheduled previously with org-learn. Unscheduled items are considered to be 'new' and ready for memorisation.

How should 'drill topics' be structured? Any org topic is a legal drill topic – it will simply be shown with subheadings collapsed. After pressing a key, any hidden subheadings will be revealed, and you will be asked to rate your "recall" of the item.

This will be adequate for some items, but usually you will want to write items where you have more control over what information is hidden from the user for recall purposes.

* Item                                   :drill:
What is the capital city of Estonia?

** The Answer
Tallinn.

* Item                                   :drill:
The capital city of Estonia is [Tallinn].

Type 1 hypersensitivity reactions are mediated by [immunoglobulin E|molecule]
and [mast cells|cell type].

* Noun                                               :drill:
    :PROPERTIES:
    :DRILL_CARD_TYPE: twosided
    :END:

Translate this word.

** Spanish
la mujer

** English
the woman

** Example sentence
¿Quién fue esa mujer? 
Who was that woman?

* Noun                                               :drill:
    :PROPERTIES:
    :DRILL_CARD_TYPE: multisided
    :END:

Translate.

** Spanish
la mesa

** English
the table

** Picture
[[file:table.jpg][PICTURE]]

* Fact
The capital city of [New Zealand] is Wellington, which has a population of
about 400,000.

* Fact
The capital city of New Zealand is [Wellington], which has a population of
about 400,000.

* Fact
The capital city of New Zealand is Wellington, which has a population of
about [400,000].

* Fact
The capital city of [New Zealand] is Wellington, which is located in the
the South Island.

* Fact
The capital city of New Zealand is [Wellington], which is located in 
the South Island.

* Fact
The capital city of New Zealand is Wellington, which is located in 
[the South Island].

* Fact
  :PROPERTIES:
  :DRILL_CARD_TYPE: multicloze
  :END:

The capital city of [New Zealand] is [Wellington], which is located in 
[the South Island] and has a population of about [400,000].

Start a drill session with M-x org-drill. By default, this includes all non-hidden topics in the current buffer. org-drill takes an optional argument, SCOPE, which allows it to take drill items from other sources. Possible values for SCOPE are:

tree

The subtree starting with the entry at the cursor.

file

The current buffer, including both hidden and non-hidden items.

file-with-archives

The current buffer, and any archives associated with it.

agenda

All agenda files.

agenda-with-archives

All agenda files with any archive files associated with them.

(file1 file2 …)

A list of filenames. All files in the list will be scanned.

During a drill session, you will be presented with each item, then asked to rate your recall of it by pressing a key between 0 and 5. The meaning of these numbers is (taken from org-learn):

Quality	SuperMemo label	Meaning
0	NULL	You have forgotten this card completely.
1	BAD	Wrong answer.
2	FAIL	Barely correct, the interval was too long.
3	PASS	Correct answer, but with much effort.
4	GOOD	Correct answer, with a little thought.
5	BRIGHT	Correct answer, effortless.

You can press '?' at the prompt if you have trouble remembering what the numbers 0–5 signify. At any time you can press 'q' to finish the drill early (your progress will be saved), 's' to skip the current item without viewing the answer, or 'e' to finish the drill and jump to the current topic for editing (your progress up to that point will be saved).

From the Anki website, http://ichi2.net/anki/wiki/Leeches:

Leeches are cards that you keep on forgetting. Because they require so many reviews, they take up a lot more of your time than other cards.

Like Anki, Org-Drill defines leeches as cards that you have "failed" many times. The number of times an item must be failed before it is considered a leech is set by the variable org-drill-leech-failure-threshold (15 by default). When you fail to remember an item more than this many times, the item will be given the :leech: tag.

Leech items can be handled in one of three ways. You can choose how Org-Drill handles leeches by setting the variable org-drill-leech-method to one of the following values:

nil

Leech items are tagged with the leech tag, but otherwise treated the same as normal items.

skip

Leech items are not included in drill sessions.

warn

Leech items are still included in drill sessions, but a warning message is printed when each leech item is presented.

The best way to deal with a leech is either to delete it, or reformulate it so that it is easier to remember, for example by splitting it into more than one card.

See the SuperMemo website for more on leeches.

There are some situations, such as before an exam, where you will want to revise all of your cards regardless of when they are next due for review.

To do this, run a cram session with the org-drill-cram command (M-x org-drill-cram RET). This works the same as a normal drill session, except that all items are considered due for review unless you reviewed them within the last 12 hours (you can change the number of hours by customising the variable org-drill-cram-hours).

An innovative feature of the program SuperMemo is so-called "incremental reading". This refers to the ability to quickly and easily make drill items from selected portions of text as you read an article (a web page for example). See the SuperMemo website for more on incremental reading.

Much of the infrastructure for incremental reading is already provided by Org Mode, with the help of some other emacs packages. You can provide yourself with an incremental reading facility by using 'org-capture' alongside a package that allows you to browse web pages either in emacs (w3 or emacs-w3m) or in the external browser of your choice (org-protocol).

Another important component of incremental reading is the ability to save your exact place in a document, so you can read it incrementally rather than all at once. There is a large variety of bookmarking packages for emacs which provide advanced bookmarking functionality: see the Emacs Wiki for details. Bookmarking exact webpage locations in an external browser seems to be a bit more difficult. For Firefox, the Wired Marker addon works well.

An example of using Org-Drill for incremental reading is given below. First, and most importantly, we need to define a couple of org-capture templates for captured facts.

(setq org-capture-templates
       `(("u"
         "Task: Read this URL"
         entry
         (file+headline "tasks.org" "Articles To Read")
         ,(concat "* TODO Read article: '%:description'\nURL: %c\n\n")
         :empty-lines 1
         :immediate-finish t)

        ("w"
         "Capture web snippet"
         entry
         (file+headline "my-facts.org" "Inbox")
         ,(concat "* Fact: '%:description'        :"
                  (format "%s" org-drill-question-tag)
                  ":\n:PROPERTIES:\n:DATE_ADDED: %u\n:SOURCE_URL: %c\n:END:\n\n%i\n%?\n")
         :empty-lines 1
         :immediate-finish t)
        ;; ...other capture templates...
    ))

Using these templates and org-protocol, you can set up buttons in your web browser to:

• Create a task telling you to read the URL of the currently viewed webpage
• Turn a region of selected text on a webpage, into a new fact which is saved to whichever file and heading you nominate in the template. The fact will contain a timestamp, and a hyperlink back to the webpage where you created it.

For example, suppose you are reading the Wikipedia entry on tuberculosis here.

You read the following:

The classic symptoms of tuberculosis are a chronic cough with blood-tinged sputum, fever, night sweats, and weight loss. Infection of other organs causes a wide range of symptoms. Treatment is difficult and requires long courses of multiple antibiotics. Antibiotic resistance is a growing problem in (extensively) multi-drug-resistant tuberculosis. Prevention relies on screening programs and vaccination, usually with Bacillus Calmette-Guérin vaccine.

You decide you want to remember that "Bacillus Calmette-Guérin vaccine" is the name of the vaccine against tuberculosis. First, you select the `interesting' portion of the text with the mouse:

The classic symptoms of tuberculosis are a chronic cough with blood-tinged sputum, fever, night sweats, and weight loss. Infection of other organs causes a wide range of symptoms. Treatment is difficult and requires long courses of multiple antibiotics. Antibiotic resistance is a growing problem in (extensively) multi-drug-resistant tuberculosis. Prevention relies on screening programs and vaccination, usually with Bacillus Calmette-Guérin vaccine.

Then you press the button you created when setting up org-protocol, which is configured to activate the capture template "w: Capture web snippet". The selected text will be sent to Emacs, turned into a new fact using the template, and filed away for your later attention.

(Note that it might be more efficient to turn the entire paragraph into a drill item – since it contains several important facts – then split it up into multiple items when you edit it later in Emacs.)

Once you have had enough of reading the article, save your place, then go to your "fact" file in Emacs. You should see that each piece of text you selected has been turned into a drill item. Continuing the above example, you would see something like:

** Fact: 'Tuberculosis - Wikipedia, the Free Encyclopedia'        :drill:

Prevention relies on screening programs and vaccination, usually with Bacillus
Calmette-Guérin vaccine.

You need to edit this fact so it makes sense independent of its context, as that is how it will be presented to you in future. The easiest way to turn the text into a 'question' is by cloze deletion. All you need to do is surround the 'hidden' parts of the text with square brackets.

Prevention of tuberculosis relies on screening programs and vaccination,
usually with [Bacillus Calmette-Guérin vaccine].

You can of course define browser buttons that use several different "fact" templates, each of which might send its fact to a different file or subheading, or give it different tags or properties, for example.

• org-drill-question-tag should use a tag match string, rather than a single tag? Can use org-make-tag-matcher.
• perhaps take account of item priorities, showing high priority items first