diff options
| author | eeeickythump <devnull@localhost> | 2011-05-21 00:10:34 +1200 |
|---|---|---|
| committer | eeeickythump <devnull@localhost> | 2011-05-21 00:10:34 +1200 |
| commit | 1c77d6cf3ace2de1e9c6b7b6f53ec2a93935ee6a (patch) | |
| tree | 3383dfbc2b341b17a417c80a72c21c3673c7e35d /README.html | |
| parent | e7ffd8e6eb290bd2053e100a483ddd9e012dcb33 (diff) | |
| download | org-drill-1c77d6cf3ace2de1e9c6b7b6f53ec2a93935ee6a.tar.gz org-drill-1c77d6cf3ace2de1e9c6b7b6f53ec2a93935ee6a.zip | |
Removed old doc files (renamed).2.3.2
Diffstat (limited to 'README.html')
| -rwxr-xr-x | README.html | 1551 |
1 files changed, 0 insertions, 1551 deletions
diff --git a/README.html b/README.html deleted file mode 100755 index 91836c6..0000000 --- a/README.html +++ /dev/null @@ -1,1551 +0,0 @@ -<?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</title> -<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/> -<meta name="generator" content="Org-mode"/> -<meta name="generated" content="2011-05-20 23:13:33 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</h1> - -<div id="table-of-contents"> -<h2>Table of Contents</h2> -<div id="text-table-of-contents"> -<ul> -<li><a href="#sec-1">Synopsis </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> -</ul> -</div> -</div> - -<div id="outline-container-1" class="outline-2"> -<h2 id="sec-1">Synopsis </h2> -<div class="outline-text-2" id="text-1"> - - - -<p> -Org-Drill is an extension for <a href="http://www.gnu.org/software/emacs/">GNU Emacs</a> <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 fed back to <code>org-learn</code> 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> -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 mujer', <i>or</i> 'the woman', -<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 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="postamble"> -<p class="date">Date: 2011-05-20 23:13:33 NZST</p> -<p class="author">Author: Paul Sexton</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> |