org-drill.el – flashcards and spaced repetition for org-mode

Org-Drill is an extension for Org mode. Org-Drill uses a spaced repetition algorithm to conduct interactive "drill sessions", using org files as sources of facts to be memorised. Each topic is treated as a "flash card". 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 used 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

Org-Drill has its own repository, at:

https://gitlab.com/phillord/org-drill/

It's also available in MELPA.

Org-drill is no longer included in the Org mode repository.

Follow the instructions for setting up MELPA: https://melpa.org/#/getting-started

Then use M-x list-packages and choose to install org-drill.

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

Drill items can have other drill items as children. When a drill item is being tested, the contents of any child drill items will be hidden.

You don't need to schedule the topics initially. 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 that 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:

• No description for this link
• No description for this link
• No description for this link
• No description for this link

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.

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. See below for details.

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

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 up to that point will be saved), 's' to skip the current item without viewing the answer, or 'e' to escape from the drill and jump to the current topic for editing (again, your progress up to that point will be saved).

After exiting the drill session with e or q, you can resume where you left off, using the command org-drill-resume. This will return you to the item that you were viewing when you left the session. For example, if you are shown an item and realise that it is poorly formulated, or contains an error, you can press e to leave the drill, then correct the item, then press M-x org-drill-resume and continue where you left off.

Note that 'drastic' edits, such as deleting or moving items, can sometimes cause Org-Drill to "lose its place" in the file, preventing it from successfully resuming the session. In that case you will need to start a new session.

Org-Drill has to scan your entire item database each time you start a new drill session. This can be slow if you have a large item collection. If you have a large number of 'due' items and want to run a second drill session after finishing one session, you can use the command org-drill-again to run a new drill session that draws from the pool of remaining due items that were not tested during the previous session, without re-scanning the item collection.

Also note that if you run org-drill-resume and you have actually finished the drill session, you will be asked whether you want to start another drill session without re-scanning (as if you had run org-drill-again).

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

If you keep all your items in a single file, it may eventually get very large. The file will be slow to load, and Emacs may have trouble syntax-highlighting the file contents correctly.

The easiest steps to solve this problem are:

1. Move your file into its own dedicated directory.
2. Divide the file into two or more smaller files.
3. Within each file, set org-drill-scope to 'directory'. See No description for this link above for instructions about how to do this.

Every drill item is automatically given a persistent unique "ID" the first time it is seen by Org-Drill. This means that if two different people subsequently edit or reschedule that item, Org-Drill can still tell that it is the same item. This in turn means that collections of items can be shared and edited in a collaborative manner.

There are two commands that are useful in this regard:

1. org-drill-strip-all-data - this command deletes all user-specific scheduling data from every item in the current collection. (It takes the same optional 'scope' argument as org-drill to define which items will be processed by the command). User-specific data includes scheduling dates, ease factors, number of failures and repetitions, and so on. All items are reset to 'new' status. This command is useful if you want to share your item collection with someone else.
2. org-drill-merge-buffers - When called from buffer A, it prompts you for another buffer (B), which must also be loaded into Emacs. This command imports all the user-specific scheduling data from buffer B into buffer A, and deletes any such information in A. Matching items are identified by their ID. Any items in B that do not exist in A are copied to A, in the same hierarchical location if all the parent headings exist, otherwise at the end of the buffer.

An example scenario:

Tim decides to learn Swedish using an item collection (.org file) made publically available by Jane. (Before publishing it Jane used 'org-drill-strip-all-data' to remove her personal scheduling data from the collection.) A few weeks later, Jane updates her collection, adding new items and revising some old ones. Tim downloads the new collection and imports his progress from his copy of the old collection, using 'org-drill-merge-buffers', using the new collection as buffer A and the old one as buffer B. He can then discard the old copy. Any items HE added to HIS copy of the old collection (buffer B) will not be lost – they will be appended to his copy of the new collection.

Of course the sharing does not need to be 'public'. You and a friend might be learning a language or some other topic together. You each maintain a card collection. Periodically your friend sends you a copy of their collection – you run org-drill-merge-buffers on it, always using your own collection as buffer B so that your own scheduling progress is carried over. Other times you send your friend a copy of your collection, and he or she follows the same procedure.

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 is written by Paul Sexton.