Many changes:2.0

- Item drill data is stored in a clearer format, each value has its own property, the old 'org-learn'
  LEARN_DATA property has been dropped. Items that contain LEARN_DATA are silently rolled over to
  the new format.
- For SM5, matrix of optimal factors is now correctly *global* rather than per-item, and is saved
  between drill sessions as an emacs customization variable.
- We store interval data as floating point numbers rather than rounding to the nearest integer.
- New experimental algorithm: 'simple8', based on SuperMemo SM8.
- New options:
  - org-drill-forgetting-index: define the percentage of items that it is "acceptable" to fail.
    A warning message is shown after the drill session if more items than this were failed.
  - org-drill-learn-fraction: governs how fast time intervals increase with each successful
    repetition of an item.
  - org-drill-adjust-intervals-for-early-and-late-repetitions-p: if true, alter next scheduled date
    if an item is reviewed earlier or later than it was supposed to be.
- Almost all variables have been declared safe for file-local reassignment.
- We now ignore org-learn-always-reschedule, regarding it as always true.
- Post-session report now shows a count of dormant items (those not yet due for review).

1 files changed, 451 insertions, 231 deletions

diff --git a/README.html b/README.html
index 7f46d5b..5561788 100755
--- a/README.html
+++ b/README.html
@@ -7,7 +7,7 @@ lang="en" xml:lang="en">
 <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="2011-04-04 10:18:44 "/>
+<meta name="generated" content="2011-04-08 16:00:36 "/>
 <meta name="author" content="Paul Sexton"/>
 <meta name="description" content=""/>
 <meta name="keywords" content=""/>
@@ -89,7 +89,7 @@ lang="en" xml:lang="en">
 <div id="text-table-of-contents">
 <ul>
 <li><a href="#sec-1">Synopsis </a></li>
-<li><a href="#sec-2">Installation and Customisation </a></li>
+<li><a href="#sec-2">Installation </a></li>
 <li><a href="#sec-3">Demonstration </a></li>
 <li><a href="#sec-4">Writing the questions </a>
 <ul>
@@ -98,15 +98,28 @@ lang="en" xml:lang="en">
 <li><a href="#sec-4_3">Two-sided cards </a></li>
 <li><a href="#sec-4_4">Multi-sided cards </a></li>
 <li><a href="#sec-4_5">Multi-cloze cards </a></li>
-<li><a href="#sec-4_6">User-defined topic types </a></li>
-<li><a href="#sec-4_7">Comments </a></li>
+<li><a href="#sec-4_6">User-defined card types </a></li>
 </ul>
 </li>
 <li><a href="#sec-5">Running the drill session </a></li>
-<li><a href="#sec-6">Leeches </a></li>
-<li><a href="#sec-7">Cram mode </a></li>
-<li><a href="#sec-8">Incremental reading </a></li>
-<li><a href="#sec-9">Still to do </a></li>
+<li><a href="#sec-6">Cram mode </a></li>
+<li><a href="#sec-7">Leeches </a></li>
+<li><a href="#sec-8">Customisation </a>
+<ul>
+<li><a href="#sec-8_1">Appearance of items during drill sessions </a></li>
+<li><a href="#sec-8_2">Duration of drill sessions </a></li>
+<li><a href="#sec-8_3">Spaced repetition algorithm </a>
+<ul>
+<li><a href="#sec-8_3_1">Choice of algorithm </a></li>
+<li><a href="#sec-8_3_2">Random variation of repetition intervals </a></li>
+<li><a href="#sec-8_3_3">Adjustment for early or late review of items </a></li>
+<li><a href="#sec-8_3_4">Adjusting item difficulty globally </a></li>
+</ul>
+</li>
+<li><a href="#sec-8_4">Per-file customisation settings </a></li>
+</ul>
+</li>
+<li><a href="#sec-9">Incremental reading </a></li>
 </ul>
 </div>
 </div>
@@ -138,7 +151,7 @@ For more on the spaced repetition algorithm, and examples of other programs
 that use it, see:
 </p><ul>
 <li>
