1. Paul Sexton
  2. org-drill

Source

org-drill / README.html

Diff from to

File README.html

 <title>Org-Drill</title>
 <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
 <meta name="generator" content="Org-mode"/>
-<meta name="generated" content="2010-08-22 09:45:05 NZST"/>
+<meta name="generated" content="2010-08-26 21:14:57 NZST"/>
 <meta name="author" content="Paul Sexton"/>
 <meta name="description" content=""/>
 <meta name="keywords" content=""/>
  }
 /*]]>*///-->
 </script>
+
 </head>
 <body>
 <div id="content">
 <div id="text-table-of-contents">
 <ul>
 <li><a href="#sec-1">1 Synopsis </a></li>
-<li><a href="#sec-2">2 Installation </a></li>
+<li><a href="#sec-2">2 Installation and Customisation </a></li>
 <li><a href="#sec-3">3 Demonstration </a></li>
 <li><a href="#sec-4">4 Writing the questions </a>
 <ul>
 </div>
 
 <div id="outline-container-2" class="outline-2">
-<h2 id="sec-2"><span class="section-number-2">2</span> Installation </h2>
+<h2 id="sec-2"><span class="section-number-2">2</span> Installation and Customisation </h2>
 <div class="outline-text-2" id="text-2">
 
 
 
 
 
