diff options
Diffstat (limited to 'README.org')
| -rw-r--r-- | README.org | 410 |
1 files changed, 410 insertions, 0 deletions
diff --git a/README.org b/README.org new file mode 100644 index 0000000..7faf0c2 --- /dev/null +++ b/README.org @@ -0,0 +1,410 @@ +# -*- mode: org; coding: utf-8 -*- +#+TITLE: Org-Drill +#+AUTHOR: Paul Sexton + +* Synopsis + + +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: +- [[http://supermemo.com/index.htm][SuperMemo]] (the SM5 algorithm is discussed [[http://www.supermemo.com/english/ol/sm5.htm][here]]) +- [[http://ichi2.net/anki/][Anki]] +- [[http://mnemosyne-proj.org/index.php][Mnemosyne]] + + +* Installation + + +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. + +#+BEGIN_SRC emacs-lisp +(require 'org-drill) +#+END_SRC + +I also recommend the following, so that items are always eventually retested, +even when you remember them very well. + +#+BEGIN_SRC emacs-lisp +(setq org-learn-always-reschedule t) +#+END_SRC + +If you want cloze-deleted text to show up in a special font within Org mode +buffers, also add: + +#+BEGIN_SRC emacs-lisp +(setq org-drill-use-visible-cloze-face-p t) +#+END_SRC + + +* Demonstration + + +Load the file [[file:spanish.org][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. + + +* Writing the questions + + +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. + +** Simple topics + +The simplest drill topic has no special structure. When such a topic is +presented during a drill session, any subheadings are "collapsed" with their +contents hidden. So, you could include the question as text beneath the main +heading, and the answer within a subheading. For example: + +#+BEGIN_EXAMPLE +* Item :drill: +What is the capital city of Estonia? + +** The Answer +Tallinn. +#+END_EXAMPLE + +When this item is presented for review, the text beneath the main heading will +be visible, but the contents of the subheading ("The Answer") will be hidden. + + +** Cloze deletion + +Cloze deletion can be used in any drill topic regardless of whether it is +otherwise 'simple', or one of the specialised topic types discussed below. To +use cloze deletion, part of the body of the topic is marked as /cloze text/ by +surrounding it with single square brackets, [like so]. When the topic is +presented for review, the text within square brackets will be obscured. The +text is then revealed after the user presses a key. For example: + +#+BEGIN_EXAMPLE +* Item :drill: +The capital city of Estonia is [Tallinn]. +#+END_EXAMPLE + +During review, the user will see: + +#+BEGIN_QUOTE +The capital city of Estonia is @<font style="background-color: blue;" color="blue"> +XXXXXXX@</font>. +#+END_QUOTE + +When the user presses a key, the text "Tallinn" will become visible. + + +** Two-sided cards + +The remaining topic types all use the topic property, =DRILL_CARD_TYPE=. This +property tells =org-drill= which function to use to present the topic during +review. If this property has the value =twosided= then the topic is treated as +a "two sided card". When a two sided card is reviewed, /one of the first two/ +subheadings within the topic will be visible -- all other +subheadings will be hidden. + +Two-sided cards are meant to emulate the type of flipcard where either side is +useful as test material (for example, a card with a word in a foreign language +on one side, and its translation on the other). + +A two sided card can have more than 2 subheadings, but all subheadings after +the first two are considered as "notes" and will always be hidden during topic +review. + +#+BEGIN_EXAMPLE +* 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? +#+END_EXAMPLE + +In this example, the user will be shown the main text -- "Translate this word" +-- and either 'la mujer', /or/ 'the woman', at random. The section 'Example +sentence' will never be shown until after the user presses a key, because it is +not one of the first two 'sides' of the topic. + + +** Multi-sided cards + +The =multisided= card type is similar to =twosided=, except that any +subheading has a chance of being presented during the topic review. One +subheading is always shown and all others are always hidden. + +#+BEGIN_EXAMPLE +* Noun :drill: + :PROPERTIES: + :DRILL_CARD_TYPE: multisided + :END: + +Translate. + +** Spanish +la mesa + +** English +the table + +** Picture +[[file:table.jpg][PICTURE]] +#+END_EXAMPLE + +The user will be shown the main text and either 'la mujer', /or/ 'the woman', +/or/ a picture of a table. + + +** User-defined topic types + +Finally, you can write your own elisp functions to define new kinds of +topics. Any new topic type will need to be added to +=org-drill-card-type-alist=, and cards using that topic type will need to have +it as the value of their =DRILL_CARD_TYPE= property. For an example, see the +function =org-drill-present-spanish-verb=, which defines the new topic type +=spanish_verb=, used in 'spanish.org'. + +See the file [[file:spanish.org][spanish.org]] for a full set of example material. + + +* Running the drill session + + +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=): + +- 0 :: Completely forgot. +- 1 :: Even after seeing the answer, it still took a bit to sink in. +- 2 :: After seeing the answer, you remembered it. +- 3 :: It took you awhile, but you finally remembered. +- 4 :: After a little bit of thought you remembered. +- 5 :: You remembered the item really easily. + +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), or 'e' to finish the drill and jump to the +current topic for editing (your progress up to that point will be saved). + + +* Leeches + + +From the Anki website, http://ichi2.net/anki/wiki/Leeches: + +#+BEGIN_QUOTE +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. +#+END_QUOTE + +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 [[http://www.supermemo.com/help/leech.htm][the SuperMemo website]] for more on leeches. + + +* Incremental reading + + +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 [[http://www.supermemo.com/help/read.htm][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 in emacs -- e.g. w3 or [[http://www.emacswiki.org/emacs/emacs-w3m][emacs-w3m]]. There is a +large variety of bookmarking packages for emacs which allow you to save your +place in webpages (another important component of incremental reading). See the +[[http://www.emacswiki.org/emacs/BookMarks][Emacs Wiki]] for details. + +An example of using Org-Drill for incremental reading is given below. First, +and most importantly, we need to define an =org-capture= template for captured +facts: + +#+BEGIN_SRC emacs-lisp +(setq org-capture-templates + `(("f" "Fact" entry + (file+headline "my_new_facts.org" "Incoming") + (concat "* Fact #%(format \"%s\" (float-time)) :" + org-drill-question-tag + ":%^g\n + :PROPERTIES: + :DATE_ADDED: %t + :SOURCE_URL: %a + :END:\n +%i%?\n\n") + :empty-lines 1 + :immediate-finish nil) + ;; ...other capture templates... + )) +#+END_SRC + +Using this template, you can select a region of text which contains a fact you +want to remember, for example while reading a web page. You then invoke the +capture template above, and the selected text will be turned into a new fact +and saved to whichever file and heading you nominate in the template. You will +be given the opportunity to edit the fact -- you should make sure that the fact +makes sense independent of its context, as that is how it will be presented to +you. 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. + +Next, you start reading a web page within Emacs. For example, suppose you are +reading the Wikipedia entry on tuberculosis [[http://en.wikipedia.org/wiki/Tuberculosis][here]]. + +You read the following: + +#+BEGIN_QUOTE +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. +#+END_QUOTE + +You decide you want to remember that "Bacillus Calmette-Guérin vaccine" is the +name of the vaccine against tuberculosis. First, you select the relevant +portion of the text as the active region: + +#+BEGIN_QUOTE +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. +@<font style="background-color: yellow;">Prevention relies +on screening programs and vaccination, usually with Bacillus Calmette-Guérin +vaccine.@</font> +#+END_QUOTE + +Then you press a key to "capture" this piece of text (whatever key you have +bound to =org-capture=), followed by "f" to use the "Fact" template shown +above. + +A temporary buffer will be created, containing something like: + +#+BEGIN_EXAMPLE +** Fact #1282372386.671655 :drill: + + :PROPERTIES: + :DATE_ADDED: <2010-08-21 Sat> + :SOURCE_URL: [[http://en.wikipedia.org/wiki/Tuberculosis][Tuberculosis - Wikipedia, the free encyclopedia]] + :END: + +Prevention relies on screening programs and vaccination, usually with Bacillus +Calmette-Guérin vaccine. +#+END_EXAMPLE + +Note that the fact's properties automatically contain the date of its creation, +and a URL linking back to the origin of the fact -- the web page you were +browsing, in this case. Because fact "titles" are seldom necessary, the title +of the fact contains a meaningless but unique number (the number of seconds +elapsed since 1/1/1970). + +Next, you edit the sentence so that it makes sense when you are presented with +it out of context, and you also mark the key fact you want to remember by +surrounding it with single square brackets. + +: Prevention of tuberculosis relies on screening programs and vaccination, +: usually with [Bacillus Calmette-Guérin vaccine]. + +You then press =C-c C-c=, and the new fact is saved. You continue reading the +web page, adding other facts if you wish. + +Points to note: +- You can of course define 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. +- You don't have to use a web browser within Emacs. The "fact" template above + will work if you do not have text selected -- the new fact will be empty. You + could read a web page (or PDF document, etc) in a program of your choice, + copy some text to the clipboard, then switch to Emacs and paste it into a new + empty fact. +- Alternatively, you could define a template that takes its text from the + clipboard rather than from the selected region. You can do this by changing + the =%i= in the fact template to =%x= or =%^C=. See the documentation for the + variable =org-capture-templates= for more details. + + +* Still to do + + +- hide drawers. +- =org-drill-question-tag= should use a tag match string, rather than a + single tag +- progress indicator during drill session: cumulative time, time spent thinking + about this card +- perhaps take account of item priorities, showing high priority items first + |