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 (see descriptions of the SM2, SM5 and SM8 algorithms)
• 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)

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 the value of 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 all subheadings collapsed, so thta only the material beneath the main item heading is visible. 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. For this reason, some other card types are defined, including:

• Two-sided cards
• Multi-sided cards
• Multicloze cards
• User-defined card types

A note about comments: In org mode, comment lines start with '#'. The rest of the line is ignored by Org (apart from some special cases). You may sometimes want to put material in comments which you do not want to see when you are being tested on the item. For this reason, comments are always rendered invisible while items are being tested.

* 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
PICTURE

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

The capital city of [New Zealand] is [Wellington], which is located in
the [North|North/South] Island and 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 has a population of
about [400,000].

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

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

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

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

The capital city of [New Zealand] is [Wellington], which is located in
the [North|North/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).

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).

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.

Org-Drill has several settings which you change using M-x customize-group org-drill <RET>. Alternatively you can change these settings by adding elisp code to your configuration file (.emacs).

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

(setq org-drill-hide-item-headings-p t)

(setq org-drill-maximum-items-per-session 40)
(setq org-drill-maximum-duration 30)   ; 30 minutes

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

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

(setq org-drill-adjust-intervals-for-early-and-late-repetitions-p t)

(setq org-drill-learn-fraction 0.45)   ; change the value as desired

# Local Variables:
# org-drill-maximum-items-per-session:    50
# org-drill-spaced-repetition-algorithm:  simple8
# End:

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.