[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/org-drill e7ffd8e6eb 040/251: Renamed documentation file a
|
From: |
ELPA Syncer |
|
Subject: |
[nongnu] elpa/org-drill e7ffd8e6eb 040/251: Renamed documentation file and fixed a few typos. |
|
Date: |
Mon, 17 Jan 2022 18:58:59 -0500 (EST) |
branch: elpa/org-drill
commit e7ffd8e6eb290bd2053e100a483ddd9e012dcb33
Author: eeeickythump <devnull@localhost>
Commit: eeeickythump <devnull@localhost>
Renamed documentation file and fixed a few typos.
---
org-drill.html | 1569 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
org-drill.org | 919 +++++++++++++++++++++++++++++++++
2 files changed, 2488 insertions(+)
diff --git a/org-drill.html b/org-drill.html
new file mode 100644
index 0000000000..065fca33cf
--- /dev/null
+++ b/org-drill.html
@@ -0,0 +1,1569 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml";
+lang="en" xml:lang="en">
+<head>
+<title>org-drill.el – flashcards and spaced repetition for
org-mode</title>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
+<meta name="generator" content="Org-mode"/>
+<meta name="generated" content="2011-05-21 00:08:14 NZST"/>
+<meta name="author" content="Paul Sexton"/>
+<meta name="description" content=""/>
+<meta name="keywords" content=""/>
+<style type="text/css">
+ <!--/*--><![CDATA[/*><!--*/
+ html { font-family: Times, serif; font-size: 12pt; }
+ .title { text-align: center; }
+ .todo { color: red; }
+ .done { color: green; }
+ .tag { background-color: #add8e6; font-weight:normal }
+ .target { }
+ .timestamp { color: #bebebe; }
+ .timestamp-kwd { color: #5f9ea0; }
+ .right {margin-left:auto; margin-right:0px; text-align:right;}
+ .left {margin-left:0px; margin-right:auto; text-align:left;}
+ .center {margin-left:auto; margin-right:auto; text-align:center;}
+ p.verse { margin-left: 3% }
+ pre {
+ border: 1pt solid #AEBDCC;
+ background-color: #F3F5F7;
+ padding: 5pt;
+ font-family: courier, monospace;
+ font-size: 90%;
+ overflow:auto;
+ }
+ table { border-collapse: collapse; }
+ td, th { vertical-align: top; }
+ th.right { text-align:center; }
+ th.left { text-align:center; }
+ th.center { text-align:center; }
+ td.right { text-align:right; }
+ td.left { text-align:left; }
+ td.center { text-align:center; }
+ dt { font-weight: bold; }
+ div.figure { padding: 0.5em; }
+ div.figure p { text-align: center; }
+ textarea { overflow-x: auto; }
+ .linenr { font-size:smaller }
+ .code-highlighted {background-color:#ffff00;}
+ .org-info-js_info-navigation { border-style:none; }
+ #org-info-js_console-label { font-size:10px; font-weight:bold;
+ white-space:nowrap; }
+ .org-info-js_search-highlight {background-color:#ffff00; color:#000000;
+ font-weight:bold; }
+ /*]]>*/-->
+</style>
+<script type="text/javascript">
+<!--/*--><![CDATA[/*><!--*/
+ function CodeHighlightOn(elem, id)
+ {
+ var target = document.getElementById(id);
+ if(null != target) {
+ elem.cacheClassElem = elem.className;
+ elem.cacheClassTarget = target.className;
+ target.className = "code-highlighted";
+ elem.className = "code-highlighted";
+ }
+ }
+ function CodeHighlightOff(elem, id)
+ {
+ var target = document.getElementById(id);
+ if(elem.cacheClassElem)
+ elem.className = elem.cacheClassElem;
+ if(elem.cacheClassTarget)
+ target.className = elem.cacheClassTarget;
+ }
+/*]]>*///-->
+</script>
+
+</head>
+<body>
+<div id="content">
+
+<h1 class="title">org-drill.el – flashcards and spaced repetition for
org-mode</h1>
+
+
+<div id="table-of-contents">
+<h2>Table of Contents</h2>
+<div id="text-table-of-contents">
+<ul>
+<li><a href="#sec-1">General </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>
+<li><a href="#sec-4_1">Simple topics </a></li>
+<li><a href="#sec-4_2">Cloze deletion </a></li>
+<li><a href="#sec-4_3">Clozed text hints </a></li>
+<li><a href="#sec-4_4">Two-sided cards </a></li>
+<li><a href="#sec-4_5">Multi-sided cards </a></li>
+<li><a href="#sec-4_6">Multi-cloze cards </a></li>
+<li><a href="#sec-4_7">User-defined card types </a></li>
+<li><a href="#sec-4_8">Empty cards </a></li>
+</ul>
+</li>
+<li><a href="#sec-5">Running the drill session </a></li>
+<li><a href="#sec-6">Multiple sequential drill sessions </a></li>
+<li><a href="#sec-7">Cram mode </a></li>
+<li><a href="#sec-8">Leeches </a></li>
+<li><a href="#sec-9">Customisation </a>
+<ul>
+<li><a href="#sec-9_1">Visual appearance of items during drill sessions
</a></li>
+<li><a href="#sec-9_2">Duration of drill sessions </a></li>
+<li><a href="#sec-9_3">Saving buffers after drill sessions </a></li>
+<li><a href="#sec-9_4">Sources of items for drill sessions (scope) </a></li>
+<li><a href="#sec-9_5">Definition of old and overdue items </a></li>
+<li><a href="#sec-9_6">Spaced repetition algorithm </a>
+<ul>
+<li><a href="#sec-9_6_1">Choice of algorithm </a></li>
+<li><a href="#sec-9_6_2">Random variation of repetition intervals </a></li>
+<li><a href="#sec-9_6_3">Adjustment for early or late review of items </a></li>
+<li><a href="#sec-9_6_4">Adjusting item difficulty globally </a></li>
+</ul>
+</li>
+<li><a href="#sec-9_7">Per-file customisation settings </a></li>
+</ul>
+</li>
+<li><a href="#sec-10">Coping with large collections </a></li>
+<li><a href="#sec-11">Sharing, merging and synchronising item collections
</a></li>
+<li><a href="#sec-12">Incremental reading </a></li>
+<li><a href="#sec-13">Author </a></li>
+</ul>
+</div>
+</div>
+
+<div id="outline-container-1" class="outline-2">
+<h2 id="sec-1">General </h2>
+<div class="outline-text-2" id="text-1">
+
+
+
+<p>
+Org-Drill is an extension for <a href="http://orgmode.org/";>Org mode</a>.
Org-Drill uses a <a
href="http://en.wikipedia.org/wiki/Spaced_repetition";>spaced repetition</a>
+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.
+</p>
+<p>
+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.
+</p>
+<p>
+Different "topic types" can be defined, which present their information to the
+student in different ways.
+</p>
+<p>
+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> (see descriptions
of the SM2, SM5 and SM8 algorithms)
+</li>
+<li><a href="http://ichi2.net/anki/";>Anki</a>
+</li>
+<li><a href="http://mnemosyne-proj.org/index.php";>Mnemosyne</a>
+</li>
+</ul>
+
+
+<p>
+Org-Drill comes bundled with Org mode, in the "contrib" directory. Org-Drill
+also has its own repository, which is updated more regularly than the bundled
+version. The repository is at:
+</p>
+<p>
+<a
href="http://bitbucket.org/eeeickythump/org-drill";>http://bitbucket.org/eeeickythump/org-drill</a>
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-2" class="outline-2">
+<h2 id="sec-2">Installation </h2>
+<div class="outline-text-2" id="text-2">
+
+
+
+<p>
+The easiest way is to customise the variable 'org-modules' (<code>M-x
customize-variables RET org-modules</code>) and make sure 'drill' is
+ticked. Org-drill will then be loaded when you restart Emacs or restart
+Org-mode.
+</p>
+<p>
+For manual installation, put the following in your <code>.emacs</code>. You
will also need
+to make sure that Org's "contrib/lisp" directory is in the emacs load-path.
+</p>
+
+
+
+<pre class="example">(require 'org-drill)
+</pre>
+
+
+
+
+</div>
+
+</div>
+
+<div id="outline-container-3" class="outline-2">
+<h2 id="sec-3">Demonstration </h2>
+<div class="outline-text-2" id="text-3">
+
+
+
+<p>
+Load the file <a href="spanish.html">spanish.org</a>. Press <code>M-x</code>
and run the function <code>org-drill</code>. Follow
+the prompts at the bottom of the screen.
+</p>
+<p>
+When the drill finishes, you can look at <code>spanish.org</code> to get some
idea of how
+drill topics are written.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-4" class="outline-2">
+<h2 id="sec-4">Writing the questions </h2>
+<div class="outline-text-2" id="text-4">
+
+
+
+<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 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>
+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.
+</p>
+<p>
+You don't need to schedule the topics initially. Unscheduled items are
+considered to be 'new' and ready for memorisation.
+</p>
+<p>
+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.
+</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. For this reason, some other card types are defined, including:
+</p><ul>
+<li><a href="#sec-4_4">Two-sided cards</a>
+</li>
+<li><a href="#sec-4_5">Multi-sided cards</a>
+</li>
+<li><a href="#sec-4_6">Multi-cloze cards</a>
+</li>
+<li><a href="#sec-4_7">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">
+<h3 id="sec-4_1">Simple topics </h3>
+<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
+contents hidden. So, you could include the question as text beneath the main
+heading, and the answer within a subheading. For example:
+</p>
+
+
+
+<pre class="example">* Item :drill:
+What is the capital city of Estonia?
+
+** The Answer
+Tallinn.
+</pre>
+
+
+
+<p>
+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.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-4_2" class="outline-3">
+<h3 id="sec-4_2">Cloze deletion </h3>
+<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
+below. To use cloze deletion, one or more parts of the body of the topic is
+marked as <i>cloze text</i> 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:
+</p>
+
+
+
+
+<pre class="example">* Item :drill:
+The capital city of Estonia is [Tallinn].
+</pre>
+
+
+
+<p>
+During review, the user will see:
+</p>
+<blockquote>
+
+<p>The capital city of Estonia is <font style="background-color: blue;"
color="cyan">
+<tt>[…]</tt></font>.
+</p>
+</blockquote>
+
+
+<p>
+When the user presses a key, the text "Tallinn" will become visible.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-4_3" class="outline-3">
+<h3 id="sec-4_3">Clozed text hints </h3>
+<div class="outline-text-3" id="text-4_3">
+
+
+
+<p>
+Clozed text can 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. During testing, the hint text will
+be visible when the rest of the text is hidden, and invisible when the rest of
+the text is visible.
+</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>[molecule…]</tt></font>
+and <font style="background-color: blue;" color="cyan">
+<tt>[cell type…]</tt></font>.
+</p>
+</blockquote>
+
+
+
+</div>
+
+</div>
+
+<div id="outline-container-4_4" class="outline-3">
+<h3 id="sec-4_4"><a name="Two-sided-cards" id="Two-sided-cards"></a>Two-sided
cards </h3>
+<div class="outline-text-3" id="text-4_4">
+
+
+<p>
+The remaining topic types all use the topic property,
<code>DRILL_CARD_TYPE</code>. This
+property tells <code>org-drill</code> which function to use to present the
topic during
+review. If this property has the value <code>twosided</code> then the topic is
treated as
+a "two sided card". When a two sided card is reviewed, <i>one of the first
two</i>
+subheadings within the topic will be visible – all other
+subheadings will be hidden.
+</p>
+<p>
+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).
+</p>
+<p>
+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.
+</p>
+
+
+
+<pre class="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?
+</pre>
+
+
+
+<p>
+In this example, the user will be shown the main text – "Translate this
word"
+– and either 'la mujer', <i>or</i> '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.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-4_5" class="outline-3">
+<h3 id="sec-4_5"><a name="Multi-sided-cards"
id="Multi-sided-cards"></a>Multi-sided cards </h3>
+<div class="outline-text-3" id="text-4_5">
+
+
+
+<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
+subheading is always shown and all others are always hidden.
+</p>
+
+
+
+<pre class="example">* Noun
:drill:
+ :PROPERTIES:
+ :DRILL_CARD_TYPE: multisided
+ :END:
+
+Translate.
+
+** Spanish
+la mesa
+
+** English
+the table
+
+** Picture
+[[file:table.jpg][PICTURE]]
+</pre>
+
+
+
+<p>
+The user will be shown the main text and either 'la mesa', <i>or</i> 'the
table',
+<i>or</i> a picture of a table.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-4_6" class="outline-3">
+<h3 id="sec-4_6"><a name="Multi-cloze-cards"
id="Multi-cloze-cards"></a>Multi-cloze cards </h3>
+<div class="outline-text-3" id="text-4_6">
+
+
+
+<p>
+Often, you will wish to create cards out of sentences that express several
+facts, such as the following:
+</p>
+
+
+
+<pre class="example">The capital city of New Zealand is Wellington, which is
located in the
+North Island and has a population of about 400,000.
+</pre>
+
+
+
+<p>
+There is more than one fact in this statement – you could create a single
+'simple' card with all the facts marked as cloze text, like so:
+</p>
+
+
+
+<pre class="example">The capital city of [New Zealand] is [Wellington], which
is located in
+the [North|North/South] Island and has a population of about [400,000].
+</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-8">leech</a>.
+</p>
+<p>
+A better way to express all these facts using 'simple' cards is to create
+several cards, with one fact per card. You might end up with something
+like this:
+</p>
+
+
+
+<pre class="example">* Fact
+The capital city of [New Zealand] is Wellington, 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.
+
+* Fact
+The capital city of New Zealand is Wellington, which has a population of
+about [400,000].
+
+* Fact
+The capital city of [New Zealand] is Wellington, which is located in the
+the North Island.
+
+* Fact
+The capital city of New Zealand is [Wellington], which is located in
+the North Island.
+
+* Fact
+The capital city of New Zealand is Wellington, which is located in
+the [North|North/South] Island.
+</pre>
+
+
+
+<p>
+However, this is really cumbersome. Multicloze card types exist for this
+situation. Multicloze cards behave like 'simple' cards, except that when there
+is more than one area marked as cloze text, some but not all of the areas
+can be hidden. There are several types of predefined multicloze card:
+</p>
+<ol>
+<li><code>hide1cloze</code> – one of the marked areas is hidden during
review; the others
+ all remain visible. The hidden text area is chosen randomly at each review.
+ (Note: this type used to be called 'multicloze', and that card type is
+ retained as a synonym for 'hide1cloze'.)
+</li>
+<li><code>show1cloze</code> – only one of the marked areas is visible
during review; all
+ the others are hidden. The hidden text area is chosen randomly at each
+ review.
+</li>
+<li><code>hide2cloze</code> – like hide1cloze, but 2 marked pieces of
text will be hidden,
+ and the rest will be visible.
+</li>
+<li><code>show2cloze</code> – like show1cloze, but 2 marked pieces of
text will be visible,
+ the rest are hidden.
+</li>
+</ol>
+
+
+<p>
+There are also some types of multicloze card where some pieces have an
+increased or decreased chance of being hidden. These are intended for use when
+studying languages: generally it is easy to translate a foreign-language
+sentence into your own language if you have met it before, but it is much
+harder to translate in the other direction. Therefore, you will want to test
+the harder direction more often.
+</p><ol>
+<li><code>hide1_firstmore</code> – only one of the marked pieces of text
will be
+ hidden. 75% of the time (guaranteed), the <i>first</i> piece is hidden; the
rest
+ of the time, one of the other pieces is randomly hidden.
+</li>
+<li><code>show1_firstless</code> – only one of the marked pieces of text
will be
+ visible. Only 25% of the time (guaranteed) will the <i>first</i> piece will
be
+ visible; the rest of the time, one of the other pieces is randomly visible.
+</li>
+<li><code>show1_lastmore</code> – only one of the marked pieces of text
will be
+ visible. 75% of the time (guaranteed), the <i>last</i> piece will be
visible;
+ the rest of the time, one of the other pieces is randomly visible.
+</li>
+</ol>
+
+
+<p>
+So, for the above example, we can actually use the original 'bad' simple card,
+but change its card type to 'hide1cloze'. Each time the card is presented for
+review, one of 'New Zealand', 'Wellington', 'the South Island' or '400,000'
+will be hidden.
+</p>
+
+
+
+<pre class="example">* Fact
+ :PROPERTIES:
+ :DRILL_CARD_TYPE: hide1cloze
+ :END:
+
+The capital city of [New Zealand] is [Wellington], which is located in
+the [North|North/South] Island and has a population of about [400,000].
+</pre>
+
+
+
+
+</div>
+
+</div>
+
+<div id="outline-container-4_7" class="outline-3">
+<h3 id="sec-4_7"><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_7">
+
+
+
+<p>
+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 examples,
see the
+functions at the end of org-drill.el – these include:
+</p><ul>
+<li><code>org-drill-present-verb-conjugation</code>, which implements the
'conjugate'
+ card type. This asks the user to conjugate a verb in a particular tense. It
+ demonstrates how the appearance of an entry can be completely altered during
+ a drill session, both during testing and during the display of the answer.
+</li>
+<li><code>org-drill-present-translate-number</code>, which uses a third-party
emacs lisp
+ library (<a
href="http://www.emacswiki.org/emacs/spell-number.el";>spell-number.el</a>) to
prompt the user to translate random numbers
+ to and from any language recognised by that library.
+</li>
+<li><code>org-drill-present-spanish-verb</code>, which defines the new topic
type
+ <code>spanish_verb</code>. This illustrates how a function can control which
of an
+ item's subheadings are visible during the drill session.
+</li>
+</ul>
+
+
+<p>
+See the file <a href="spanish.html">spanish.org</a> for a full set of example
material, including examples
+of all the card types discussed above.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-4_8" class="outline-3">
+<h3 id="sec-4_8">Empty cards </h3>
+<div class="outline-text-3" id="text-4_8">
+
+
+
+<p>
+If the body of a drill item is completely empty (ignoring properties and child
+items), then the item will be skipped during drill sessions. The purpose of
+this behaviour is to allow you to paste in 'skeletons' of complex items, then
+fill in missing information later. For example, you may wish to include an
+empty drill item for each tense of a newly learned verb, then paste in the
+actual conjugation later as you learn each tense.
+</p>
+<p>
+Note that if an item is empty, any child drill items will <b>not</b> be
ignored,
+unless they are empty as well.
+</p>
+<p>
+If you have an item with an empty body, but still want it to be included in a
+drill session, put a brief comment ('# …') in the item body.
+</p>
+
+</div>
+</div>
+
+</div>
+
+<div id="outline-container-5" class="outline-2">
+<h2 id="sec-5">Running the drill session </h2>
+<div class="outline-text-2" id="text-5">
+
+
+
+<p>
+Start a drill session with <code>M-x org-drill</code>. By default, this
includes all
+non-hidden topics in the current buffer. <code>org-drill</code> takes an
optional
+argument, SCOPE, which allows it to take drill items from other
+sources. See <a href="#sec-9_4">below</a> for details.
+</p>
+<p>
+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 <code>org-learn</code>):
+</p>
+<table border="2" cellspacing="0" cellpadding="6" rules="groups"
frame="hsides">
+<caption></caption>
+<colgroup><col class="right" /><col class="left" /><col class="left" /><col
class="left" />
+</colgroup>
+<thead>
+<tr><th scope="col" class="right">Quality</th><th scope="col"
class="left">SuperMemo label</th><th scope="col" class="left">Fail?</th><th
scope="col" class="left">Meaning</th></tr>
+</thead>
+<tbody>
+<tr><td class="right">0</td><td class="left">NULL</td><td
class="left">Yes</td><td class="left">Wrong, and the answer is unfamiliar when
you see it.</td></tr>
+<tr><td class="right">1</td><td class="left">BAD</td><td
class="left">Yes</td><td class="left">Wrong answer.</td></tr>
+<tr><td class="right">2</td><td class="left">FAIL</td><td
class="left">Yes</td><td class="left">Almost, but not quite correct.</td></tr>
+<tr><td class="right">3</td><td class="left">PASS</td><td
class="left">No</td><td class="left">Correct answer, but with much
effort.</td></tr>
+<tr><td class="right">4</td><td class="left">GOOD</td><td
class="left">No</td><td class="left">Correct answer, with a little
thought.</td></tr>
+<tr><td class="right">5</td><td class="left">BRIGHT</td><td
class="left">No</td><td class="left">Correct answer, effortless.</td></tr>
+</tbody>
+</table>
+
+
+<p>
+You can press '?' at the prompt if you have trouble remembering what the
+numbers 0–5 signify.
+</p>
+<p>
+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).
+</p>
+<p>
+After exiting the drill session with 'e' or 'q', you can resume where you left
+off, using the command <code>org-drill-resume</code>. 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
+<code>M-x org-drill-resume</code> and continue where you left off.
+</p>
+<p>
+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.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-6" class="outline-2">
+<h2 id="sec-6">Multiple sequential drill sessions </h2>
+<div class="outline-text-2" id="text-6">
+
+
+
+<p>
+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 <code>org-drill-again</code> 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.
+</p>
+<p>
+Also note that if you run <code>org-drill-resume</code> 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 <code>org-drill-again</code>).
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-7" class="outline-2">
+<h2 id="sec-7">Cram mode </h2>
+<div class="outline-text-2" id="text-7">
+
+
+
+<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-8" class="outline-2">
+<h2 id="sec-8"><a name="leeches" id="leeches"></a>Leeches </h2>
+<div class="outline-text-2" id="text-8">
+
+
+<p>
+From the Anki website, <a
href="http://ichi2.net/anki/wiki/Leeches";>http://ichi2.net/anki/wiki/Leeches</a>:
+</p>
+<blockquote>
+
+<p>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.
+</p>
+</blockquote>
+
+
+<p>
+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 <code>org-drill-leech-failure-threshold</code>
(15 by
+default). When you fail to remember an item more than this many times, the item
+will be given the <code>:leech:</code> tag.
+</p>
+<p>
+Leech items can be handled in one of three ways. You can choose how Org-Drill
+handles leeches by setting the variable <code>org-drill-leech-method</code> to
one of the
+following values:
+</p><dl>
+<dt>nil</dt><dd>Leech items are tagged with the <code>leech</code> tag, but
otherwise treated the
+ same as normal items.
+</dd>
+<dt>skip</dt><dd>Leech items are not included in drill sessions.
+</dd>
+<dt>warn</dt><dd>Leech items are still included in drill sessions, but a
warning
+ message is printed when each leech item is presented.
+</dd>
+</dl>
+
+
+<p>
+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.
+</p>
+<p>
+See <a href="http://www.supermemo.com/help/leech.htm";>the SuperMemo
website</a> for more on leeches.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-9" class="outline-2">
+<h2 id="sec-9">Customisation </h2>
+<div class="outline-text-2" id="text-9">
+
+
+
+<p>
+Org-Drill has several settings which you change using
+<code>M-x customize-group org-drill <RET></code>. Alternatively you can
change these
+settings by adding elisp code to your configuration file (<code>.emacs</code>).
+</p>
+
+
+</div>
+
+<div id="outline-container-9_1" class="outline-3">
+<h3 id="sec-9_1">Visual appearance of items during drill sessions </h3>
+<div class="outline-text-3" id="text-9_1">
+
+
+
+<p>
+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-9_2" class="outline-3">
+<h3 id="sec-9_2">Duration of drill sessions </h3>
+<div class="outline-text-3" id="text-9_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-9_3" class="outline-3">
+<h3 id="sec-9_3">Saving buffers after drill sessions </h3>
+<div class="outline-text-3" id="text-9_3">
+
+
+
+<p>
+By default, you will be prompted to save all unsaved buffers at the end of a
+drill session. If you don't like this behaviour, use the following setting:
+</p>
+
+
+
+<pre class="example">(setq org-drill-save-buffers-after-drill-sessions-p nil)
+</pre>
+
+
+
+
+</div>
+
+</div>
+
+<div id="outline-container-9_4" class="outline-3">
+<h3 id="sec-9_4"><a name="scope" id="scope"></a>Sources of items for drill
sessions (scope) </h3>
+<div class="outline-text-3" id="text-9_4">
+
+
+<p>
+By default, Org-Drill gathers drill items from the current buffer only,
+ignoring any non-visible items. There may be times when you want Org-Drill to
+gather drill items from other sources. You can do this by changing the value of
+the variable <code>org-drill-scope</code>. Possible values are:
+</p>
+<dl>
+<dt>file</dt><dd>The current buffer, ignoring hidden items. This is the
default.
+</dd>
+<dt>tree</dt><dd>The subtree starting with the entry at the cursor.
(Alternatively you
+ can use <code>M-x org=drill-tree</code> to run the drill session
– this will
+ behave the same as <code>org-drill</code> if 'tree' was used as the
value of
+ SCOPE.)
+</dd>
+<dt>file-no-restriction</dt><dd>The current buffer, including both hidden and
+ non-hidden items.
+</dd>
+<dt>file-with-archives</dt><dd>The current buffer, and any archives associated
with it.
+</dd>
+<dt>agenda</dt><dd>All agenda files.
+</dd>
+<dt>agenda-with-archives</dt><dd>All agenda files with any archive files
associated
+ with them.
+</dd>
+<dt>directory</dt><dd>All files with the extension '.org' in the same
directory as the
+ current file. (The current file will also be included if its
+ extension is .org)
+</dd>
+<dt>(file1 file2 …)</dt><dd>A list of filenames. All files in the list
will be
+ scanned.
+</dd>
+</dl>
+
+
+</div>
+
+</div>
+
+<div id="outline-container-9_5" class="outline-3">
+<h3 id="sec-9_5">Definition of old and overdue items </h3>
+<div class="outline-text-3" id="text-9_5">
+
+
+
+<p>
+Org-Drill prioritises <i>overdue</i> items in each drill session, presenting
them
+before other items are seen. Overdue items are defined in terms of how far in
+the past the item is scheduled for review. The threshold is defined in terms
+of a proportion rather than an absolute number of days. If days overdue is
+greater than
+</p>
+<pre class="example">
+last-interval * (factor - 1)
+</pre>
+
+
+<p>
+and is at least one day overdue, then the item is considered 'overdue'. The
+default factor is 1.2, meaning that the due date can overrun by 20% before the
+item is considered overdue.
+</p>
+<p>
+To change the factor that determines when items become overdue, use something
+like the following in your .emacs. Note that the value should never be less
+than 1.0.
+</p>
+
+
+
+<pre class="example">(setq org-drill-overdue-interval-factor 1.1)
+</pre>
+
+
+
+<p>
+After prioritising overdue items, Org-Drill next prioritises <i>young</i>
+items. These are items which were recently learned (or relearned in the case of
+a failure), and which therefore have short inter-repetition intervals.
+"Recent" is defined as an inter-repetition interval less than a fixed number of
+days, rather than a number of repetitions. This ensures that more difficult
+items are reviewed more often than easier items before they stop being 'young'.
+</p>
+<p>
+The default definition of a young item is one with an inter-repetition interval
+of 10 days or less. To change this, use the following:
+</p>
+
+
+
+<pre class="example">(setq org-drill-days-before-old 7)
+</pre>
+
+
+
+
+</div>
+
+</div>
+
+<div id="outline-container-9_6" class="outline-3">
+<h3 id="sec-9_6">Spaced repetition algorithm </h3>
+<div class="outline-text-3" id="text-9_6">
+
+
+
+
+</div>
+
+<div id="outline-container-9_6_1" class="outline-4">
+<h4 id="sec-9_6_1">Choice of algorithm </h4>
+<div class="outline-text-4" id="text-9_6_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 – 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-9_6_2" class="outline-4">
+<h4 id="sec-9_6_2">Random variation of repetition intervals </h4>
+<div class="outline-text-4" id="text-9_6_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-9_6_3" class="outline-4">
+<h4 id="sec-9_6_3">Adjustment for early or late review of items </h4>
+<div class="outline-text-4" id="text-9_6_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-9_6_4" class="outline-4">
+<h4 id="sec-9_6_4">Adjusting item difficulty globally </h4>
+<div class="outline-text-4" id="text-9_6_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="example">(setq org-drill-learn-fraction 0.45) ; change the value
as desired
+</pre>
+
+
+
+
+</div>
+</div>
+
+</div>
+
+<div id="outline-container-9_7" class="outline-3">
+<h3 id="sec-9_7"><a name="per-file-settings"
id="per-file-settings"></a>Per-file customisation settings </h3>
+<div class="outline-text-3" id="text-9_7">
+
+
+<p>
+Most of Org-Drill's customisation 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="example"># Local Variables:
+# org-drill-maximum-items-per-session: 50
+# org-drill-spaced-repetition-algorithm: simple8
+# End:
+</pre>
+
+
+
+<p>
+You can achieve the same effect by including the settings in the 'mode line'
+(this must be the <b>first line</b> in the file), like so:
+</p>
+
+
+
+<pre class="example"># -*- org-drill-maximum-items-per-session: 50;
org-drill-spaced-repetition-algorithm: simple8 -*-
+</pre>
+
+
+
+<p>
+In either case you will need to save, close and re-open the file for the
+changes to take effect.
+</p>
+
+</div>
+</div>
+
+</div>
+
+<div id="outline-container-10" class="outline-2">
+<h2 id="sec-10">Coping with large collections </h2>
+<div class="outline-text-2" id="text-10">
+
+
+
+<p>
+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.
+</p>
+<p>
+The easiest steps to solve this problem are:
+</p><ol>
+<li>Move your file into its own dedicated directory.
+</li>
+<li>Divide the file into two or more smaller files.
+</li>
+<li>Within each file, set <code>org-drill-scope</code> to 'directory'. See
+ <a href="#sec-9_7">per-file settings</a> above for instructions about how
to do this.
+</li>
+</ol>
+
+</div>
+
+</div>
+
+<div id="outline-container-11" class="outline-2">
+<h2 id="sec-11">Sharing, merging and synchronising item collections </h2>
+<div class="outline-text-2" id="text-11">
+
+
+
+<p>
+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.
+</p>
+<p>
+There are two commands that are useful in this regard:
+</p><ol>
+<li><code>org-drill-strip-all-data</code> - this command deletes all
user-specific
+ scheduling data from every item in the current collection. (It takes the
+ same optional 'scope' argument as <code>org-drill</code> 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.
+</li>
+<li><code>org-drill-merge-buffers</code> - 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.
+</li>
+</ol>
+
+
+<p>
+An example scenario:
+</p>
+<p>
+Tim decides to learn Swedish using an item collection (<code>.org</code> 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.
+</p>
+<p>
+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 <code>org-drill-merge-buffers</code> 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.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-12" class="outline-2">
+<h2 id="sec-12">Incremental reading </h2>
+<div class="outline-text-2" id="text-12">
+
+
+
+<p>
+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 <a href="http://www.supermemo.com/help/read.htm";>the SuperMemo
website</a> for more on incremental reading.
+</p>
+<p>
+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 <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 seems to be a bit
+more difficult. For Firefox, the <a href="http://www.wired-marker.org/";>Wired
Marker</a> 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 a couple of <code>org-capture</code>
templates for
+captured facts.
+</p>
+
+
+
+<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 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>
+<blockquote>
+
+<p>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.
+</p>
+</blockquote>
+
+
+<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 `interesting'
+portion of the text with the mouse:
+</p>
+<blockquote>
+
+<p>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>
+</p>
+</blockquote>
+
+
+<p>
+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>
+(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.)
+</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 each piece of text you selected
+has been turned into a drill item. Continuing the above example, you would see
+something like:
+</p>
+
+
+
+<pre class="example">** Fact: 'Tuberculosis - Wikipedia, the Free
Encyclopedia' :drill:
+
+Prevention relies on screening programs and vaccination, usually with Bacillus
+Calmette-Guérin vaccine.
+</pre>
+
+
+
+<p>
+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,
+usually with [Bacillus Calmette-Guérin vaccine].
+</pre>
+
+
+
+<p>
+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>
+
+</div>
+
+</div>
+
+<div id="outline-container-13" class="outline-2">
+<h2 id="sec-13">Author </h2>
+<div class="outline-text-2" id="text-13">
+
+
+<p>
+Org-Drill is written by Paul Sexton.
+</p>
+</div>
+</div>
+<div id="postamble">
+<p class="date">Date: 2011-05-21 00:08:14 NZST</p>
+<p class="creator">Org version 7.5 with Emacs version 23</p>
+<a href="http://validator.w3.org/check?uri=referer";>Validate XHTML 1.0</a>
+</div>
+</div>
+</body>
+</html>
diff --git a/org-drill.org b/org-drill.org
new file mode 100755
index 0000000000..0651e5f2a3
--- /dev/null
+++ b/org-drill.org
@@ -0,0 +1,919 @@
+# -*- mode: org; coding: utf-8-unix -*-
+#+TITLE: org-drill.el -- flashcards and spaced repetition for org-mode
+#+OPTIONS: num:nil ^:{} author:nil
+#+STARTUP: showall
+
+
+* General
+
+
+Org-Drill is an extension for [[http://orgmode.org/][Org mode]]. Org-Drill
uses a [[http://en.wikipedia.org/wiki/Spaced_repetition][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:
+- [[http://supermemo.com/index.htm][SuperMemo]] (see descriptions of the SM2,
SM5 and SM8 algorithms)
+- [[http://ichi2.net/anki/][Anki]]
+- [[http://mnemosyne-proj.org/index.php][Mnemosyne]]
+
+Org-Drill comes bundled with Org mode, in the "contrib" directory. Org-Drill
+also has its own repository, which is updated more regularly than the bundled
+version. The repository is at:
+
+http://bitbucket.org/eeeickythump/org-drill
+
+
+* Installation
+
+
+The easiest way is to customise the variable 'org-modules' (=M-x
+customize-variables RET org-modules=) and make sure 'drill' is
+ticked. Org-drill will then be loaded when you restart Emacs or restart
+Org-mode.
+
+For manual 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_EXAMPLE
+(require 'org-drill)
+#+END_EXAMPLE
+
+
+* 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 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:
+- [[Two-sided cards]]
+- [[Multi-sided cards]]
+- [[Multi-cloze cards]]
+- [[User-defined card types]]
+
+*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.
+
+
+** 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 is one of the specialised topic types discussed
+below. To use cloze deletion, one or more parts 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="cyan">
+@<tt>[...]@</tt>@</font>.
+#+END_QUOTE
+
+When the user presses a key, the text "Tallinn" will become visible.
+
+
+** Clozed text hints
+
+
+Clozed text can 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. During testing, the hint text will
+be visible when the rest of the text is hidden, and invisible when the rest of
+the text is visible.
+
+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
+# <<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
+# <<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 mesa', /or/ 'the table',
+/or/ a picture of a table.
+
+
+** Multi-cloze cards
+# <<Multi-cloze cards>>
+
+
+Often, you will wish to create cards out of sentences that express several
+facts, such as the following:
+
+#+BEGIN_EXAMPLE
+The capital city of New Zealand is Wellington, which is located in the
+North Island and has a population of about 400,000.
+#+END_EXAMPLE
+
+There is more than one fact in this statement -- you could create a single
+'simple' card with all the facts marked as cloze text, like so:
+
+#+BEGIN_EXAMPLE
+The capital city of [New Zealand] is [Wellington], which is located in
+the [North|North/South] Island and has a population of about [400,000].
+#+END_EXAMPLE
+
+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 [[leeches][leech]].
+
+A better way to express all these facts using 'simple' cards is to create
+several cards, with one fact per card. You might end up with something
+like this:
+
+#+BEGIN_EXAMPLE
+* Fact
+The capital city of [New Zealand] is Wellington, 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.
+
+* Fact
+The capital city of New Zealand is Wellington, which has a population of
+about [400,000].
+
+* Fact
+The capital city of [New Zealand] is Wellington, which is located in the
+the North Island.
+
+* Fact
+The capital city of New Zealand is [Wellington], which is located in
+the North Island.
+
+* Fact
+The capital city of New Zealand is Wellington, which is located in
+the [North|North/South] Island.
+#+END_EXAMPLE
+
+However, this is really cumbersome. Multicloze card types exist for this
+situation. Multicloze cards behave like 'simple' cards, except that when there
+is more than one area marked as cloze text, some but not all of the areas
+can be hidden. There are several types of predefined multicloze card:
+
+1. =hide1cloze= -- one of the marked areas is hidden during review; the others
+ all remain visible. The hidden text area is chosen randomly at each review.
+ (Note: this type used to be called 'multicloze', and that card type is
+ retained as a synonym for 'hide1cloze'.)
+2. =show1cloze= -- only one of the marked areas is visible during review; all
+ the others are hidden. The hidden text area is chosen randomly at each
+ review.
+3. =hide2cloze= -- like hide1cloze, but 2 marked pieces of text will be hidden,
+ and the rest will be visible.
+4. =show2cloze= -- like show1cloze, but 2 marked pieces of text will be
visible,
+ the rest are hidden.
+
+There are also some types of multicloze card where some pieces have an
+increased or decreased chance of being hidden. These are intended for use when
+studying languages: generally it is easy to translate a foreign-language
+sentence into your own language if you have met it before, but it is much
+harder to translate in the other direction. Therefore, you will want to test
+the harder direction more often.
+5. =hide1_firstmore= -- only one of the marked pieces of text will be
+ hidden. 75% of the time (guaranteed), the /first/ piece is hidden; the rest
+ of the time, one of the other pieces is randomly hidden.
+6. =show1_firstless= -- only one of the marked pieces of text will be
+ visible. Only 25% of the time (guaranteed) will the /first/ piece will be
+ visible; the rest of the time, one of the other pieces is randomly visible.
+7. =show1_lastmore= -- only one of the marked pieces of text will be
+ visible. 75% of the time (guaranteed), the /last/ piece will be visible;
+ the rest of the time, one of the other pieces is randomly visible.
+
+So, for the above example, we can actually use the original 'bad' simple card,
+but change its card type to 'hide1cloze'. Each time the card is presented for
+review, one of 'New Zealand', 'Wellington', 'the South Island' or '400,000'
+will be hidden.
+
+#+BEGIN_EXAMPLE
+* Fact
+ :PROPERTIES:
+ :DRILL_CARD_TYPE: hide1cloze
+ :END:
+
+The capital city of [New Zealand] is [Wellington], which is located in
+the [North|North/South] Island and has a population of about [400,000].
+#+END_EXAMPLE
+
+
+** User-defined card types
+# <<User-defined card types>>
+
+
+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
+=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 examples, see the
+functions at the end of org-drill.el -- these include:
+- =org-drill-present-verb-conjugation=, which implements the 'conjugate'
+ card type. This asks the user to conjugate a verb in a particular tense. It
+ demonstrates how the appearance of an entry can be completely altered during
+ a drill session, both during testing and during the display of the answer.
+- =org-drill-present-translate-number=, which uses a third-party emacs lisp
+ library
([[http://www.emacswiki.org/emacs/spell-number.el][spell-number.el]]) to prompt
the user to translate random numbers
+ to and from any language recognised by that library.
+- =org-drill-present-spanish-verb=, which defines the new topic type
+ =spanish_verb=. This illustrates how a function can control which of an
+ item's subheadings are visible during the drill session.
+
+See the file [[file:spanish.org][spanish.org]] for a full set of example
material, including examples
+of all the card types discussed above.
+
+
+** Empty cards
+
+
+If the body of a drill item is completely empty (ignoring properties and child
+items), then the item will be skipped during drill sessions. The purpose of
+this behaviour is to allow you to paste in 'skeletons' of complex items, then
+fill in missing information later. For example, you may wish to include an
+empty drill item for each tense of a newly learned verb, then paste in the
+actual conjugation later as you learn each tense.
+
+Note that if an item is empty, any child drill items will *not* be ignored,
+unless they are empty as well.
+
+If you have an item with an empty body, but still want it to be included in a
+drill session, put a brief comment ('# ...') in the item body.
+
+
+* 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. See [[scope][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=):
+
+| Quality | SuperMemo label | Fail? | Meaning
|
+|---------+-----------------+-------+------------------------------------------------------|
+| 0 | NULL | Yes | Wrong, and the answer is unfamiliar when
you see it. |
+| 1 | BAD | Yes | Wrong answer.
|
+| 2 | FAIL | Yes | Almost, but not quite correct.
|
+| 3 | PASS | No | Correct answer, but with much effort.
|
+| 4 | GOOD | No | Correct answer, with a little thought.
|
+| 5 | BRIGHT | No | 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 (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.
+
+
+* Multiple sequential drill sessions
+
+
+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=).
+
+
+* Cram mode
+
+
+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=).
+
+
+* Leeches
+# <<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.
+
+
+* Customisation
+
+
+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=).
+
+
+** Visual appearance of items during drill sessions
+
+
+If you want cloze-deleted text to show up in a special font within Org mode
+buffers, add this to your .emacs:
+
+#+BEGIN_EXAMPLE
+(setq org-drill-use-visible-cloze-face-p t)
+#+END_EXAMPLE
+
+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:
+
+#+BEGIN_EXAMPLE
+(setq org-drill-hide-item-headings-p t)
+#+END_EXAMPLE
+
+
+** Duration of drill sessions
+
+
+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.
+
+#+BEGIN_EXAMPLE
+(setq org-drill-maximum-items-per-session 40)
+(setq org-drill-maximum-duration 30) ; 30 minutes
+#+END_EXAMPLE
+
+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 /all/ outstanding items have been reviewed.
+
+
+** Saving buffers after drill sessions
+
+
+By default, you will be prompted to save all unsaved buffers at the end of a
+drill session. If you don't like this behaviour, use the following setting:
+
+#+BEGIN_EXAMPLE
+(setq org-drill-save-buffers-after-drill-sessions-p nil)
+#+END_EXAMPLE
+
+
+** Sources of items for drill sessions (scope)
+# <<scope>>
+
+By default, Org-Drill gathers drill items from the current buffer only,
+ignoring any non-visible items. There may be times when you want Org-Drill to
+gather drill items from other sources. You can do this by changing the value of
+the variable =org-drill-scope=. Possible values are:
+
+- file :: The current buffer, ignoring hidden items. This is the default.
+- tree :: The subtree starting with the entry at the cursor. (Alternatively you
+ can use =M-x org=drill-tree= to run the drill session -- this will
+ behave the same as =org-drill= if 'tree' was used as the value of
+ SCOPE.)
+- file-no-restriction :: 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.
+- directory :: All files with the extension '.org' in the same directory as the
+ current file. (The current file will also be included if its
+ extension is .org)
+- (file1 file2 ...) :: A list of filenames. All files in the list will be
+ scanned.
+
+
+
+** Definition of old and overdue items
+
+
+Org-Drill prioritises /overdue/ items in each drill session, presenting them
+before other items are seen. Overdue items are defined in terms of how far in
+the past the item is scheduled for review. The threshold is defined in terms
+of a proportion rather than an absolute number of days. If days overdue is
+greater than
+
+: last-interval * (factor - 1)
+
+and is at least one day overdue, then the item is considered 'overdue'. The
+default factor is 1.2, meaning that the due date can overrun by 20% before the
+item is considered overdue.
+
+To change the factor that determines when items become overdue, use something
+like the following in your .emacs. Note that the value should never be less
+than 1.0.
+
+#+BEGIN_EXAMPLE
+(setq org-drill-overdue-interval-factor 1.1)
+#+END_EXAMPLE
+
+After prioritising overdue items, Org-Drill next prioritises /young/
+items. These are items which were recently learned (or relearned in the case of
+a failure), and which therefore have short inter-repetition intervals.
+"Recent" is defined as an inter-repetition interval less than a fixed number of
+days, rather than a number of repetitions. This ensures that more difficult
+items are reviewed more often than easier items before they stop being 'young'.
+
+The default definition of a young item is one with an inter-repetition interval
+of 10 days or less. To change this, use the following:
+
+#+BEGIN_EXAMPLE
+(setq org-drill-days-before-old 7)
+#+END_EXAMPLE
+
+
+** Spaced repetition algorithm
+
+
+*** Choice of algorithm
+
+
+Org-Drill supports three different spaced repetition algorithms, all based on
+SuperMemo algorithms. These are:
+- [[http://www.supermemo.com/english/ol/sm2.htm][SM2]] :: an early algorithm,
used in SuperMemo 2.0 (1988), which remains very
+ popular -- 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.
+- [[http://www.supermemo.com/english/ol/sm5.htm][SM5]] (default) :: 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.
+- Simple8 :: an experimental algorithm based on the
[[http://www.supermemo.com/english/algsm8.htm][SM8]] 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'.
+
+
+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
+
+
+*** Random variation of repetition intervals
+
+
+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
+
+
+*** Adjustment for early or late review of items
+
+
+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:
+
+#+BEGIN_EXAMPLE
+(setq org-drill-adjust-intervals-for-early-and-late-repetitions-p t)
+#+END_EXAMPLE
+
+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.
+
+
+*** Adjusting item difficulty globally
+
+
+The =learn fraction= is a global value which affects how quickly the intervals
+(times between each retest of an item) increase with successive repetitions,
+for /all/ 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.
+
+
+| Repetition | F=0.3 | F=0.4 | *F=0.5* | F=0.6 | F=0.7 |
+|------------+-------+-------+---------+-------+-------|
+| 1st | 2 | 2 | 2 | 2 | 2 |
+| 2nd | 7 | 7 | 7 | 7 | 7 |
+| 5th | 26 | 34 | 46 | 63 | 85 |
+| 10th | 85 | 152 | 316 | 743 | 1942 |
+| 15th | 233 | 501 | 1426 | 5471 | 27868 |
+
+To alter the learn fraction, put the following in your .emacs:
+
+#+BEGIN_EXAMPLE
+(setq org-drill-learn-fraction 0.45) ; change the value as desired
+#+END_EXAMPLE
+
+
+** Per-file customisation settings
+# <<per-file settings>>
+
+Most of Org-Drill's customisation 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:
+
+#+BEGIN_EXAMPLE
+# Local Variables:
+# org-drill-maximum-items-per-session: 50
+# org-drill-spaced-repetition-algorithm: simple8
+# End:
+#+END_EXAMPLE
+
+You can achieve the same effect by including the settings in the 'mode line'
+(this must be the *first line* in the file), like so:
+
+#+BEGIN_EXAMPLE
+# -*- org-drill-maximum-items-per-session: 50;
org-drill-spaced-repetition-algorithm: simple8 -*-
+#+END_EXAMPLE
+
+In either case you will need to save, close and re-open the file for the
+changes to take effect.
+
+
+* Coping with large collections
+
+
+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
+ [[per-file settings]] above for instructions about how to do this.
+
+
+* Sharing, merging and synchronising item collections
+
+
+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.
+
+
+* 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 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 seems to be a bit
+more difficult. For Firefox, the [[http://www.wired-marker.org/][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.
+
+#+BEGIN_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...
+ ))
+#+END_EXAMPLE
+
+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
[[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 `interesting'
+portion of the text with the mouse:
+
+#+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 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:
+
+#+BEGIN_EXAMPLE
+** Fact: 'Tuberculosis - Wikipedia, the Free Encyclopedia' :drill:
+
+Prevention relies on screening programs and vaccination, usually with Bacillus
+Calmette-Guérin vaccine.
+#+END_EXAMPLE
+
+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.
+
+
+* Author
+
+Org-Drill is written by Paul Sexton.
+
- [nongnu] elpa/org-drill 6dc1b90f21 050/251: Added tag 2.3.5 for changeset 872dde6580f6, (continued)
- [nongnu] elpa/org-drill 6dc1b90f21 050/251: Added tag 2.3.5 for changeset 872dde6580f6, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 9cb409a1ba 012/251: * New command: 'M-x org-drill-cram'. "Cram Mode" is the same as an ordinary drill session, except, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 5749d5bb7a 057/251: Contents of entry drawers are now hidden while displaying answers., ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 79a0ac93ae 058/251: Hide entry drawers when showing answers for verb conjugation and noun, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 93545edb91 063/251: Added tag 2.3.8 for changeset a8cade42f59c, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 8b6e230886 065/251: Added ability to define arbitrary left and right cloze delimiters (strings),, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill b17bf579bd 039/251: - New card types: show2cloze, hide1_firstmore, show1_firstless, show1_lastmore. See docs for details., ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 9487fd21f8 002/251: Added special card type for spanish verbs, to demonstrate custom card types., ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 5040d0e6d2 014/251: Added tag 1.4 for changeset 2e4735840112, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill e698616493 026/251: - More robust handling of the situation where we resume a drill session but, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill e7ffd8e6eb 040/251: Renamed documentation file and fixed a few typos.,
ELPA Syncer <=
- [nongnu] elpa/org-drill 063e8035a8 071/251: - Ignore cloze markings if they occur inside Org source blocks, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 663a1ee3f3 079/251: Clarified that org-drill is licensed under GPL v3., ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 8a9192cc2f 080/251: Persistence of the optimal factor matrix across application sessions is now, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill cfe271d824 062/251: Fixed: org-drill-strip-all-data now works again (was using obsolete arguments, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 09f7bc5c9b 083/251: Backout changeset 5d9b61ea5a181eb282e4069c17cbdf00e4325726, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill f9a217faa1 052/251: Wrapped all calls to 'org-display-inline-images' in 'ignore-errors', to prevent, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill d0405e9311 060/251: Fixed bug with scheduling failed cards, caused by changes to 'org-schedule' in, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill e43199b988 056/251: Changed permissions on some files., ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 4114c541a7 082/251: You can now customise the keys for the 'quit', 'edit', 'tags', 'help' and, ELPA Syncer, 2022/01/17
- [nongnu] elpa/org-drill 8c374c0998 091/251: Merged in Fuco/org-drill/fix-input (pull request #3), ELPA Syncer, 2022/01/17