-<pre class="src src-emacs-lisp"><span style="color: #696969;">(</span><span style="color: #8b4789;">require</span> '<span style="color: #698b22; font-weight: bold;">org-drill</span><span style="color: #696969;">)</span>
+<pre class="example">(require 'org-drill)
 </pre>
 
 
 
 <p>
 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.
 </p>
 
 
 
-<pre class="src src-emacs-lisp"><span style="color: #696969;">(</span>setq org-learn-always-reschedule t<span style="color: #696969;">)</span>
+<pre class="example">(setq org-learn-always-reschedule t)
 </pre>
 
 
 
 
 
-<pre class="src src-emacs-lisp"><span style="color: #696969;">(</span>setq org-drill-use-visible-cloze-face-p t<span style="color: #696969;">)</span>
+<pre class="example">(setq org-drill-use-visible-cloze-face-p t)
+</pre>
+
+
+
+<p>
+Org-Drill supports two different spaced repetition algorithms &ndash; SM5 (the
+default, implemented by <code>org-learn</code>) and SM2. SM2 is an earlier algorithm which
+remains very popular &ndash; Anki and Mnemosyne, two of the most popular spaced
+repetition programs, use SM2.
+</p>
+<p>
+If you want Org-Drill to use the SM2 algorithm, put the following in your
+<code>.emacs</code>:
+</p>
+
+
+
+<pre class="example">(setq org-drill-spaced-repetition-algorithm 'sm2)
+</pre>
+
+
+
+<p>
+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.
+</p>
+<p>
+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 <a href="http://www.supermemo.com/english/ol/sm5.htm">his code</a>.
+</p>
+<p>
+To enable random "noise" for item intervals, set the variable
+<code>org-drill-add-random-noise-to-intervals-p</code> to true by putting the following in
+your <code>.emacs</code>:
+</p>
+
+
+
+<pre class="example">(setq org-drill-add-random-noise-to-intervals-p t)
 </pre>
 
 
 </p>
 <blockquote>
 
-<p>The capital city of Estonia is <font style="background-color: blue;" color="blue">
-XXXXXXX</font>.
+<p>The capital city of Estonia is <font style="background-color: blue;" color="cyan">
+<tt>[&hellip;]</tt></font>.
 </p>
 </blockquote>
 
 <p>
 When the user presses a key, the text "Tallinn" will become visible.
 </p>
+<p>
+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.
+</p>
+<p>
+Example:
+</p>
+
+
+
+<pre class="example">Type 1 hypersensitivity reactions are mediated by [immunoglobulin E|molecule]
+and [mast cells|cell type].
+</pre>
+
+
+
+<blockquote>
+
+<p>Type 1 hypersensitivity reactions are mediated by 
+<font style="background-color: blue;" color="cyan">
+<tt>[&hellip;molecule]</tt></font>
+and <font style="background-color: blue;" color="cyan">
+<tt>[&hellip;cell type]</tt></font>.
+</p>
+</blockquote>
+
+
 
 </div>
 
 rate your recall of it by pressing a key between 0 and 5. The meaning of these
 numbers is (taken from <code>org-learn</code>):
 </p>
-<dl>
-<dt>0</dt><dd>
-Completely forgot. 
-</dd>
-<dt>1</dt><dd>
-Even after seeing the answer, it still took a bit to sink in. 
-</dd>
-<dt>2</dt><dd>
-After seeing the answer, you remembered it. 
-</dd>
-<dt>3</dt><dd>
-It took you awhile, but you finally remembered.
-</dd>
-<dt>4</dt><dd>
-After a little bit of thought you remembered.
-</dd>
-<dt>5</dt><dd>
-You remembered the item really easily.
+<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
+<caption></caption>
+<colgroup><col align="right" /><col align="left" /><col align="left" />
+</colgroup>
+<thead>
+<tr><th scope="col">Quality</th><th scope="col">SuperMemo label</th><th scope="col">Meaning</th></tr>
+</thead>
+<tbody>
+<tr><td>0</td><td>NULL</td><td>You have forgotten this card completely.</td></tr>
+<tr><td>1</td><td>BAD</td><td>Wrong answer.</td></tr>
+<tr><td>2</td><td>FAIL</td><td>Barely correct, the interval was too long.</td></tr>
+<tr><td>3</td><td>PASS</td><td>Correct answer, but with much effort.</td></tr>
+<tr><td>4</td><td>GOOD</td><td>Correct answer, with a little thought.</td></tr>
+<tr><td>5</td><td>BRIGHT</td><td>Correct answer, effortless.</td></tr>
+</tbody>
+</table>
 
-</dd>
-</dl>
 
-<p>You can press '?'  at the prompt if you have trouble remembering what the
+<p>
+You can press '?'  at the prompt if you have trouble remembering what the
 numbers 0&ndash;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).
 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 &ndash; e.g. w3 or <a href="http://www.emacswiki.org/emacs/emacs-w3m">emacs-w3m</a>. 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
-<a href="http://www.emacswiki.org/emacs/BookMarks">Emacs Wiki</a> for details.
+allows you to browse web pages either in emacs (w3 or <a href="http://www.emacswiki.org/emacs/emacs-w3m">emacs-w3m</a>) or in the
+external browser of your choice (<a href="http://orgmode.org/worg/org-contrib/org-protocol.php">org-protocol</a>).
+</p>
+<p>
+Another important component of incremental reading is the ability to save your
+exact place in a document, so you can read it <i>incrementally</i> rather than all
+at once. There is a large variety of bookmarking packages for emacs which
+provide advanced bookmarking functionality: see the <a href="http://www.emacswiki.org/emacs/BookMarks">Emacs Wiki</a> for details.
+Bookmarking exact webpage locations in an external browser is a bit more
+difficult. For Firefox, the addon works well.
 </p>
 <p>
 An example of using Org-Drill for incremental reading is given below. First,
-and most importantly, we need to define an <code>org-capture</code> template for captured
-facts:
+and most importantly, we need to define a couple of <code>org-capture</code> templates for
+captured facts. 
 </p>
 
 
 
-<pre class="src src-emacs-lisp"><span style="color: #696969;">(</span>setq org-capture-templates
-      `<span style="color: #696969;">((</span><span style="color: #008b00;">"f"</span> <span style="color: #008b00;">"Fact"</span> entry
-         <span style="color: #696969;">(</span>file+headline <span style="color: #008b00;">"my_new_facts.org"</span> <span style="color: #008b00;">"Incoming"</span><span style="color: #696969;">)</span>
-         <span style="color: #696969;">(</span>concat <span style="color: #008b00;">"* Fact #%(format \"%s\" (float-time))        :"</span>
-                 org-drill-question-tag
-                 <span style="color: #008b00;">":%^g\n
-    :PROPERTIES:
-    :DATE_ADDED: %t
-    :SOURCE_URL: %a
-    :END:\n
-%i%?\n\n"</span><span style="color: #696969;">)</span>
-         <span style="color: #4169e1;">:empty-lines</span> 1
-         <span style="color: #4169e1;">:immediate-finish</span> nil<span style="color: #696969;">)</span>
-        <span style="color: #db7093;">;; </span><span style="color: #db7093;">...other capture templates...
-</span>    <span style="color: #696969;">))</span>
+<pre class="example">(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...
+    ))
 </pre>
 
 
 
 <p>
-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 &ndash; 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. 
-</p>
-<p>
-Next, you start reading a web page within Emacs. For example, suppose you are
-reading the Wikipedia entry on tuberculosis <a href="http://en.wikipedia.org/wiki/Tuberculosis">here</a>.
+Using these templates and <code>org-protocol</code>, you can set up buttons in your web
+browser to:
+</p><ul>
+<li>
+Create a task telling you to read the URL of the currently viewed webpage
+</li>
+<li>
+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.
+
+</li>
+</ul>
+
+<p>For example, suppose you are reading the Wikipedia entry on tuberculosis <a href="http://en.wikipedia.org/wiki/Tuberculosis">here</a>.
 </p>
 <p>
 You read the following:
 
 <p>
 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:
 </p>
 <blockquote>
 
 
 
 <p>
-Then you press a key to "capture" this piece of text (whatever key you have
-bound to <code>org-capture</code>), followed by "f" to use the "Fact" template shown
-above. 
+Then you press the button you created when setting up <code>org=protocol</code>, 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.
 </p>
 <p>
-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 &ndash; since it contains several important facts &ndash; then split it up into
+multiple items when you edit it later in Emacs.)
+</p>
+<p>
+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:
 </p>
 
 
 
-<pre class="example">** Fact #1282372386.671655                           :drill:
-
-    :PROPERTIES:
-    :DATE_ADDED: &lt;2010-08-21 Sat&gt;
-    :SOURCE_URL: [[http://en.wikipedia.org/wiki/Tuberculosis][Tuberculosis - Wikipedia, the free encyclopedia]]
-    :END:
+<pre class="example">** Fact: 'Tuberculosis - Wikipedia, the Free Encyclopedia'        :drill:
 
 Prevention relies on screening programs and vaccination, usually with Bacillus
 Calmette-Guérin vaccine.
 
 
 <p>
-Note that the fact's properties automatically contain the date of its creation,
-and a URL linking back to the origin of the fact &ndash; 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).
-</p>
-<p>
-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.
 </p>
 <pre class="example">
 Prevention of tuberculosis relies on screening programs and vaccination,
 </pre>
 
 
+
 <p>
-You then press <code>C-c C-c</code>, and the new fact is saved. You continue reading the
-web page, adding other facts if you wish.
+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. 
 </p>
-<p>
-Points to note:
-</p><ul>
-<li>
-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.
-</li>
-<li>
-You don't have to use a web browser within Emacs. The "fact" template above
-will work if you do not have text selected &ndash; 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.
-</li>
-<li>
-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 <code>%i</code> in the fact template to <code>%x</code> or <code>%^C</code>. See the documentation for the
-variable <code>org-capture-templates</code> for more details.
 
-
-</li>
-</ul>
 </div>
 
 </div>
 <div class="outline-text-2" id="text-8">
 
 
-
 <ul>
 <li>
-hide drawers.
+hide drawers!
 </li>
 <li>
 <code>org-drill-question-tag</code> should use a tag match string, rather than a
 </li>
 <li>
 perhaps take account of item priorities, showing high priority items first
-
 </li>
 </ul>
 </div>
 <div id="postamble">
 <p class="author"> Author: Paul Sexton
 </p>
-<p class="date"> Date: 2010-08-22 09:45:05 NZST</p>
+<p class="date"> Date: 2010-08-26 21:14:57 NZST</p>
 <p class="creator">HTML generated by org-mode 7.01trans in emacs 23</p>
 </div>
 </div>