Source

org-drill / README.org

Diff from to

File README.org

 # -*- mode: org; coding: utf-8 -*-
+#+STARTUP: showall
 #+TITLE: Org-Drill
 #+AUTHOR: Paul Sexton
 
 - [[http://mnemosyne-proj.org/index.php][Mnemosyne]]
 
 
-* Installation
+* Installation and Customisation
 
 
 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 
+#+BEGIN_EXAMPLE
 (require 'org-drill)
-#+END_SRC
+#+END_EXAMPLE
 
 I also recommend the following, so that items are always eventually retested,
-even when you remember them very well.
+even when you remember them well.
 
-#+BEGIN_SRC emacs-lisp 
+#+BEGIN_EXAMPLE
 (setq org-learn-always-reschedule t)
-#+END_SRC
+#+END_EXAMPLE
 
 If you want cloze-deleted text to show up in a special font within Org mode
 buffers, also add:
 
-#+BEGIN_SRC emacs-lisp 
+#+BEGIN_EXAMPLE
 (setq org-drill-use-visible-cloze-face-p t)
-#+END_SRC
+#+END_EXAMPLE
+
+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=:
+
+#+BEGIN_EXAMPLE
+(setq org-drill-spaced-repetition-algorithm 'sm2)
+#+END_EXAMPLE
+
+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 [[http://www.supermemo.com/english/ol/sm5.htm][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=:
+
+#+BEGIN_EXAMPLE
+(setq org-drill-add-random-noise-to-intervals-p t)
+#+END_EXAMPLE
 
 
 * Demonstration
 During review, the user will see:
 
 #+BEGIN_QUOTE
-The capital city of Estonia is @<font style="background-color: blue;" color="blue">
-XXXXXXX@</font>.
+The capital city of Estonia is @<font style="background-color: blue;" color="cyan">
+@<tt>[...]@</tt>@</font>.
 #+END_QUOTE
 
 When the user presses a key, the text "Tallinn" will become visible.
 
+Clozed text can also contain a "hint" about the answer. If the text 
+surrounded by single square brackets contains a `|' character (vertical bar),
+all text after that character is treated as a hint, and will be visible when
+the rest of the text is hidden.
+
+Example:
+
+#+BEGIN_EXAMPLE
+Type 1 hypersensitivity reactions are mediated by [immunoglobulin E|molecule]
+and [mast cells|cell type].
+#+END_EXAMPLE
+
+#+BEGIN_QUOTE
+Type 1 hypersensitivity reactions are mediated by 
+@<font style="background-color: blue;" color="cyan">
+@<tt>[...molecule]@</tt>@</font>
+and @<font style="background-color: blue;" color="cyan">
+@<tt>[...cell type]@</tt>@</font>.
+#+END_QUOTE
+
 
 ** Two-sided cards
 
 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.
+| 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
 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.
+allows you to browse web pages either in emacs (w3 or [[http://www.emacswiki.org/emacs/emacs-w3m][emacs-w3m]]) or in the
+external browser of your choice ([[http://orgmode.org/worg/org-contrib/org-protocol.php][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 [[http://www.emacswiki.org/emacs/BookMarks][Emacs Wiki]] for details.
+Bookmarking exact webpage locations in an external browser is a bit more
+difficult. For Firefox, the addon works well.
 
 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:
+and most importantly, we need to define a couple of =org-capture= templates for
+captured facts. 
 
-#+BEGIN_SRC emacs-lisp 
+#+BEGIN_EXAMPLE
 (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")
+       `(("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 nil)
+         :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...
     ))
-#+END_SRC
+#+END_EXAMPLE
 
-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. 
+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.
 
-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]].
+For example, suppose you are reading the Wikipedia entry on tuberculosis [[http://en.wikipedia.org/wiki/Tuberculosis][here]].
 
 You read the following:
 
 #+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:
+name of the vaccine against tuberculosis. First, you select the `interesting'
+portion of the text with the mouse:
 
 #+BEGIN_QUOTE
 The classic symptoms of tuberculosis are a chronic cough with blood-tinged
 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. 
+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.
 
-A temporary buffer will be created, containing something like:
+(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 all the pieces of text you
+selected have been turned into drill items. Continuing the above example, you
+would see 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:
+** Fact: 'Tuberculosis - Wikipedia, the Free Encyclopedia'        :drill:
 
 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.
+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 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.
+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. 
 
 
 * Still to do
 
-
-- hide drawers.
+- 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
-