-<a href="http://supermemo.com/index.htm">SuperMemo</a> (the SM5 algorithm is discussed <a href="http://www.supermemo.com/english/ol/sm5.htm">here</a>)
+<a href="http://supermemo.com/index.htm">SuperMemo</a> (see descriptions of the SM2, SM5 and SM8 algorithms)
 </li>
 <li>
 <a href="http://ichi2.net/anki/">Anki</a>
@@ -155,7 +168,7 @@ that use it, see:
 </div>
 
 <div id="outline-container-2" class="outline-2">
-<h2 id="sec-2">Installation and Customisation </h2>
+<h2 id="sec-2">Installation </h2>
 <div class="outline-text-2" id="text-2">
 
 
@@ -172,85 +185,6 @@ Put the following in your <code>.emacs</code>. You will also need to make sure t
 
 
 
-<p>
-I also recommend the following, so that items are always eventually retested,
-even when you remember them well.
-</p>
-
-
-
-<pre class="example">(setq org-learn-always-reschedule t)
-</pre>
-
-
-
-<p>
-If you want cloze-deleted text to show up in a special font within Org mode
-buffers, also add:
-</p>
-
-
-
-<pre class="example">(setq org-drill-use-visible-cloze-face-p t)
-</pre>
-
-
-
-<p>
-Item headings may contain information that "gives away" the answer to the item,
-either in the heading text or in tags. If you want item headings to be made
-invisible while each item is being tested, add:
-</p>
-
-
-
-<pre class="example">(setq org-drill-hide-item-headings-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>
-
-
 
 
 </div>
@@ -284,8 +218,9 @@ drill topics are written.
 
 <p>
 Org-Drill uses org mode topics as 'drill items'. To be used as a drill item,
-the topic must have a tag that matches <code>org-drill-question-tag</code>. This is
-<code>:drill:</code> by default. Any other org topics will be ignored.
+the topic must have a tag that matches the value of
+<code>org-drill-question-tag</code>. This is <code>:drill:</code> by default. Any other org topics
+will be ignored.
 </p>
 <p>
 You don't need to schedule the topics initially.  However <code>org-drill</code> <b>will</b>
@@ -295,16 +230,40 @@ memorisation.
 </p>
 <p>
 How should 'drill topics' be structured? Any org topic is a legal drill topic
-&ndash; 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.
+&ndash; 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.
 </p>
 <p>
 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.
+recall purposes. For this reason, some other card types are defined, including:
+</p><ul>
+<li>
+<a href="#sec-4_3">Two-sided cards</a>
+</li>
+<li>
+<a href="#sec-4_4">Multi-sided cards</a>
+</li>
+<li>
+<a href="#Multicloze--cards">Multicloze cards</a>
+</li>
+<li>
+<a href="#sec-4_6">User-defined card types</a>
+</li>
+</ul>
+
+
+<p>
+<b>A note about comments:</b> 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.
 </p>
 
+
 </div>
 
 <div id="outline-container-4_1" class="outline-3">
@@ -312,6 +271,7 @@ recall purposes.
 <div class="outline-text-3" id="text-4_1">
 
 
+
 <p>
 The simplest drill topic has no special structure. When such a topic is
 presented during a drill session, any subheadings are "collapsed" with their
@@ -321,11 +281,11 @@ heading, and the answer within a subheading. For example:
 
 
 
-<pre class="example">* Item                                   :drill:
-What is the capital city of Estonia?
+<pre class="src src-org"><span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Item                                   </span><span style="color: #66cdaa; background-color: #4169e1; font-weight: bold;">:drill:</span><span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">
+</span>What is the capital city of Estonia?
 
-** The Answer
-Tallinn.
+<span style="color: #4876ff; background-color: #000080; font-weight: bold;">** The Answer
+</span>Tallinn.
 </pre>
 
 
@@ -344,6 +304,7 @@ be visible, but the contents of the subheading ("The Answer") will be hidden.
 <div class="outline-text-3" id="text-4_2">
 
 
+
 <p>
 Cloze deletion can be used in any drill topic regardless of whether it is
 otherwise 'simple', or is one of the specialised topic types discussed
@@ -356,8 +317,9 @@ example:
 
 
 
-<pre class="example">* Item                                   :drill:
-The capital city of Estonia is [Tallinn].
+
+<pre class="src src-org"><span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Item                                   </span><span style="color: #66cdaa; background-color: #4169e1; font-weight: bold;">:drill:</span><span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">
+</span>The capital city of Estonia is <span style="color: #ab82ff;">[Tallinn]</span>.
 </pre>
 
 
@@ -388,8 +350,8 @@ Example:
 
 
 
-<pre class="example">Type 1 hypersensitivity reactions are mediated by [immunoglobulin E|molecule]
-and [mast cells|cell type].
+<pre class="src src-org">Type 1 hypersensitivity reactions are mediated by <span style="color: #ab82ff;">[immunoglobulin E</span><span style="color: #483d8b;">|molecule</span><span style="color: #ab82ff;">]</span>
+and <span style="color: #ab82ff;">[mast cells</span><span style="color: #483d8b;">|cell type</span><span style="color: #ab82ff;">]</span>.
 </pre>
 
 
@@ -411,7 +373,7 @@ and <font style="background-color: blue;" color="cyan">
 </div>
 
 <div id="outline-container-4_3" class="outline-3">
-<h3 id="sec-4_3">Two-sided cards </h3>
+<h3 id="sec-4_3"><a name="Two-sided--cards" id="Two-sided--cards"></a>Two-sided cards </h3>
 <div class="outline-text-3" id="text-4_3">
 
 
@@ -436,21 +398,21 @@ review.
 
 
 
-<pre class="example">* Noun                                               :drill:
-    :PROPERTIES:
-    :DRILL_CARD_TYPE: twosided
-    :END:
+<pre class="src src-org"><span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Noun                                               </span><span style="color: #66cdaa; background-color: #4169e1; font-weight: bold;">:drill:</span><span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">
+</span><span style="color: #8b4789;">    :PROPERTIES:</span>
+    <span style="color: #8b4789;">:DRILL_CARD_TYPE:</span> <span style="color: #006400;">twosided</span>
+<span style="color: #8b4789;">    :END:</span>
 
 Translate this word.
 
-** Spanish
-la mujer
+<span style="color: #4876ff; background-color: #000080; font-weight: bold;">** Spanish
+</span>la mujer
 
-** English
-the woman
+<span style="color: #4876ff; background-color: #000080; font-weight: bold;">** English
+</span>the woman
 
-** Example sentence
-¿Quién fue esa mujer?
+<span style="color: #4876ff; background-color: #000080; font-weight: bold;">** Example sentence
+</span>&#191;Qui&#233;n fue esa mujer?
 Who was that woman?
 </pre>
 
@@ -468,10 +430,11 @@ not one of the first two 'sides' of the topic.
 </div>
 
 <div id="outline-container-4_4" class="outline-3">
-<h3 id="sec-4_4">Multi-sided cards </h3>
+<h3 id="sec-4_4"><a name="Multi-sided--cards" id="Multi-sided--cards"></a>Multi-sided cards </h3>
 <div class="outline-text-3" id="text-4_4">
 
 
+
 <p>
 The <code>multisided</code> card type is similar to <code>twosided</code>, except that any
 subheading has a chance of being presented during the topic review. One
@@ -480,21 +443,21 @@ subheading is always shown and all others are always hidden.
 
 
 
-<pre class="example">* Noun                                               :drill:
-    :PROPERTIES:
-    :DRILL_CARD_TYPE: multisided
-    :END:
+<pre class="src src-org"><span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Noun                                               </span><span style="color: #66cdaa; background-color: #4169e1; font-weight: bold;">:drill:</span><span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">
+</span><span style="color: #8b4789;">    :PROPERTIES:</span>
+    <span style="color: #8b4789;">:DRILL_CARD_TYPE:</span> <span style="color: #006400;">multisided</span>
+<span style="color: #8b4789;">    :END:</span>
 
 Translate.
 
-** Spanish
-la mesa
+<span style="color: #4876ff; background-color: #000080; font-weight: bold;">** Spanish
+</span>la mesa
 
-** English
-the table
+<span style="color: #4876ff; background-color: #000080; font-weight: bold;">** English
+</span>the table
 
-** Picture
-[[file:table.jpg][PICTURE]]
+<span style="color: #4876ff; background-color: #000080; font-weight: bold;">** Picture
+</span><span style="color: #00bfff; text-decoration: underline;">PICTURE</span>
 </pre>
 
 
@@ -503,43 +466,47 @@ the table
 The user will be shown the main text and either 'la mujer', <i>or</i> 'the woman',
 <i>or</i> a picture of a table.
 </p>
+
 </div>
 
 </div>
 
 <div id="outline-container-4_5" class="outline-3">
-<h3 id="sec-4_5">Multi-cloze cards </h3>
+<h3 id="sec-4_5"><a name="Multi-cloze--cards" id="Multi-cloze--cards"></a>Multi-cloze cards </h3>
 <div class="outline-text-3" id="text-4_5">
 
 
+
 <p>
 Often, you will wish to create cards out of sentences that express several
 facts, such as the following:
 </p>
-<blockquote>
 
-<p>The capital city of New Zealand is Wellington, which is located in the
+
+
+<pre class="src src-org">The capital city of New Zealand is Wellington, which is located in the
 South Island and has a population of about 400,000.
-</p>
-</blockquote>
+</pre>
+
 
 
 <p>
 There is more than one fact in this statement &ndash; you could create a single
 'simple' card with all the facts marked as cloze text, like so:
 </p>
-<blockquote>
 
-<p>The capital city of [New Zealand] is [Wellington], which is located in
-[the South Island] and has a population of about [400,000].
-</p>
-</blockquote>
+
+
+<pre class="src src-org">The capital city of <span style="color: #ab82ff;">[New Zealand]</span> is <span style="color: #ab82ff;">[Wellington]</span>, which is located in
+the <span style="color: #ab82ff;">[North</span><span style="color: #483d8b;">|North/South</span><span style="color: #ab82ff;">]</span> Island and has a population of about <span style="color: #ab82ff;">[400,000]</span>.
+</pre>
+
 
 
 <p>
 But this card will be difficult to remember. If you get just one of the 4
 hidden facts wrong, you will fail the card. A card like this is likely to
-become a <a href="#sec-6">leech</a>.
+become a <a href="#sec-7">leech</a>.
 </p>
 <p>
 A better way to express all these facts using 'simple' cards is to create
@@ -549,29 +516,29 @@ like this:
 
 
 
-<pre class="example">* Fact
-The capital city of [New Zealand] is Wellington, which has a population of
+<pre class="src src-org"><span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Fact
+</span>The capital city of <span style="color: #ab82ff;">[New Zealand]</span> is Wellington, which has a population of
 about 400,000.
 
-* Fact
-The capital city of New Zealand is [Wellington], which has a population of
+<span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Fact
+</span>The capital city of New Zealand is <span style="color: #ab82ff;">[Wellington]</span>, 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].
+<span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Fact
+</span>The capital city of New Zealand is Wellington, which has a population of
+about <span style="color: #ab82ff;">[400,000]</span>.
 
-* Fact
-The capital city of [New Zealand] is Wellington, which is located in the
-the South Island.
+<span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Fact
+</span>The capital city of <span style="color: #ab82ff;">[New Zealand]</span> is Wellington, which is located in the
+the North Island.
 
-* Fact
-The capital city of New Zealand is [Wellington], which is located in
-the South Island.
+<span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Fact
+</span>The capital city of New Zealand is <span style="color: #ab82ff;">[Wellington]</span>, which is located in
+the North Island.
 
-* Fact
-The capital city of New Zealand is Wellington, which is located in
-[the South Island].
+<span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Fact
+</span>The capital city of New Zealand is Wellington, which is located in
+the <span style="color: #ab82ff;">[North</span><span style="color: #483d8b;">|North/South</span><span style="color: #ab82ff;">]</span> Island.
 </pre>
 
 
@@ -592,28 +559,30 @@ will be hidden.
 
 
 
-<pre class="example">* Fact
-  :PROPERTIES:
-  :DRILL_CARD_TYPE: multicloze
-  :END:
+<pre class="src src-org"><span style="color: #f0ffff; background-color: #4169e1; font-weight: bold;">* Fact
+</span><span style="color: #8b4789;">  :PROPERTIES:</span>
+  <span style="color: #8b4789;">:DRILL_CARD_TYPE:</span> <span style="color: #006400;">multicloze</span>
+<span style="color: #8b4789;">  :END:</span>
 
-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 <span style="color: #ab82ff;">[New Zealand]</span> is <span style="color: #ab82ff;">[Wellington]</span>, which is located in
+the <span style="color: #ab82ff;">[North</span><span style="color: #483d8b;">|North/South</span><span style="color: #ab82ff;">]</span> Island and has a population of about <span style="color: #ab82ff;">[400,000]</span>.
 </pre>
 
 
 
+
 </div>
 
 </div>
 
 <div id="outline-container-4_6" class="outline-3">
-<h3 id="sec-4_6">User-defined topic types </h3>
+<h3 id="sec-4_6"><a name="User-defined--card--types" id="User-defined--card--types"></a>User-defined card types </h3>
 <div class="outline-text-3" id="text-4_6">
 
 
+
 <p>
-Finally, you can write your own elisp functions to define new kinds of
+Finally, you can write your own emacs lisp functions to define new kinds of
 topics. Any new topic type will need to be added to
 <code>org-drill-card-type-alist</code>, and cards using that topic type will need to have
 it as the value of their <code>DRILL_CARD_TYPE</code> property. For an example, see the
@@ -623,23 +592,8 @@ function <code>org-drill-present-spanish-verb</code>, which defines the new topi
 <p>
 See the file <a href="spanish.html">spanish.org</a> for a full set of example material.
 </p>
-</div>
-
-</div>
-
-<div id="outline-container-4_7" class="outline-3">
-<h3 id="sec-4_7">Comments </h3>
-<div class="outline-text-3" id="text-4_7">
 
 
-<p>
-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.
-</p>
-
 </div>
 </div>
 
@@ -717,10 +671,31 @@ answer, or 'e' to finish the drill and jump to the current topic for editing
 </div>
 
 <div id="outline-container-6" class="outline-2">
-<h2 id="sec-6"><a name="leeches" id="leeches"></a>Leeches </h2>
+<h2 id="sec-6">Cram mode </h2>
 <div class="outline-text-2" id="text-6">
 
 
+
+<p>
+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.
+</p>
+<p>
+To do this, run a <i>cram session</i> with the <code>org-drill-cram</code> command (<code>M-x org-drill-cram RET</code>). 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 <code>org-drill-cram-hours</code>).
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-7" class="outline-2">
+<h2 id="sec-7"><a name="leeches" id="leeches"></a>Leeches </h2>
+<div class="outline-text-2" id="text-7">
+
+
 <p>
 From the Anki website, <a href="http://ichi2.net/anki/wiki/Leeches">http://ichi2.net/anki/wiki/Leeches</a>:
 </p>
@@ -771,30 +746,297 @@ See <a href="http://www.supermemo.com/help/leech.htm">the SuperMemo website</a>
 
 </div>
 
-<div id="outline-container-7" class="outline-2">
-<h2 id="sec-7">Cram mode </h2>
-<div class="outline-text-2" id="text-7">
+<div id="outline-container-8" class="outline-2">
+<h2 id="sec-8">Customisation </h2>
+<div class="outline-text-2" id="text-8">
 
 
 
 <p>
-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.
+Org-Drill has several settings which you change using
+<code>M-x customize-group org-drill &lt;RET&gt;</code>. Alternatively you can change these
+settings by adding elisp code to your configuration file (<code>.emacs</code>).
 </p>
+
+
+</div>
+
+<div id="outline-container-8_1" class="outline-3">
+<h3 id="sec-8_1">Appearance of items during drill sessions </h3>
+<div class="outline-text-3" id="text-8_1">
+
+
+
 <p>
-To do this, run a <i>cram session</i> with the <code>org-drill-cram</code> command (<code>M-x org-drill-cram RET</code>). 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 <code>org-drill-cram-hours</code>).
+If you want cloze-deleted text to show up in a special font within Org mode
+buffers, add this to your .emacs:
+</p>
+
+
+
+<pre class="example">(setq org-drill-use-visible-cloze-face-p t)
+</pre>
+
+
+
+<p>
+Item headings may contain information that "gives away" the answer to the item,
+either in the heading text or in tags. If you want item headings to be made
+invisible while each item is being tested, add:
 </p>
 
+
+
+<pre class="example">(setq org-drill-hide-item-headings-p t)
+</pre>
+
+
+
+
 </div>
 
 </div>
 
-<div id="outline-container-8" class="outline-2">
-<h2 id="sec-8">Incremental reading </h2>
-<div class="outline-text-2" id="text-8">
+<div id="outline-container-8_2" class="outline-3">
+<h3 id="sec-8_2">Duration of drill sessions </h3>
+<div class="outline-text-3" id="text-8_2">
+
+
+
+<p>
+By default, a drill session will end when either 30 items have been
+successfully reviewed, or 20 minutes have passed. To change this behaviour, use
+the following settings.
+</p>
+
+
+
+<pre class="example">(setq org-drill-maximum-items-per-session 40)
+(setq org-drill-maximum-duration 30)   ; 30 minutes
+</pre>
+
+
+
+<p>
+If either of these variables is set to nil, then item count or elapsed time
+will not count as reasons to end the session. If both variables are nil, the
+session will not end until <i>all</i> outstanding items have been reviewed.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-8_3" class="outline-3">
+<h3 id="sec-8_3">Spaced repetition algorithm </h3>
+<div class="outline-text-3" id="text-8_3">
+
+
+
+
+</div>
+
+<div id="outline-container-8_3_1" class="outline-4">
+<h4 id="sec-8_3_1">Choice of algorithm </h4>
+<div class="outline-text-4" id="text-8_3_1">
+
+
+
+<p>
+Org-Drill supports three different spaced repetition algorithms, all based on
+SuperMemo algorithms. These are:
+</p><dl>
+<dt><a href="http://www.supermemo.com/english/ol/sm2.htm">SM2</a></dt><dd>
+an early algorithm, used in SuperMemo 2.0 (1988), which remains very
+popular &ndash; Anki and Mnemosyne, two of the most popular spaced repetition
+programs, use SM2. This algorithm stores an 'ease factor' for each item,
+which is modified each time you rate your recall of the item.
+</dd>
+<dt><a href="http://www.supermemo.com/english/ol/sm5.htm">SM5</a> (default)</dt><dd>
+used in SuperMemo 5.0 (1989). This algorithm uses 'ease
+factors' but also uses a persistent, per-user 'matrix of optimal factors'
+which is also modified after each item repetition.
+</dd>
+<dt>Simple8</dt><dd>
+an experimental algorithm based on the <a href="http://www.supermemo.com/english/algsm8.htm">SM8</a> algorithm. SM8 is used
+in SuperMemo 8.0 (1998) and is almost identical to SM11 which is
+used in SuperMemo 2002. Like SM5, it uses a matrix of optimal
+factors. Simple8 differs from SM8 in that it does not adapt the
+matrix to the individual user, though it does adapt each item's
+'ease factor'.
+
+</dd>
+</dl>
+
+
+<p>
+If you want Org-Drill to use the <code>SM2</code> algorithm, put the following in your
+<code>.emacs</code>:
+</p>
+
+
+
+<pre class="example">(setq org-drill-spaced-repetition-algorithm 'sm2)
+</pre>
+
+
+
+
+</div>
+
+</div>
+
+<div id="outline-container-8_3_2" class="outline-4">
+<h4 id="sec-8_3_2">Random variation of repetition intervals </h4>
+<div class="outline-text-4" id="text-8_3_2">
+
+
+
+<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>
+
+
+
+
+</div>
+
+</div>
+
+<div id="outline-container-8_3_3" class="outline-4">
+<h4 id="sec-8_3_3">Adjustment for early or late review of items </h4>
+<div class="outline-text-4" id="text-8_3_3">
+
+
+
+<p>
+Reviewing items earlier or later than their scheduled review date may affect
+how soon the next review date should be scheduled. Code to make this adjustment
+is also presented on the SuperMemo website. It can be enabled with:
+</p>
+
+
+
+<pre class="example">(setq org-drill-adjust-intervals-for-early-and-late-repetitions-p t)
+</pre>
+
+
+
+<p>
+This will affect both early and late repetitions if the Simple8 algorithm is
+used. For the SM5 algorithm it will affect early repetitions only. It has no
+effect on the SM2 algorithm.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-8_3_4" class="outline-4">
+<h4 id="sec-8_3_4">Adjusting item difficulty globally </h4>
+<div class="outline-text-4" id="text-8_3_4">
+
+
+
+<p>
+The <code>learn fraction</code> is a global value which affects how quickly the intervals
+(times between each retest of an item) increase with successive repetitions,
+for <i>all</i> items. The default value is 0.5, and this is the value used in
+SuperMemo. For some collections of information, you may find that you are
+reviewing items too often (they are too easy and the workload is too high), or
+too seldom (you are failing them too often). In these situations, it is
+possible to alter the learn fraction from its default in order to increase or
+decrease the frequency of repetition of items over time. Increasing the value
+will make the time intervals grow faster, and lowering it will make them grow
+more slowly. The table below shows the growth in intervals (in days) with some
+different values of the learn fraction (F). The table assumes that the item is
+successfully recalled each time, with an average quality of just under 4.
+</p>
+
+<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
+<caption></caption>
+<colgroup><col class="left" /><col class="right" /><col class="right" /><col class="right" /><col class="right" /><col class="right" />
+</colgroup>
+<thead>
+<tr><th scope="col" class="left">Repetition</th><th scope="col" class="right">F=0.3</th><th scope="col" class="right">F=0.4</th><th scope="col" class="right"><b>F=0.5</b></th><th scope="col" class="right">F=0.6</th><th scope="col" class="right">F=0.7</th></tr>
+</thead>
+<tbody>
+<tr><td class="left">1st</td><td class="right">2</td><td class="right">2</td><td class="right">2</td><td class="right">2</td><td class="right">2</td></tr>
+<tr><td class="left">2nd</td><td class="right">7</td><td class="right">7</td><td class="right">7</td><td class="right">7</td><td class="right">7</td></tr>
+<tr><td class="left">5th</td><td class="right">26</td><td class="right">34</td><td class="right">46</td><td class="right">63</td><td class="right">85</td></tr>
+<tr><td class="left">10th</td><td class="right">85</td><td class="right">152</td><td class="right">316</td><td class="right">743</td><td class="right">1942</td></tr>
+<tr><td class="left">15th</td><td class="right">233</td><td class="right">501</td><td class="right">1426</td><td class="right">5471</td><td class="right">27868</td></tr>
+</tbody>
+</table>
+
+
+<p>
+To alter the learn fraction, put the following in your .emacs:
+</p>
+
+
+
+<pre class="src src-elisp"><span style="color: #696969;">(</span>setq org-drill-learn-fraction 0.45<span style="color: #696969;">)</span>   <span style="color: #db7093;">; </span><span style="color: #db7093;">change the value as desired
+</span></pre>
+
+
+
+
+</div>
+</div>
+
+</div>
+
+<div id="outline-container-8_4" class="outline-3">
+<h3 id="sec-8_4">Per-file customisation settings </h3>
+<div class="outline-text-3" id="text-8_4">
+
+
+
+<p>
+Most of the above settings are safe as file-local variables. This means you can
+include a commented section like this at the end of your .org file to apply
+special settings when running a Drill session using that file:
+</p>
+
+
+
+<pre class="src src-org"><span style="color: #db7093;"># Local Variables&#58;</span>
+<span style="color: #db7093;"># org-drill-maximum-items-per-session:    50</span>
+<span style="color: #db7093;"># org-drill-spaced-repetition-algorithm:  simple8</span>
+<span style="color: #db7093;"># End:</span>
+</pre>
+
+
+
+
+</div>
+</div>
+
+</div>
+
+<div id="outline-container-9" class="outline-2">
+<h2 id="sec-9">Incremental reading </h2>
+<div class="outline-text-2" id="text-9">
 
 
 
@@ -827,26 +1069,26 @@ captured facts.
 
 
 
-<pre class="example">(setq org-capture-templates
-       `(("u"
-         "Task: Read this URL"
+<pre class="src src-elisp"><span style="color: #696969;">(</span>setq org-capture-templates
+       `<span style="color: #696969;">((</span><span style="color: #008b00;">"u"</span>
+         <span style="color: #008b00;">"Task: Read this URL"</span>
          entry
-         (file+headline "tasks.org" "Articles To Read")
-         ,(concat "* TODO Read article: '%:description'\nURL: %c\n\n")
-         :empty-lines 1
-         :immediate-finish t)
+         <span style="color: #696969;">(</span>file+headline <span style="color: #008b00;">"tasks.org"</span> <span style="color: #008b00;">"Articles To Read"</span><span style="color: #696969;">)</span>
+         ,<span style="color: #696969;">(</span>concat <span style="color: #008b00;">"* TODO Read article: '%:description'\nURL: %c\n\n"</span><span style="color: #696969;">)</span>
+         <span style="color: #4169e1;">:empty-lines</span> 1
+         <span style="color: #4169e1;">:immediate-finish</span> t<span style="color: #696969;">)</span>
 
-        ("w"
-         "Capture web snippet"
+        <span style="color: #696969;">(</span><span style="color: #008b00;">"w"</span>
+         <span style="color: #008b00;">"Capture web snippet"</span>
          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...
-    ))
+         <span style="color: #696969;">(</span>file+headline <span style="color: #008b00;">"my-facts.org"</span> <span style="color: #008b00;">"Inbox"</span><span style="color: #696969;">)</span>
+         ,<span style="color: #696969;">(</span>concat <span style="color: #008b00;">"* Fact: '%:description'        :"</span>
+                  <span style="color: #696969;">(</span>format <span style="color: #008b00;">"%s"</span> org-drill-question-tag<span style="color: #696969;">)</span>
+                  <span style="color: #008b00;">":\n:PROPERTIES:\n:DATE_ADDED: %u\n:SOURCE_URL: %c\n:END:\n\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> t<span style="color: #696969;">)</span>
+        <span style="color: #db7093;">;; </span><span style="color: #db7093;">...other capture templates...
+</span>    <span style="color: #696969;">))</span>
 </pre>
 
 
@@ -924,10 +1166,10 @@ something like:
 
 
 
-<pre class="example">** Fact: 'Tuberculosis - Wikipedia, the Free Encyclopedia'        :drill:
-
+<pre class="src src-org"><span style="color: #4876ff; background-color: #000080; font-weight: bold;">** Fact: 'Tuberculosis - Wikipedia, the Free Encyclopedia'        </span><span style="color: #66cdaa; background-color: #000080; font-weight: bold;">:drill:</span><span style="color: #4876ff; background-color: #000080; font-weight: bold;">
+</span>
 Prevention relies on screening programs and vaccination, usually with Bacillus
-Calmette-Guérin vaccine.
+Calmette-Gu&#233;rin vaccine.
 </pre>
 
 
@@ -952,33 +1194,11 @@ or give it different tags or properties, for example.
 </p>
 
 </div>
-
-</div>
-
-<div id="outline-container-9" class="outline-2">
-<h2 id="sec-9">Still to do </h2>
-<div class="outline-text-2" id="text-9">
-
-
-<ul>
-<li>
-<code>org-drill-question-tag</code> should use a tag match string, rather than a
-single tag? Can use <code>org-make-tag-matcher</code>.
-</li>
-<li>
-perhaps take account of item priorities, showing high priority items first
-</li>
-<li>
-get tooltips to work for old/new/etc counts during review?
-</li>
-</ul>
-
-</div>
 </div>
 <div id="postamble">
 <p class="author"> Author: Paul Sexton
 </p>
-<p class="date"> Date: 2011-04-04 10:18:44 </p>
+<p class="date"> Date: 2011-04-08 16:00:36 </p>
 <p class="creator">HTML generated by org-mode 7.4 in emacs 23</p>
 </div>
 </div>