Browse Source

added org-drill

Inderjit Gill 6 months ago
parent
commit
0effce06d5

+ 6
- 0
external/org-drill/.hg_archival.txt View File

@@ -0,0 +1,6 @@
1
+repo: 8c5cef7fcc4ca63926318e0b731821976460e22b
2
+node: 01b05cd7561ad69e5ec9c1200414d4fa128c9a17
3
+branch: default
4
+latesttag: 2.6.1
5
+latesttagdistance: 2
6
+changessincelatesttag: 2

+ 34
- 0
external/org-drill/.hgtags View File

@@ -0,0 +1,34 @@
1
+a3f5efca0221bb1b0f8dc1136f8213b3f6563148 1.0
2
+bc740455003b3e425424274731cca27f8e16abe9 1.1
3
+c8dd87db2ce14859de03c6bd6898dcc896f3a33f 1.3
4
+2e4735840112ee8592e0cf71f7bc03ea9bfb35d3 1.4
5
+42f3700bc7484d63284115b5dd7021199277aad5 1.5
6
+6ff8dd70c108318a5fff81f15ad95a30a27d6f14 1.6
7
+16cafa21aef0bed04d0543128600e49a95c95953 2.0
8
+da0c515d1d391c46e8b37a66d4dca1c22b809d43 2.1
9
+60b0a80ce97a23a94712195efd721425bcd65bf8 2.1.1
10
+d9430f6647c94222d259c00f6b6ab0625517fe79 2.2
11
+b5d5b9f5c20312be328d550508657844bf629f2c 2.3
12
+566cf446fdae83db66fee6878241f1ef88913f65 2.3.1
13
+4e43f149ea974feb6a43368adfa775e66ccbc5b4 2.3.2
14
+e68b52fe88ac8acccdd7268131a30c9aff1b48d5 2.3.3
15
+e68b52fe88ac8acccdd7268131a30c9aff1b48d5 2.3.3
16
+1b0cc92cbb6a07f2a4aa05286dd2ce2d54157a12 2.3.3
17
+e472512f0be78795906ddd7302bcfab3759d63a8 2.3.4
18
+872dde6580f635cc6a55f247d46313d75c89e6e5 2.3.5
19
+a8cade42f59cd41ca789bc2fb907aa27d5c31a98 2.3.8
20
+37dd8ae06dede018192905050c2234106bace0c6 2.4.0
21
+97f51d64df4552f2fb9e0565b3d39ad39429fd29 2.4.1
22
+648125435aad1e6f2e3eab85585260bab989dc8e 2.4.2
23
+c289780f11d70d1f6890686d1ce2402d9b3b2a3d 2.4.3
24
+0571437aa238c958b0878a1da1d5654b258613b9 2.4.4
25
+69dde321b38c660ce2987429a057b437334bf831 2.4.5
26
+e7bb422d8cb1c8708deb780215f5eaac0e6ae262 2.4.6
27
+552ec72921546097a0bd527dc9694681e073af5b 2.4.7
28
+080a526cc34afe80658fceb65f53320834ab8152 2.4.8
29
+355c056422088c32d561e6495e4eb8a50ae2fad7 2.4.9
30
+2d622b26469cf7527992201e33eeac3bd608b862 2.4.10
31
+97921372f286b6df22a3260eb70ae0018259b4e1 2.5
32
+7a8df02a7ffc9288dca4f8add80b5ab2983e93ee 2.5.1
33
+f96493b0ba4a25d12015fe4bdbe58e06ac311ba5 2.6
34
+58692054854719e72f6e79cb8b6c1157f6859292 2.6.1

+ 950
- 0
external/org-drill/README.md View File

@@ -0,0 +1,950 @@
1
+# Introduction
2
+
3
+Org-Drill is an extension for [Org mode](http://orgmode.org/). Org-Drill uses a [spaced repetition](http://en.wikipedia.org/wiki/Spaced_repetition)
4
+algorithm to conduct interactive "drill sessions", using org files as sources
5
+of facts to be memorised. Each topic is treated as a "flash card". The material
6
+to be remembered is presented to the student in random order. The student rates
7
+his or her recall of each item, and this information is used to schedule the
8
+item for later revision.
9
+
10
+Each drill session can be restricted to topics in the current buffer
11
+(default), one or several files, all agenda files, or a subtree. A single
12
+topic can also be drilled.
13
+
14
+Different "topic types" can be defined, which present their information to the
15
+student in different ways.
16
+
17
+For more on the spaced repetition algorithm, and examples of other programs
18
+that use it, see:
19
+
20
+-   [SuperMemo](http://supermemo.com/index.htm) (see descriptions of the SM2, SM5 and SM8 algorithms)
21
+-   [Anki](http://ichi2.net/anki/)
22
+-   [Mnemosyne](http://mnemosyne-proj.org/index.php)
23
+
24
+Org-Drill comes bundled with Org mode, in the "contrib" directory. Org-Drill
25
+also has its own repository, which is updated more regularly than the bundled
26
+version. The repository is at:
27
+
28
+<http://bitbucket.org/eeeickythump/org-drill>
29
+
30
+# Installation
31
+
32
+The easiest way is to customise the variable `org-modules` (`M-x
33
+customize-variables RET org-modules`) and make sure 'drill' is
34
+ticked. Org-drill will then be loaded when you restart Emacs or restart
35
+Org-mode.
36
+
37
+For manual installation, put the following in your `.emacs`. You will also need
38
+to make sure that Org's "contrib/lisp" directory is in the emacs load-path.
39
+
40
+    (require 'org-drill)
41
+
42
+# Demonstration
43
+
44
+Load the file 'spanish.org'. Press `M-x` and run the function `org-drill`. Follow
45
+the prompts at the bottom of the screen.
46
+
47
+When the drill finishes, you can look at 'spanish.org' to get some idea of how
48
+drill topics are written.
49
+
50
+# Writing the questions
51
+
52
+Org-Drill uses org mode topics as 'drill items'. To be used as a drill item,
53
+the topic must have a tag that matches the value of
54
+`org-drill-question-tag`. This is `:drill:` by default. Any other org topics
55
+will be ignored.
56
+
57
+Drill items can have other drill items as children. When a drill item is being
58
+tested, the contents of any child drill items will be hidden.
59
+
60
+You don't need to schedule the topics initially.  Unscheduled items are
61
+considered to be 'new' and ready for memorisation.
62
+
63
+How should 'drill topics' be structured? Any org topic is a legal drill topic
64
+&#x2013; it will simply be shown with all subheadings collapsed, so that only the
65
+material beneath the main item heading is visible. After pressing a key, any
66
+hidden subheadings will be revealed, and you will be asked to rate your
67
+"recall" of the item.
68
+
69
+This will be adequate for some items, but usually you will want to write items
70
+where you have more control over what information is hidden from the user for
71
+recall purposes. For this reason, some other card types are defined, including:
72
+
73
+-   Two-sided cards
74
+-   Multi-sided cards
75
+-   Multi-cloze cards
76
+-   User-defined card types
77
+
78
+**A note about comments:** In org mode, comment lines start with '#'. The rest of
79
+the line is ignored by Org (apart from some special cases). You may sometimes
80
+want to put material in comments which you do not want to see when you are
81
+being tested on the item. For this reason, comments are always rendered
82
+invisible while items are being tested.
83
+
84
+## Simple topics
85
+
86
+The simplest drill topic has no special structure. When such a topic is
87
+presented during a drill session, any subheadings are "collapsed" with their
88
+contents hidden. So, you could include the question as text beneath the main
89
+heading, and the answer within a subheading. For example:
90
+
91
+	* Item                                   :drill:
92
+	What is the capital city of Estonia?
93
+	
94
+	** The Answer
95
+	Tallinn.
96
+
97
+When this item is presented for review, the text beneath the main heading will
98
+be visible, but the contents of the subheading ("The Answer") will be hidden.
99
+
100
+## Cloze deletion
101
+
102
+Cloze deletion can be used in any drill topic regardless of whether it is
103
+otherwise 'simple', or is one of the specialised topic types discussed
104
+below. To use cloze deletion, one or more parts of the body of the topic is
105
+marked as *cloze text* by surrounding it with single square brackets, [like
106
+so]. When the topic is presented for review, the text within square brackets
107
+will be obscured. The text is then revealed after the user presses a key. For
108
+example:
109
+
110
+	* Item                                   :drill:
111
+	The capital city of Estonia is [Tallinn].
112
+
113
+During review, the user will see:
114
+
115
+> The capital city of Estonia is <font style="background-color: blue;" color="cyan">
116
+> <tt>[&#x2026;]</tt></font>.
117
+
118
+When the user presses a key, the text "Tallinn" will become visible.
119
+
120
+## Clozed text hints
121
+
122
+Clozed text can contain a "hint" about the answer. If the text surrounded
123
+by single square brackets contains \`||' (two vertical bars), all text
124
+after that character is treated as a hint. During testing, the hint text will
125
+be visible when the rest of the text is hidden, and invisible when the rest of
126
+the text is visible.
127
+
128
+Example:
129
+
130
+    Type 1 hypersensitivity reactions are mediated by [immunoglobulin E||molecule]
131
+    and [mast cells||cell type].
132
+
133
+> Type 1 hypersensitivity reactions are mediated by
134
+> <font style="background-color: blue;" color="cyan">
135
+> <tt>[molecule&#x2026;]</tt></font>
136
+> and <font style="background-color: blue;" color="cyan">
137
+> <tt>[cell type&#x2026;]</tt></font>.
138
+
139
+## Two-sided cards
140
+
141
+
142
+The remaining topic types all use the topic property, `DRILL_CARD_TYPE`. This
143
+property tells `org-drill` which function to use to present the topic during
144
+review. If this property has the value `twosided` then the topic is treated as
145
+a "two sided card". When a two sided card is reviewed, *one of the first two*
146
+subheadings within the topic will be visible &#x2013; all other
147
+subheadings will be hidden.
148
+
149
+Two-sided cards are meant to emulate the type of flipcard where either side is
150
+useful as test material (for example, a card with a word in a foreign language
151
+on one side, and its translation on the other).
152
+
153
+A two sided card can have more than 2 subheadings, but all subheadings after
154
+the first two are considered as "notes" and will always be hidden during topic
155
+review.
156
+
157
+	* Noun                                               :drill:
158
+	    :PROPERTIES:
159
+	    :DRILL_CARD_TYPE: twosided
160
+	    :END:
161
+	
162
+	Translate this word.
163
+	
164
+	** Spanish
165
+	la mujer
166
+	
167
+	** English
168
+	the woman
169
+	
170
+	** Example sentence
171
+	¿Quién fue esa mujer?
172
+	Who was that woman?
173
+
174
+In this example, the user will be shown the main text &#x2013; "Translate this word"
175
+&#x2013; and either 'la mujer', *or* 'the woman', at random. The section 'Example
176
+sentence' will never be shown until after the user presses a key, because it is
177
+not one of the first two 'sides' of the topic.
178
+
179
+## Multi-sided cards
180
+
181
+
182
+The `multisided` card type is similar to `twosided`, except that any
183
+subheading has a chance of being presented during the topic review. One
184
+subheading is always shown and all others are always hidden.
185
+
186
+	* Noun                                               :drill:
187
+	    :PROPERTIES:
188
+	    :DRILL_CARD_TYPE: multisided
189
+	    :END:
190
+	
191
+	Translate.
192
+	
193
+	** Spanish
194
+	la mesa
195
+	
196
+	** English
197
+	the table
198
+	
199
+	** Picture
200
+	[[file:table.jpg][PICTURE]]
201
+
202
+The user will be shown the main text and either 'la mesa', *or* 'the table',
203
+*or* a picture of a table.
204
+
205
+## Multi-cloze cards
206
+
207
+
208
+Often, you will wish to create cards out of sentences that express several
209
+facts, such as the following:
210
+
211
+    The capital city of New Zealand is Wellington, which is located in the
212
+    North Island and has a population of about 400,000.
213
+
214
+There is more than one fact in this statement &#x2013; you could create a single
215
+'simple' card with all the facts marked as cloze text, like so:
216
+
217
+    The capital city of [New Zealand] is [Wellington], which is located in
218
+    the [North||North/South] Island and has a population of about [400,000].
219
+
220
+But this card will be difficult to remember. If you get just one of the 4
221
+hidden facts wrong, you will fail the card. A card like this is likely to
222
+become a leech.
223
+
224
+A better way to express all these facts using 'simple' cards is to create
225
+several cards, with one fact per card. You might end up with something
226
+like this:
227
+
228
+	* Fact
229
+	The capital city of [New Zealand] is Wellington, which has a population of
230
+	about 400,000.
231
+	
232
+	* Fact
233
+	The capital city of New Zealand is [Wellington], which has a population of
234
+	about 400,000.
235
+	
236
+	* Fact
237
+	The capital city of New Zealand is Wellington, which has a population of
238
+	about [400,000].
239
+	
240
+	* Fact
241
+	The capital city of [New Zealand] is Wellington, which is located in the
242
+	the North Island.
243
+	
244
+	* Fact
245
+	The capital city of New Zealand is [Wellington], which is located in
246
+	the North Island.
247
+	
248
+	* Fact
249
+	The capital city of New Zealand is Wellington, which is located in
250
+	the [North||North/South] Island.
251
+
252
+However, this is really cumbersome. Multicloze card types exist for this
253
+situation. Multicloze cards behave like 'simple' cards, except that when there
254
+is more than one area marked as cloze text, some but not all of the areas
255
+can be hidden. There are several types of predefined multicloze card:
256
+
257
+1.  `hide1cloze` &#x2013; one of the marked areas is hidden during review; the others
258
+    all remain visible. The hidden text area is chosen randomly at each review.
259
+    (Note: this type used to be called 'multicloze', and that card type is
260
+    retained as a synonym for 'hide1cloze'.)
261
+2.  `show1cloze` &#x2013; only one of the marked areas is visible during review; all
262
+    the others are hidden. The hidden text area is chosen randomly at each
263
+    review.
264
+3.  `hide2cloze` &#x2013; like hide1cloze, but 2 marked pieces of text will be hidden,
265
+    and the rest will be visible.
266
+4.  `show2cloze` &#x2013; like show1cloze, but 2 marked pieces of text will be visible,
267
+    the rest are hidden.
268
+
269
+There are also some types of multicloze card where some pieces have an
270
+increased or decreased chance of being hidden. These are intended for use when
271
+studying languages: generally it is easy to translate a foreign-language
272
+sentence into your own language if you have met it before, but it is much
273
+harder to translate in the other direction. Therefore, you will want to test
274
+the harder direction more often.
275
+
276
+1.  `hide1_firstmore` &#x2013; only one of the marked pieces of text will be
277
+    hidden. 75% of the time (guaranteed), the *first* piece is hidden; the rest
278
+    of the time, one of the other pieces is randomly hidden.
279
+2.  `show1_firstless` &#x2013; only one of the marked pieces of text will be
280
+    visible. Only 25% of the time (guaranteed) will the *first* piece will be
281
+    visible; the rest of the time, one of the other pieces is randomly visible.
282
+3.  `show1_lastmore` &#x2013; only one of the marked pieces of text will be
283
+    visible. 75% of the time (guaranteed), the *last* piece will be visible;
284
+    the rest of the time, one of the other pieces is randomly visible.
285
+
286
+So, for the above example, we can actually use the original 'bad' simple card,
287
+but change its card type to 'hide1cloze'. Each time the card is presented for
288
+review, one of 'New Zealand', 'Wellington', 'the North Island' or '400,000'
289
+will be hidden.
290
+
291
+	* Fact
292
+	  :PROPERTIES:
293
+	  :DRILL_CARD_TYPE: hide1cloze
294
+	  :END:
295
+	
296
+	The capital city of [New Zealand] is [Wellington], which is located in
297
+	the [North||North/South] Island and has a population of about [400,000].
298
+
299
+## User-defined card types
300
+
301
+Finally, you can write your own emacs lisp functions to define new kinds of
302
+topics. Any new topic type will need to be added to
303
+`org-drill-card-type-alist`, and cards using that topic type will need to have
304
+it as the value of their `DRILL_CARD_TYPE` property. For examples, see the
305
+functions at the end of org-drill.el &#x2013; these include:
306
+
307
+-   `org-drill-present-verb-conjugation`, which implements the 'conjugate'
308
+    card type. This asks the user to conjugate a verb in a particular tense. It
309
+    demonstrates how the appearance of an entry can be completely altered during
310
+    a drill session, both during testing and during the display of the answer.
311
+-   `org-drill-present-translate-number`, which uses a third-party emacs lisp
312
+    library ([spell-number.el](http://www.emacswiki.org/emacs/spell-number.el)) to prompt the user to translate random numbers
313
+    to and from any language recognised by that library.
314
+-   `org-drill-present-spanish-verb`, which defines the new topic type
315
+    `spanish_verb`. This illustrates how a function can control which of an
316
+    item's subheadings are visible during the drill session.
317
+
318
+See the file [spanish.org](spanish.md) for a full set of example material, including examples
319
+of all the card types discussed above.
320
+
321
+## Empty cards
322
+
323
+If the body of a drill item is completely empty (ignoring properties and child
324
+items), then the item will be skipped during drill sessions. The purpose of
325
+this behaviour is to allow you to paste in 'skeletons' of complex items, then
326
+fill in missing information later. For example, you may wish to include an
327
+empty drill item for each tense of a newly learned verb, then paste in the
328
+actual conjugation later as you learn each tense.
329
+
330
+Note that if an item is empty, any child drill items will **not** be ignored,
331
+unless they are empty as well.
332
+
333
+If you have an item with an empty body, but still want it to be included in a
334
+drill session, you can either:
335
+
336
+1.  Put a brief comment ('# &#x2026;')  in the item body.
337
+2.  Change the entry for its card type in `org-drill-card-type-alist` so that
338
+    items of this type will always be tested, even if they have an empty body.
339
+    See the documentation for `org-drill-card-type-alist` for details.
340
+
341
+# Running the drill session
342
+
343
+Start a drill session with `M-x org-drill`. By default, this tests all
344
+non-hidden topics in the current buffer. `org-drill` takes an optional
345
+argument, SCOPE, which allows it to take drill items from other
346
+sources. See below for details.
347
+
348
+During a drill session, you will be presented with each item, then asked to
349
+rate your recall of it by pressing a key between 0 and 5. The meaning of these
350
+numbers is (taken from `org-learn`):
351
+
352
+<table>
353
+
354
+
355
+<colgroup>
356
+<col  class="right">
357
+
358
+<col  class="left">
359
+
360
+<col  class="left">
361
+
362
+<col  class="left">
363
+</colgroup>
364
+<thead>
365
+<tr>
366
+<th scope="col" class="right">Quality</th>
367
+<th scope="col" class="left">SuperMemo label</th>
368
+<th scope="col" class="left">Fail?</th>
369
+<th scope="col" class="left">Meaning</th>
370
+</tr>
371
+</thead>
372
+
373
+<tbody>
374
+<tr>
375
+<td class="right">0</td>
376
+<td class="left">NULL</td>
377
+<td class="left">Yes</td>
378
+<td class="left">Wrong, and the answer is unfamiliar when you see it.</td>
379
+</tr>
380
+
381
+
382
+<tr>
383
+<td class="right">1</td>
384
+<td class="left">BAD</td>
385
+<td class="left">Yes</td>
386
+<td class="left">Wrong answer.</td>
387
+</tr>
388
+
389
+
390
+<tr>
391
+<td class="right">2</td>
392
+<td class="left">FAIL</td>
393
+<td class="left">Yes</td>
394
+<td class="left">Almost, but not quite correct.</td>
395
+</tr>
396
+
397
+
398
+<tr>
399
+<td class="right">3</td>
400
+<td class="left">PASS</td>
401
+<td class="left">No</td>
402
+<td class="left">Correct answer, but with much effort.</td>
403
+</tr>
404
+
405
+
406
+<tr>
407
+<td class="right">4</td>
408
+<td class="left">GOOD</td>
409
+<td class="left">No</td>
410
+<td class="left">Correct answer, with a little thought.</td>
411
+</tr>
412
+
413
+
414
+<tr>
415
+<td class="right">5</td>
416
+<td class="left">BRIGHT</td>
417
+<td class="left">No</td>
418
+<td class="left">Correct answer, effortless.</td>
419
+</tr>
420
+</tbody>
421
+</table>
422
+
423
+You can press '?'  at the prompt if you have trouble remembering what the
424
+numbers 0-5 signify.
425
+
426
+At any time you can press 'q' to finish the drill early (your progress up to
427
+that point will be saved), 's' to skip the current item without viewing the
428
+answer, or 'e' to escape from the drill and jump to the current topic for
429
+editing (again, your progress up to that point will be saved).
430
+
431
+After exiting the drill session with 'e' or 'q', you can resume where you left
432
+off, using the command `org-drill-resume`. This will return you to the item
433
+that you were viewing when you left the session. For example, if you are shown
434
+an item and realise that it is poorly formulated, or contains an error, you can
435
+press 'e' to leave the drill, then correct the item, then press
436
+`M-x org-drill-resume` and continue where you left off.
437
+
438
+Note that 'drastic' edits, such as deleting or moving items, can sometimes
439
+cause Org-Drill to "lose its place" in the file, preventing it from
440
+successfully resuming the session. In that case you will need to start a new
441
+session.
442
+
443
+# Multiple sequential drill sessions
444
+
445
+Org-Drill has to scan your entire item database each time you start a new drill
446
+session. This can be slow if you have a large item collection. If you have a
447
+large number of 'due' items and want to run a second drill session after
448
+finishing one session, you can use the command `org-drill-again` to run a new
449
+drill session that draws from the pool of remaining due items that were not
450
+tested during the previous session, without re-scanning the item collection.
451
+
452
+Also note that if you run `org-drill-resume` and you have actually finished the
453
+drill session, you will be asked whether you want to start another drill
454
+session without re-scanning (as if you had run `org-drill-again`).
455
+
456
+# Cram mode
457
+
458
+There are some situations, such as before an exam, where you will want to
459
+revise all of your cards regardless of when they are next due for review.
460
+
461
+To do this, run a *cram session* with the `org-drill-cram` command (`M-x
462
+org-drill-cram`). This works the same as a normal drill session, except
463
+that all items are considered due for review unless you reviewed them within
464
+the last 12 hours (you can change the number of hours by customising the
465
+variable `org-drill-cram-hours`).
466
+
467
+Cram sessions are not considered to be part of the normal learning process for
468
+the tested items. Cramming will not affect when items are next due for
469
+revision.
470
+
471
+# Leeches
472
+
473
+
474
+From the Anki website, <http://ichi2.net/anki/wiki/Leeches>:
475
+
476
+> Leeches are cards that you keep on forgetting. Because they require so many
477
+> reviews, they take up a lot more of your time than other cards.
478
+
479
+Like Anki, Org-Drill defines leeches as cards that you have "failed" many
480
+times. The number of times an item must be failed before it is considered a
481
+leech is set by the variable `org-drill-leech-failure-threshold` (15 by
482
+default). When you fail to remember an item more than this many times, the item
483
+will be given the `:leech:` tag.
484
+
485
+Leech items can be handled in one of three ways. You can choose how Org-Drill
486
+handles leeches by setting the variable `org-drill-leech-method` to one of the
487
+following values:
488
+
489
+-   **nil:** Leech items are tagged with the `leech` tag, but otherwise treated the
490
+    same as normal items.
491
+-   **skip:** Leech items are not included in drill sessions.
492
+-   **warn:** Leech items are still included in drill sessions, but a warning
493
+    message is printed when each leech item is presented.
494
+
495
+The best way to deal with a leech is either to delete it, or reformulate it so
496
+that it is easier to remember, for example by splitting it into more than one
497
+card.
498
+
499
+See [the SuperMemo website](http://www.supermemo.com/help/leech.htm) for more on leeches.
500
+
501
+# Customisation
502
+
503
+Org-Drill has several settings which you change using
504
+`M-x customize-group org-drill <RET>`. Alternatively you can change these
505
+settings by adding elisp code to your configuration file (`.emacs`).
506
+
507
+## Visual appearance of items during drill sessions
508
+
509
+If you want cloze-deleted text to show up in a special font within Org mode
510
+buffers, add this to your .emacs:
511
+
512
+    (setq org-drill-use-visible-cloze-face-p t)
513
+
514
+Item headings may contain information that "gives away" the answer to the item,
515
+either in the heading text or in tags. If you want item headings to be made
516
+invisible while each item is being tested, add:
517
+
518
+    (setq org-drill-hide-item-headings-p t)
519
+
520
+## Duration of drill sessions
521
+
522
+By default, a drill session will end when either 30 items have been
523
+successfully reviewed, or 20 minutes have passed. To change this behaviour, use
524
+the following settings.
525
+
526
+    (setq org-drill-maximum-items-per-session 40)
527
+    (setq org-drill-maximum-duration 30)   ; 30 minutes
528
+
529
+If either of these variables is set to nil, then item count or elapsed time
530
+will not count as reasons to end the session. If both variables are nil, the
531
+session will not end until *all* outstanding items have been reviewed.
532
+
533
+## Saving buffers after drill sessions
534
+
535
+By default, you will be prompted to save all unsaved buffers at the end of a
536
+drill session. If you don't like this behaviour, use the following setting:
537
+
538
+    (setq org-drill-save-buffers-after-drill-sessions-p nil)
539
+
540
+## Sources of items for drill sessions (scope)
541
+
542
+
543
+By default, Org-Drill gathers drill items from the current buffer only,
544
+ignoring any non-visible items. There may be times when you want Org-Drill to
545
+gather drill items from other sources. You can do this by changing the value of
546
+the variable `org-drill-scope`. Possible values are:
547
+
548
+-   **file:** The current buffer, ignoring hidden items. This is the default.
549
+-   **tree:** The subtree starting with the entry at the cursor. (Alternatively you
550
+    can use `M-x org=drill-tree` to run the drill session &#x2013; this will
551
+    behave the same as `org-drill` if 'tree' was used as the value of
552
+    SCOPE.)
553
+-   **file-no-restriction:** The current buffer, including both hidden and
554
+    non-hidden items.
555
+-   **file-with-archives:** The current buffer, and any archives associated with it.
556
+-   **agenda:** All agenda files.
557
+-   **agenda-with-archives:** All agenda files with any archive files associated
558
+    with them.
559
+-   **directory:** All files with the extension '.org' in the same directory as the
560
+    current file. (The current file will also be included if its
561
+    extension is .org)
562
+-   **(file1 file2 &#x2026;):** A list of filenames. All files in the list will be
563
+    scanned.
564
+
565
+## Definition of old and overdue items
566
+
567
+Org-Drill prioritises *overdue* items in each drill session, presenting them
568
+before other items are seen. Overdue items are defined in terms of how far in
569
+the past the item is scheduled for review. The threshold is defined in terms
570
+of a proportion rather than an absolute number of days. If days overdue is
571
+greater than
572
+
573
+    last-interval * (factor - 1)
574
+
575
+and is at least one day overdue, then the item is considered 'overdue'. The
576
+default factor is 1.2, meaning that the due date can overrun by 20% before the
577
+item is considered overdue.
578
+
579
+To change the factor that determines when items become overdue, use something
580
+like the following in your .emacs. Note that the value should never be less
581
+than 1.0.
582
+
583
+    (setq org-drill-overdue-interval-factor 1.1)
584
+
585
+After prioritising overdue items, Org-Drill next prioritises *young*
586
+items. These are items which were recently learned (or relearned in the case of
587
+a failure), and which therefore have short inter-repetition intervals.
588
+"Recent" is defined as an inter-repetition interval less than a fixed number of
589
+days, rather than a number of repetitions. This ensures that more difficult
590
+items are reviewed more often than easier items before they stop being 'young'.
591
+
592
+The default definition of a young item is one with an inter-repetition interval
593
+of 10 days or less. To change this, use the following:
594
+
595
+    (setq org-drill-days-before-old 7)
596
+
597
+## Spaced repetition algorithm
598
+
599
+### Choice of algorithm
600
+
601
+Org-Drill supports three different spaced repetition algorithms, all based on
602
+SuperMemo algorithms. These are:
603
+
604
+-   **[SM2](http://www.supermemo.com/english/ol/sm2.htm):** an early algorithm, used in SuperMemo 2.0 (1988), which remains very
605
+    popular &#x2013; Anki and Mnemosyne, two of the most popular spaced repetition
606
+    programs, use SM2. This algorithm stores an 'ease factor' for each item,
607
+    which is modified each time you rate your recall of the item.
608
+-   **[SM5](http://www.supermemo.com/english/ol/sm5.htm) (default):** used in SuperMemo 5.0 (1989). This algorithm uses 'ease
609
+    factors' but also uses a persistent, per-user 'matrix of optimal factors'
610
+    which is also modified after each item repetition.
611
+-   **Simple8:** an experimental algorithm based on the [SM8](http://www.supermemo.com/english/algsm8.htm) algorithm. SM8 is used
612
+    in SuperMemo 8.0 (1998) and is almost identical to SM11 which is
613
+    used in SuperMemo 2002. Like SM5, it uses a matrix of optimal
614
+    factors. Simple8 differs from SM8 in that it does not adapt the
615
+    matrix to the individual user, though it does adapt each item's
616
+    'ease factor'.
617
+
618
+If you want Org-Drill to use the `SM2` algorithm, put the following in your
619
+`.emacs`:
620
+
621
+    (setq org-drill-spaced-repetition-algorithm 'sm2)
622
+
623
+### Random variation of repetition intervals
624
+
625
+The intervals generated by the SM2 and SM5 algorithms are pretty
626
+deterministic. If you tend to add items in large, infrequent batches, the lack
627
+of variation in interval scheduling can lead to the problem of "lumpiness" &#x2013;
628
+one day a large batch of items are due for review, the next there is almost
629
+nothing, a few days later another big pile of items is due, and so on.
630
+
631
+This problem can be ameliorated by adding some random "noise" to the interval
632
+scheduling algorithm. The author of SuperMemo actually recommends this approach
633
+for the SM5 algorithm, and Org-Drill's implementation uses [his code](http://www.supermemo.com/english/ol/sm5.htm).
634
+
635
+To enable random "noise" for item intervals, set the variable
636
+`org-drill-add-random-noise-to-intervals-p` to true by putting the following in
637
+your `.emacs`:
638
+
639
+    (setq org-drill-add-random-noise-to-intervals-p t)
640
+
641
+### Adjustment for early or late review of items
642
+
643
+Reviewing items earlier or later than their scheduled review date may affect
644
+how soon the next review date should be scheduled. Code to make this adjustment
645
+is also presented on the SuperMemo website. It can be enabled with:
646
+
647
+    (setq org-drill-adjust-intervals-for-early-and-late-repetitions-p t)
648
+
649
+This will affect both early and late repetitions if the Simple8 algorithm is
650
+used. For the SM5 algorithm it will affect early repetitions only. It has no
651
+effect on the SM2 algorithm.
652
+
653
+### Adjusting the first interval (SM5 algorithm only)
654
+
655
+In the SM5 algorithm, the initial interval after the first successful
656
+presentation of an item is *always* 4 days. If you wish to change this for some
657
+reason, you can do so with:
658
+
659
+    (setq org-drill-sm5-initial-interval 5.0)
660
+
661
+note that this will have no effect if you are not using the SM5 algorithm.
662
+
663
+### Adjusting item difficulty globally
664
+
665
+The `learn fraction` is a global value which affects how quickly the intervals
666
+(times between each retest of an item) increase with successive repetitions,
667
+for *all* items. The default value is 0.5, and this is the value used in
668
+SuperMemo. For some collections of information, you may find that you are
669
+reviewing items too often (they are too easy and the workload is too high), or
670
+too seldom (you are failing them too often). In these situations, it is
671
+possible to alter the learn fraction from its default in order to increase or
672
+decrease the frequency of repetition of items over time. Increasing the value
673
+will make the time intervals grow faster, and lowering it will make them grow
674
+more slowly. The table below shows the growth in intervals (in days) with some
675
+different values of the learn fraction (F). The table assumes that the item is
676
+successfully recalled each time, with an average quality of just under 4.
677
+
678
+<table>
679
+
680
+
681
+<colgroup>
682
+<col  class="left">
683
+
684
+<col  class="right">
685
+
686
+<col  class="right">
687
+
688
+<col  class="right">
689
+
690
+<col  class="right">
691
+
692
+<col  class="right">
693
+</colgroup>
694
+<thead>
695
+<tr>
696
+<th scope="col" class="left">Repetition</th>
697
+<th scope="col" class="right">F=0.3</th>
698
+<th scope="col" class="right">F=0.4</th>
699
+<th scope="col" class="right">**F=0.5**</th>
700
+<th scope="col" class="right">F=0.6</th>
701
+<th scope="col" class="right">F=0.7</th>
702
+</tr>
703
+</thead>
704
+
705
+<tbody>
706
+<tr>
707
+<td class="left">1st</td>
708
+<td class="right">2</td>
709
+<td class="right">2</td>
710
+<td class="right">2</td>
711
+<td class="right">2</td>
712
+<td class="right">2</td>
713
+</tr>
714
+
715
+
716
+<tr>
717
+<td class="left">2nd</td>
718
+<td class="right">7</td>
719
+<td class="right">7</td>
720
+<td class="right">7</td>
721
+<td class="right">7</td>
722
+<td class="right">7</td>
723
+</tr>
724
+
725
+
726
+<tr>
727
+<td class="left">5th</td>
728
+<td class="right">26</td>
729
+<td class="right">34</td>
730
+<td class="right">46</td>
731
+<td class="right">63</td>
732
+<td class="right">85</td>
733
+</tr>
734
+
735
+
736
+<tr>
737
+<td class="left">10th</td>
738
+<td class="right">85</td>
739
+<td class="right">152</td>
740
+<td class="right">316</td>
741
+<td class="right">743</td>
742
+<td class="right">1942</td>
743
+</tr>
744
+
745
+
746
+<tr>
747
+<td class="left">15th</td>
748
+<td class="right">233</td>
749
+<td class="right">501</td>
750
+<td class="right">1426</td>
751
+<td class="right">5471</td>
752
+<td class="right">27868</td>
753
+</tr>
754
+</tbody>
755
+</table>
756
+
757
+To alter the learn fraction, put the following in your .emacs:
758
+
759
+    (setq org-drill-learn-fraction 0.45)   ; change the value as desired
760
+
761
+## Per-file customisation settings
762
+
763
+
764
+Most of Org-Drill's customisation settings are safe as file-local
765
+variables. This means you can include a commented section like this at the end
766
+of your .org file to apply special settings when running a Drill session using
767
+that file:
768
+
769
+    # Local Variables:
770
+    # org-drill-maximum-items-per-session:    50
771
+    # org-drill-spaced-repetition-algorithm:  simple8
772
+    # End:
773
+
774
+You can achieve the same effect by including the settings in the 'mode line'
775
+(this must be the **first line** in the file), like so:
776
+
777
+    # -*- org-drill-maximum-items-per-session: 50; org-drill-spaced-repetition-algorithm: simple8 -*-
778
+
779
+In either case you will need to reload the file for the changes to take effect.
780
+
781
+# Coping with large collections
782
+
783
+If you keep all your items in a single file, it may eventually get very
784
+large. The file will be slow to load, and Emacs may have trouble
785
+syntax-highlighting the file contents correctly.
786
+
787
+The easiest way to solve this problem is:
788
+
789
+1.  Move your file into its own dedicated directory.
790
+2.  Divide the file into two or more smaller files.
791
+3.  Within each file, set `org-drill-scope` to 'directory'. See
792
+    above for instructions about how to do this.
793
+
794
+# Sharing, merging and synchronising item collections
795
+
796
+Every drill item is automatically given a persistent unique "ID" the first time
797
+it is seen by Org-Drill. This means that if two different people subsequently
798
+edit or reschedule that item, Org-Drill can still tell that it is the same
799
+item. This in turn means that collections of items can be shared and edited in
800
+a collaborative manner.
801
+
802
+There are two commands that are useful in this regard:
803
+
804
+1.  `org-drill-strip-all-data` - this command deletes all user-specific
805
+    scheduling data from every item in the current collection. (It takes the
806
+    same optional 'scope' argument as `org-drill` to define which items will
807
+    be processed by the command). User-specific data includes scheduling dates,
808
+    ease factors, number of failures and repetitions, and so on. All items are
809
+    reset to 'new' status. This command is useful if you want to share your
810
+    item collection with someone else.
811
+2.  `org-drill-merge-buffers` - When called from buffer A, it prompts you for
812
+    another buffer (B), which must also be loaded into Emacs. This command
813
+    imports all the user-specific scheduling data from buffer B into buffer A,
814
+    and deletes any such information in A. Matching items are identified by
815
+    their ID. Any items in B that do not exist in A are copied to A, in
816
+    the same hierarchical location if all the parent headings exist, otherwise
817
+    at the end of the buffer.
818
+
819
+An example scenario:
820
+
821
+Tim decides to learn Swedish using an item collection (`.org` file) made
822
+publically available by Jane.  (Before publishing it Jane used
823
+'org-drill-strip-all-data' to remove her personal scheduling data from the
824
+collection.)  A few weeks later, Jane updates her collection, adding new items
825
+and revising some old ones. Tim downloads the new collection and imports his
826
+progress from his copy of the old collection, using 'org-drill-merge-buffers',
827
+using the new collection as buffer A and the old one as buffer B. He can then
828
+discard the old copy. Any items HE added to HIS copy of the old collection
829
+(buffer B) will not be lost &#x2013; they will be appended to his copy of the new
830
+collection.
831
+
832
+Of course the sharing does not need to be 'public'. You and a friend might be
833
+learning a language or some other topic together. You each maintain a card
834
+collection. Periodically your friend sends you a copy of their collection &#x2013;
835
+you run `org-drill-merge-buffers` on it, always using your own collection as
836
+buffer B so that your own scheduling progress is carried over. Other times you
837
+send your friend a copy of your collection, and he or she follows the same
838
+procedure.
839
+
840
+# Incremental reading
841
+
842
+An innovative feature of the program SuperMemo is so-called "incremental
843
+reading". This refers to the ability to quickly and easily make drill items
844
+from selected portions of text as you read an article (a web page for
845
+example). See [the SuperMemo website](http://www.supermemo.com/help/read.htm) for more on incremental reading.
846
+
847
+Much of the infrastructure for incremental reading is already provided by Org
848
+Mode, with the help of some other emacs packages. You can provide yourself with
849
+an incremental reading facility by using 'org-capture' alongside a package that
850
+allows you to browse web pages either in emacs (w3 or [emacs-w3m](http://www.emacswiki.org/emacs/emacs-w3m)) or in the
851
+external browser of your choice ([org-protocol](http://orgmode.org/worg/org-contrib/org-protocol.php)).
852
+
853
+Another important component of incremental reading is the ability to save your
854
+exact place in a document, so you can read it *incrementally* rather than all
855
+at once. There is a large variety of bookmarking packages for emacs which
856
+provide advanced bookmarking functionality: see the [Emacs Wiki](http://www.emacswiki.org/emacs/BookMarks) for details.
857
+Bookmarking exact webpage locations in an external browser seems to be a bit
858
+more difficult. For Firefox, the [Wired Marker](http://www.wired-marker.org/) addon works well.
859
+
860
+An example of using Org-Drill for incremental reading is given below. First,
861
+and most importantly, we need to define a couple of `org-capture` templates for
862
+captured facts.
863
+
864
+    (setq org-capture-templates
865
+           `(("u"
866
+             "Task: Read this URL"
867
+             entry
868
+             (file+headline "tasks.org" "Articles To Read")
869
+             ,(concat "* TODO Read article: '%:description'\nURL: %c\n\n")
870
+             :empty-lines 1
871
+             :immediate-finish t)
872
+    
873
+            ("w"
874
+             "Capture web snippet"
875
+             entry
876
+             (file+headline "my-facts.org" "Inbox")
877
+             ,(concat "* Fact: '%:description'        :"
878
+                      (format "%s" org-drill-question-tag)
879
+                      ":\n:PROPERTIES:\n:DATE_ADDED: %u\n:SOURCE_URL: %c\n:END:\n\n%i\n%?\n")
880
+             :empty-lines 1
881
+             :immediate-finish t)
882
+            ;; ...other capture templates...
883
+        ))
884
+
885
+Using these templates and `org-protocol`, you can set up buttons in your web
886
+browser to:
887
+-   Create a task telling you to read the URL of the currently viewed webpage
888
+-   Turn a region of selected text on a webpage, into a new fact which is saved
889
+    to whichever file and heading you nominate in the template. The fact will
890
+    contain a timestamp, and a hyperlink back to the webpage where you created
891
+    it.
892
+
893
+For example, suppose you are reading the Wikipedia entry on tuberculosis [here](http://en.wikipedia.org/wiki/Tuberculosis).
894
+
895
+You read the following:
896
+
897
+> The classic symptoms of tuberculosis are a chronic cough with blood-tinged
898
+> sputum, fever, night sweats, and weight loss. Infection of other organs causes
899
+> a wide range of symptoms. Treatment is difficult and requires long courses of
900
+> multiple antibiotics. Antibiotic resistance is a growing problem in
901
+> (extensively) multi-drug-resistant tuberculosis. Prevention relies on screening
902
+> programs and vaccination, usually with Bacillus Calmette-Guérin vaccine.
903
+
904
+You decide you want to remember that "Bacillus Calmette-Guérin vaccine" is the
905
+name of the vaccine against tuberculosis. First, you select the \`interesting'
906
+portion of the text with the mouse:
907
+
908
+> The classic symptoms of tuberculosis are a chronic cough with blood-tinged
909
+> sputum, fever, night sweats, and weight loss. Infection of other organs causes
910
+> a wide range of symptoms. Treatment is difficult and requires long courses of
911
+> multiple antibiotics. Antibiotic resistance is a growing problem in
912
+> (extensively) multi-drug-resistant tuberculosis.
913
+> <font style="background-color: yellow;">Prevention relies
914
+> on screening programs and vaccination, usually with Bacillus Calmette-Guérin
915
+> vaccine.</font>
916
+
917
+Then you press the button you created when setting up `org-protocol`, which is
918
+configured to activate the capture template "w: Capture web snippet". The
919
+selected text will be sent to Emacs, turned into a new fact using the template,
920
+and filed away for your later attention.
921
+
922
+(Note that it might be more efficient to turn the entire paragraph into a drill
923
+item &#x2013; since it contains several important facts &#x2013; then split it up into
924
+multiple items when you edit it later in Emacs.)
925
+
926
+Once you have had enough of reading the article, save your place, then go to
927
+your "fact" file in Emacs. You should see that each piece of text you selected
928
+has been turned into a drill item. Continuing the above example, you would see
929
+something like:
930
+
931
+	** Fact: 'Tuberculosis - Wikipedia, the Free Encyclopedia'        :drill:
932
+	
933
+	Prevention relies on screening programs and vaccination, usually with Bacillus
934
+	Calmette-Guérin vaccine.
935
+
936
+You need to edit this fact so it makes sense independent of its context, as
937
+that is how it will be presented to you in future. The easiest way to turn the
938
+text into a 'question' is by cloze deletion. All you need to do is surround the
939
+'hidden' parts of the text with square brackets.
940
+
941
+    Prevention of tuberculosis relies on screening programs and vaccination,
942
+    usually with [Bacillus Calmette-Guérin vaccine].
943
+
944
+You can of course define browser buttons that use several different "fact"
945
+templates, each of which might send its fact to a different file or subheading,
946
+or give it different tags or properties, for example.
947
+
948
+# Author
949
+
950
+Org-Drill is written by Paul Sexton.

BIN
external/org-drill/apple.jpg View File


+ 3496
- 0
external/org-drill/org-drill.el
File diff suppressed because it is too large
View File


+ 1604
- 0
external/org-drill/org-drill.html
File diff suppressed because it is too large
View File


+ 939
- 0
external/org-drill/org-drill.org View File

@@ -0,0 +1,939 @@
1
+# -*- mode: org; coding: utf-8-unix -*-
2
+#+TITLE: org-drill.el -- flashcards and spaced repetition for org-mode
3
+#+OPTIONS: num:nil ^:{} author:nil
4
+#+STARTUP: showall
5
+
6
+
7
+* General
8
+
9
+
10
+Org-Drill is an extension for [[http://orgmode.org/][Org mode]]. Org-Drill uses a [[http://en.wikipedia.org/wiki/Spaced_repetition][spaced repetition]]
11
+algorithm to conduct interactive "drill sessions", using org files as sources
12
+of facts to be memorised. Each topic is treated as a "flash card". The material
13
+to be remembered is presented to the student in random order. The student rates
14
+his or her recall of each item, and this information is used to schedule the
15
+item for later revision.
16
+
17
+Each drill session can be restricted to topics in the current buffer
18
+(default), one or several files, all agenda files, or a subtree. A single
19
+topic can also be drilled.
20
+
21
+Different "topic types" can be defined, which present their information to the
22
+student in different ways.
23
+
24
+For more on the spaced repetition algorithm, and examples of other programs
25
+that use it, see:
26
+- [[http://supermemo.com/index.htm][SuperMemo]] (see descriptions of the SM2, SM5 and SM8 algorithms)
27
+- [[http://ichi2.net/anki/][Anki]]
28
+- [[http://mnemosyne-proj.org/index.php][Mnemosyne]]
29
+
30
+Org-Drill comes bundled with Org mode, in the "contrib" directory. Org-Drill
31
+also has its own repository, which is updated more regularly than the bundled
32
+version. The repository is at:
33
+
34
+http://bitbucket.org/eeeickythump/org-drill
35
+
36
+
37
+* Installation
38
+
39
+
40
+The easiest way is to customise the variable 'org-modules' (=M-x
41
+customize-variables RET org-modules=) and make sure 'drill' is
42
+ticked. Org-drill will then be loaded when you restart Emacs or restart
43
+Org-mode.
44
+
45
+For manual installation, put the following in your =.emacs=. You will also need
46
+to make sure that Org's "contrib/lisp" directory is in the emacs load-path.
47
+
48
+#+BEGIN_EXAMPLE
49
+(require 'org-drill)
50
+#+END_EXAMPLE
51
+
52
+
53
+* Demonstration
54
+
55
+
56
+Load the file [[file:spanish.org][spanish.org]]. Press =M-x= and run the function =org-drill=. Follow
57
+the prompts at the bottom of the screen.
58
+
59
+When the drill finishes, you can look at =spanish.org= to get some idea of how
60
+drill topics are written.
61
+
62
+
63
+* Writing the questions
64
+
65
+
66
+Org-Drill uses org mode topics as 'drill items'. To be used as a drill item,
67
+the topic must have a tag that matches the value of
68
+=org-drill-question-tag=. This is =:drill:= by default. Any other org topics
69
+will be ignored.
70
+
71
+Drill items can have other drill items as children. When a drill item is being
72
+tested, the contents of any child drill items will be hidden.
73
+
74
+You don't need to schedule the topics initially.  Unscheduled items are
75
+considered to be 'new' and ready for memorisation.
76
+
77
+How should 'drill topics' be structured? Any org topic is a legal drill topic
78
+-- it will simply be shown with all subheadings collapsed, so that only the
79
+material beneath the main item heading is visible. After pressing a key, any
80
+hidden subheadings will be revealed, and you will be asked to rate your
81
+"recall" of the item.
82
+
83
+This will be adequate for some items, but usually you will want to write items
84
+where you have more control over what information is hidden from the user for
85
+recall purposes. For this reason, some other card types are defined, including:
86
+- [[Two-sided cards]]
87
+- [[Multi-sided cards]]
88
+- [[Multi-cloze cards]]
89
+- [[User-defined card types]]
90
+
91
+*A note about comments:* In org mode, comment lines start with '#'. The rest of
92
+the line is ignored by Org (apart from some special cases). You may sometimes
93
+want to put material in comments which you do not want to see when you are
94
+being tested on the item. For this reason, comments are always rendered
95
+invisible while items are being tested.
96
+
97
+
98
+** Simple topics
99
+
100
+
101
+The simplest drill topic has no special structure. When such a topic is
102
+presented during a drill session, any subheadings are "collapsed" with their
103
+contents hidden. So, you could include the question as text beneath the main
104
+heading, and the answer within a subheading. For example:
105
+
106
+#+BEGIN_EXAMPLE
107
+* Item                                   :drill:
108
+What is the capital city of Estonia?
109
+
110
+** The Answer
111
+Tallinn.
112
+#+END_EXAMPLE
113
+
114
+When this item is presented for review, the text beneath the main heading will
115
+be visible, but the contents of the subheading ("The Answer") will be hidden.
116
+
117
+
118
+** Cloze deletion
119
+
120
+
121
+Cloze deletion can be used in any drill topic regardless of whether it is
122
+otherwise 'simple', or is one of the specialised topic types discussed
123
+below. To use cloze deletion, one or more parts of the body of the topic is
124
+marked as /cloze text/ by surrounding it with single square brackets, [like
125
+so]. When the topic is presented for review, the text within square brackets
126
+will be obscured. The text is then revealed after the user presses a key. For
127
+example:
128
+
129
+
130
+#+BEGIN_EXAMPLE
131
+* Item                                   :drill:
132
+The capital city of Estonia is [Tallinn].
133
+#+END_EXAMPLE
134
+
135
+During review, the user will see:
136
+
137
+#+BEGIN_QUOTE
138
+The capital city of Estonia is @<font style="background-color: blue;" color="cyan">
139
+@<tt>[...]@</tt>@</font>.
140
+#+END_QUOTE
141
+
142
+When the user presses a key, the text "Tallinn" will become visible.
143
+
144
+
145
+** Clozed text hints
146
+
147
+
148
+Clozed text can contain a "hint" about the answer. If the text surrounded
149
+by single square brackets contains `||' (two vertical bars), all text
150
+after that character is treated as a hint. During testing, the hint text will
151
+be visible when the rest of the text is hidden, and invisible when the rest of
152
+the text is visible.
153
+
154
+Example:
155
+
156
+#+BEGIN_EXAMPLE
157
+Type 1 hypersensitivity reactions are mediated by [immunoglobulin E||molecule]
158
+and [mast cells||cell type].
159
+#+END_EXAMPLE
160
+
161
+#+BEGIN_QUOTE
162
+Type 1 hypersensitivity reactions are mediated by
163
+@<font style="background-color: blue;" color="cyan">
164
+@<tt>[molecule...]@</tt>@</font>
165
+and @<font style="background-color: blue;" color="cyan">
166
+@<tt>[cell type...]@</tt>@</font>.
167
+#+END_QUOTE
168
+
169
+
170
+** Two-sided cards
171
+# <<Two-sided cards>>
172
+
173
+The remaining topic types all use the topic property, =DRILL_CARD_TYPE=. This
174
+property tells =org-drill= which function to use to present the topic during
175
+review. If this property has the value =twosided= then the topic is treated as
176
+a "two sided card". When a two sided card is reviewed, /one of the first two/
177
+subheadings within the topic will be visible -- all other
178
+subheadings will be hidden.
179
+
180
+Two-sided cards are meant to emulate the type of flipcard where either side is
181
+useful as test material (for example, a card with a word in a foreign language
182
+on one side, and its translation on the other).
183
+
184
+A two sided card can have more than 2 subheadings, but all subheadings after
185
+the first two are considered as "notes" and will always be hidden during topic
186
+review.
187
+
188
+#+BEGIN_EXAMPLE
189
+* Noun                                               :drill:
190
+    :PROPERTIES:
191
+    :DRILL_CARD_TYPE: twosided
192
+    :END:
193
+
194
+Translate this word.
195
+
196
+** Spanish
197
+la mujer
198
+
199
+** English
200
+the woman
201
+
202
+** Example sentence
203
+¿Quién fue esa mujer?
204
+Who was that woman?
205
+#+END_EXAMPLE
206
+
207
+In this example, the user will be shown the main text -- "Translate this word"
208
+-- and either 'la mujer', /or/ 'the woman', at random. The section 'Example
209
+sentence' will never be shown until after the user presses a key, because it is
210
+not one of the first two 'sides' of the topic.
211
+
212
+
213
+** Multi-sided cards
214
+# <<Multi-sided cards>>
215
+
216
+
217
+The =multisided= card type is similar to =twosided=, except that any
218
+subheading has a chance of being presented during the topic review. One
219
+subheading is always shown and all others are always hidden.
220
+
221
+#+BEGIN_EXAMPLE
222
+* Noun                                               :drill:
223
+    :PROPERTIES:
224
+    :DRILL_CARD_TYPE: multisided
225
+    :END:
226
+
227
+Translate.
228
+
229
+** Spanish
230
+la mesa
231
+
232
+** English
233
+the table
234
+
235
+** Picture
236
+[[file:table.jpg][PICTURE]]
237
+#+END_EXAMPLE
238
+
239
+The user will be shown the main text and either 'la mesa', /or/ 'the table',
240
+/or/ a picture of a table.
241
+
242
+
243
+** Multi-cloze cards
244
+# <<Multi-cloze cards>>
245
+
246
+
247
+Often, you will wish to create cards out of sentences that express several
248
+facts, such as the following:
249
+
250
+#+BEGIN_EXAMPLE
251
+The capital city of New Zealand is Wellington, which is located in the
252
+North Island and has a population of about 400,000.
253
+#+END_EXAMPLE
254
+
255
+There is more than one fact in this statement -- you could create a single
256
+'simple' card with all the facts marked as cloze text, like so:
257
+
258
+#+BEGIN_EXAMPLE
259
+The capital city of [New Zealand] is [Wellington], which is located in
260
+the [North||North/South] Island and has a population of about [400,000].
261
+#+END_EXAMPLE
262
+
263
+But this card will be difficult to remember. If you get just one of the 4
264
+hidden facts wrong, you will fail the card. A card like this is likely to
265
+become a [[leeches][leech]].
266
+
267
+A better way to express all these facts using 'simple' cards is to create
268
+several cards, with one fact per card. You might end up with something
269
+like this:
270
+
271
+#+BEGIN_EXAMPLE
272
+* Fact
273
+The capital city of [New Zealand] is Wellington, which has a population of
274
+about 400,000.
275
+
276
+* Fact
277
+The capital city of New Zealand is [Wellington], which has a population of
278
+about 400,000.
279
+
280
+* Fact
281
+The capital city of New Zealand is Wellington, which has a population of
282
+about [400,000].
283
+
284
+* Fact
285
+The capital city of [New Zealand] is Wellington, which is located in the
286
+the North Island.
287
+
288
+* Fact
289
+The capital city of New Zealand is [Wellington], which is located in
290
+the North Island.
291
+
292
+* Fact
293
+The capital city of New Zealand is Wellington, which is located in
294
+the [North||North/South] Island.
295
+#+END_EXAMPLE
296
+
297
+However, this is really cumbersome. Multicloze card types exist for this
298
+situation. Multicloze cards behave like 'simple' cards, except that when there
299
+is more than one area marked as cloze text, some but not all of the areas
300
+can be hidden. There are several types of predefined multicloze card:
301
+
302
+1. =hide1cloze= -- one of the marked areas is hidden during review; the others
303
+   all remain visible. The hidden text area is chosen randomly at each review.
304
+   (Note: this type used to be called 'multicloze', and that card type is
305
+   retained as a synonym for 'hide1cloze'.)
306
+2. =show1cloze= -- only one of the marked areas is visible during review; all
307
+   the others are hidden. The hidden text area is chosen randomly at each
308
+   review.
309
+3. =hide2cloze= -- like hide1cloze, but 2 marked pieces of text will be hidden,
310
+   and the rest will be visible.
311
+4. =show2cloze= -- like show1cloze, but 2 marked pieces of text will be visible,
312
+   the rest are hidden.
313
+
314
+There are also some types of multicloze card where some pieces have an
315
+increased or decreased chance of being hidden. These are intended for use when
316
+studying languages: generally it is easy to translate a foreign-language
317
+sentence into your own language if you have met it before, but it is much
318
+harder to translate in the other direction. Therefore, you will want to test
319
+the harder direction more often.
320
+5. =hide1_firstmore= -- only one of the marked pieces of text will be
321
+   hidden. 75% of the time (guaranteed), the /first/ piece is hidden; the rest
322
+   of the time, one of the other pieces is randomly hidden.
323
+6. =show1_firstless= -- only one of the marked pieces of text will be
324
+   visible. Only 25% of the time (guaranteed) will the /first/ piece will be
325
+   visible; the rest of the time, one of the other pieces is randomly visible.
326
+7. =show1_lastmore= -- only one of the marked pieces of text will be
327
+   visible. 75% of the time (guaranteed), the /last/ piece will be visible;
328
+   the rest of the time, one of the other pieces is randomly visible.
329
+
330
+So, for the above example, we can actually use the original 'bad' simple card,
331
+but change its card type to 'hide1cloze'. Each time the card is presented for
332
+review, one of 'New Zealand', 'Wellington', 'the North Island' or '400,000'
333
+will be hidden.
334
+
335
+#+BEGIN_EXAMPLE
336
+* Fact
337
+  :PROPERTIES:
338
+  :DRILL_CARD_TYPE: hide1cloze
339
+  :END:
340
+
341
+The capital city of [New Zealand] is [Wellington], which is located in
342
+the [North||North/South] Island and has a population of about [400,000].
343
+#+END_EXAMPLE
344
+
345
+
346
+** User-defined card types
347
+# <<User-defined card types>>
348
+
349
+
350
+Finally, you can write your own emacs lisp functions to define new kinds of
351
+topics. Any new topic type will need to be added to
352
+=org-drill-card-type-alist=, and cards using that topic type will need to have
353
+it as the value of their =DRILL_CARD_TYPE= property. For examples, see the
354
+functions at the end of org-drill.el -- these include:
355
+- =org-drill-present-verb-conjugation=, which implements the 'conjugate'
356
+  card type. This asks the user to conjugate a verb in a particular tense. It
357
+  demonstrates how the appearance of an entry can be completely altered during
358
+  a drill session, both during testing and during the display of the answer.
359
+- =org-drill-present-translate-number=, which uses a third-party emacs lisp
360
+  library ([[http://www.emacswiki.org/emacs/spell-number.el][spell-number.el]]) to prompt the user to translate random numbers
361
+  to and from any language recognised by that library.
362
+- =org-drill-present-spanish-verb=, which defines the new topic type
363
+  =spanish_verb=. This illustrates how a function can control which of an
364
+  item's subheadings are visible during the drill session.
365
+
366
+See the file [[file:spanish.org][spanish.org]] for a full set of example material, including examples
367
+of all the card types discussed above.
368
+
369
+
370
+** Empty cards
371
+
372
+
373
+If the body of a drill item is completely empty (ignoring properties and child
374
+items), then the item will be skipped during drill sessions. The purpose of
375
+this behaviour is to allow you to paste in 'skeletons' of complex items, then
376
+fill in missing information later. For example, you may wish to include an
377
+empty drill item for each tense of a newly learned verb, then paste in the
378
+actual conjugation later as you learn each tense.
379
+
380
+Note that if an item is empty, any child drill items will *not* be ignored,
381
+unless they are empty as well.
382
+
383
+If you have an item with an empty body, but still want it to be included in a
384
+drill session, you can either:
385
+1. Put a brief comment ('# ...')  in the item body.
386
+2. Change the entry for its card type in =org-drill-card-type-alist= so that
387
+   items of this type will always be tested, even if they have an empty body.
388
+   See the documentation for =org-drill-card-type-alist= for details.
389
+
390
+
391
+* Running the drill session
392
+
393
+
394
+Start a drill session with =M-x org-drill=. By default, this tests all
395
+non-hidden topics in the current buffer. =org-drill= takes an optional
396
+argument, SCOPE, which allows it to take drill items from other
397
+sources. See [[scope][below]] for details.
398
+
399
+During a drill session, you will be presented with each item, then asked to
400
+rate your recall of it by pressing a key between 0 and 5. The meaning of these
401
+numbers is (taken from =org-learn=):
402
+
403
+| Quality | SuperMemo label | Fail? | Meaning                                              |
404
+|---------+-----------------+-------+------------------------------------------------------|
405
+|       0 | NULL            | Yes   | Wrong, and the answer is unfamiliar when you see it. |
406
+|       1 | BAD             | Yes   | Wrong answer.                                        |
407
+|       2 | FAIL            | Yes   | Almost, but not quite correct.                       |
408
+|       3 | PASS            | No    | Correct answer, but with much effort.                |
409
+|       4 | GOOD            | No    | Correct answer, with a little thought.               |
410
+|       5 | BRIGHT          | No    | Correct answer, effortless.                          |
411
+
412
+You can press '?'  at the prompt if you have trouble remembering what the
413
+numbers 0--5 signify.
414
+
415
+At any time you can press 'q' to finish the drill early (your progress up to
416
+that point will be saved), 's' to skip the current item without viewing the
417
+answer, or 'e' to escape from the drill and jump to the current topic for
418
+editing (again, your progress up to that point will be saved).
419
+
420
+After exiting the drill session with 'e' or 'q', you can resume where you left
421
+off, using the command =org-drill-resume=. This will return you to the item
422
+that you were viewing when you left the session. For example, if you are shown
423
+an item and realise that it is poorly formulated, or contains an error, you can
424
+press 'e' to leave the drill, then correct the item, then press
425
+=M-x org-drill-resume= and continue where you left off.
426
+
427
+Note that 'drastic' edits, such as deleting or moving items, can sometimes
428
+cause Org-Drill to "lose its place" in the file, preventing it from
429
+successfully resuming the session. In that case you will need to start a new
430
+session.
431
+
432
+
433
+* Multiple sequential drill sessions
434
+
435
+
436
+Org-Drill has to scan your entire item database each time you start a new drill
437
+session. This can be slow if you have a large item collection. If you have a
438
+large number of 'due' items and want to run a second drill session after
439
+finishing one session, you can use the command =org-drill-again= to run a new
440
+drill session that draws from the pool of remaining due items that were not
441
+tested during the previous session, without re-scanning the item collection.
442
+
443
+Also note that if you run =org-drill-resume= and you have actually finished the
444
+drill session, you will be asked whether you want to start another drill
445
+session without re-scanning (as if you had run =org-drill-again=).
446
+
447
+
448
+* Cram mode
449
+
450
+
451
+There are some situations, such as before an exam, where you will want to
452
+revise all of your cards regardless of when they are next due for review.
453
+
454
+To do this, run a /cram session/ with the =org-drill-cram= command (=M-x
455
+org-drill-cram=). This works the same as a normal drill session, except
456
+that all items are considered due for review unless you reviewed them within
457
+the last 12 hours (you can change the number of hours by customising the
458
+variable =org-drill-cram-hours=).
459
+
460
+Cram sessions are not considered to be part of the normal learning process for
461
+the tested items. Cramming will not affect when items are next due for
462
+revision.
463
+
464
+
465
+* Leeches
466
+# <<leeches>>
467
+
468
+From the Anki website, http://ichi2.net/anki/wiki/Leeches:
469
+
470
+#+BEGIN_QUOTE
471
+Leeches are cards that you keep on forgetting. Because they require so many
472
+reviews, they take up a lot more of your time than other cards.
473
+#+END_QUOTE
474
+
475
+Like Anki, Org-Drill defines leeches as cards that you have "failed" many
476
+times. The number of times an item must be failed before it is considered a
477
+leech is set by the variable =org-drill-leech-failure-threshold= (15 by
478
+default). When you fail to remember an item more than this many times, the item
479
+will be given the =:leech:= tag.
480
+
481
+Leech items can be handled in one of three ways. You can choose how Org-Drill
482
+handles leeches by setting the variable =org-drill-leech-method= to one of the
483
+following values:
484
+- nil :: Leech items are tagged with the =leech= tag, but otherwise treated the
485
+         same as normal items.
486
+- skip :: Leech items are not included in drill sessions.
487
+- warn :: Leech items are still included in drill sessions, but a warning
488
+  message is printed when each leech item is presented.
489
+
490
+The best way to deal with a leech is either to delete it, or reformulate it so
491
+that it is easier to remember, for example by splitting it into more than one
492
+card.
493
+
494
+See [[http://www.supermemo.com/help/leech.htm][the SuperMemo website]] for more on leeches.
495
+
496
+
497
+* Customisation
498
+
499
+
500
+Org-Drill has several settings which you change using
501
+=M-x customize-group org-drill <RET>=. Alternatively you can change these
502
+settings by adding elisp code to your configuration file (=.emacs=).
503
+
504
+
505
+** Visual appearance of items during drill sessions
506
+
507
+
508
+If you want cloze-deleted text to show up in a special font within Org mode
509
+buffers, add this to your .emacs:
510
+
511
+#+BEGIN_EXAMPLE
512
+(setq org-drill-use-visible-cloze-face-p t)
513
+#+END_EXAMPLE
514
+
515
+Item headings may contain information that "gives away" the answer to the item,
516
+either in the heading text or in tags. If you want item headings to be made
517
+invisible while each item is being tested, add:
518
+
519
+#+BEGIN_EXAMPLE
520
+(setq org-drill-hide-item-headings-p t)
521
+#+END_EXAMPLE
522
+
523
+
524
+** Duration of drill sessions
525
+
526
+
527
+By default, a drill session will end when either 30 items have been
528
+successfully reviewed, or 20 minutes have passed. To change this behaviour, use
529
+the following settings.
530
+
531
+#+BEGIN_EXAMPLE
532
+(setq org-drill-maximum-items-per-session 40)
533
+(setq org-drill-maximum-duration 30)   ; 30 minutes
534
+#+END_EXAMPLE
535
+
536
+If either of these variables is set to nil, then item count or elapsed time
537
+will not count as reasons to end the session. If both variables are nil, the
538
+session will not end until /all/ outstanding items have been reviewed.
539
+
540
+
541
+** Saving buffers after drill sessions
542
+
543
+
544
+By default, you will be prompted to save all unsaved buffers at the end of a
545
+drill session. If you don't like this behaviour, use the following setting:
546
+
547
+#+BEGIN_EXAMPLE
548
+(setq org-drill-save-buffers-after-drill-sessions-p nil)
549
+#+END_EXAMPLE
550
+
551
+
552
+** Sources of items for drill sessions (scope)
553
+# <<scope>>
554
+
555
+By default, Org-Drill gathers drill items from the current buffer only,
556
+ignoring any non-visible items. There may be times when you want Org-Drill to
557
+gather drill items from other sources. You can do this by changing the value of
558
+the variable =org-drill-scope=. Possible values are:
559
+
560
+- file :: The current buffer, ignoring hidden items. This is the default.
561
+- tree :: The subtree starting with the entry at the cursor. (Alternatively you
562
+          can use =M-x org=drill-tree= to run the drill session -- this will
563
+          behave the same as =org-drill= if 'tree' was used as the value of
564
+          SCOPE.)
565
+- file-no-restriction :: The current buffer, including both hidden and
566
+     non-hidden items.
567
+- file-with-archives :: The current buffer, and any archives associated with it.
568
+- agenda :: All agenda files.
569
+- agenda-with-archives :: All agenda files with any archive files associated
570
+     with them.
571
+- directory :: All files with the extension '.org' in the same directory as the
572
+               current file. (The current file will also be included if its
573
+               extension is .org)
574
+- (file1 file2 ...) :: A list of filenames. All files in the list will be
575
+     scanned.
576
+
577
+
578
+
579
+** Definition of old and overdue items
580
+
581
+
582
+Org-Drill prioritises /overdue/ items in each drill session, presenting them
583
+before other items are seen. Overdue items are defined in terms of how far in
584
+the past the item is scheduled for review. The threshold is defined in terms
585
+of a proportion rather than an absolute number of days. If days overdue is
586
+greater than
587
+
588
+: last-interval * (factor - 1)
589
+
590
+and is at least one day overdue, then the item is considered 'overdue'. The
591
+default factor is 1.2, meaning that the due date can overrun by 20% before the
592
+item is considered overdue.
593
+
594
+To change the factor that determines when items become overdue, use something
595
+like the following in your .emacs. Note that the value should never be less
596
+than 1.0.
597
+
598
+#+BEGIN_EXAMPLE
599
+(setq org-drill-overdue-interval-factor 1.1)
600
+#+END_EXAMPLE
601
+
602
+After prioritising overdue items, Org-Drill next prioritises /young/
603
+items. These are items which were recently learned (or relearned in the case of
604
+a failure), and which therefore have short inter-repetition intervals.
605
+"Recent" is defined as an inter-repetition interval less than a fixed number of
606
+days, rather than a number of repetitions. This ensures that more difficult
607
+items are reviewed more often than easier items before they stop being 'young'.
608
+
609
+The default definition of a young item is one with an inter-repetition interval
610
+of 10 days or less. To change this, use the following:
611
+
612
+#+BEGIN_EXAMPLE
613
+(setq org-drill-days-before-old 7)
614
+#+END_EXAMPLE
615
+
616
+
617
+** Spaced repetition algorithm
618
+
619
+
620
+*** Choice of algorithm
621
+
622
+
623
+Org-Drill supports three different spaced repetition algorithms, all based on
624
+SuperMemo algorithms. These are:
625
+- [[http://www.supermemo.com/english/ol/sm2.htm][SM2]] :: an early algorithm, used in SuperMemo 2.0 (1988), which remains very
626
+  popular -- Anki and Mnemosyne, two of the most popular spaced repetition
627
+  programs, use SM2. This algorithm stores an 'ease factor' for each item,
628
+  which is modified each time you rate your recall of the item.
629
+- [[http://www.supermemo.com/english/ol/sm5.htm][SM5]] (default) :: used in SuperMemo 5.0 (1989). This algorithm uses 'ease
630
+     factors' but also uses a persistent, per-user 'matrix of optimal factors'
631
+     which is also modified after each item repetition.
632
+- Simple8 :: an experimental algorithm based on the [[http://www.supermemo.com/english/algsm8.htm][SM8]] algorithm. SM8 is used
633
+             in SuperMemo 8.0 (1998) and is almost identical to SM11 which is
634
+             used in SuperMemo 2002. Like SM5, it uses a matrix of optimal
635
+             factors. Simple8 differs from SM8 in that it does not adapt the
636
+             matrix to the individual user, though it does adapt each item's
637
+             'ease factor'.
638
+
639
+
640
+If you want Org-Drill to use the =SM2= algorithm, put the following in your
641
+=.emacs=:
642
+
643
+#+BEGIN_EXAMPLE
644
+(setq org-drill-spaced-repetition-algorithm 'sm2)
645
+#+END_EXAMPLE
646
+
647
+
648
+*** Random variation of repetition intervals
649
+
650
+
651
+The intervals generated by the SM2 and SM5 algorithms are pretty
652
+deterministic. If you tend to add items in large, infrequent batches, the lack
653
+of variation in interval scheduling can lead to the problem of "lumpiness" --
654
+one day a large batch of items are due for review, the next there is almost
655
+nothing, a few days later another big pile of items is due, and so on.
656
+
657
+This problem can be ameliorated by adding some random "noise" to the interval
658
+scheduling algorithm. The author of SuperMemo actually recommends this approach
659
+for the SM5 algorithm, and Org-Drill's implementation uses [[http://www.supermemo.com/english/ol/sm5.htm][his code]].
660
+
661
+To enable random "noise" for item intervals, set the variable
662
+=org-drill-add-random-noise-to-intervals-p= to true by putting the following in
663
+your =.emacs=:
664
+
665
+#+BEGIN_EXAMPLE
666
+(setq org-drill-add-random-noise-to-intervals-p t)
667
+#+END_EXAMPLE
668
+
669
+
670
+*** Adjustment for early or late review of items
671
+
672
+
673
+Reviewing items earlier or later than their scheduled review date may affect
674
+how soon the next review date should be scheduled. Code to make this adjustment
675
+is also presented on the SuperMemo website. It can be enabled with:
676
+
677
+#+BEGIN_EXAMPLE
678
+(setq org-drill-adjust-intervals-for-early-and-late-repetitions-p t)
679
+#+END_EXAMPLE
680
+
681
+This will affect both early and late repetitions if the Simple8 algorithm is
682
+used. For the SM5 algorithm it will affect early repetitions only. It has no
683
+effect on the SM2 algorithm.
684
+
685
+
686
+*** Adjusting the first interval (SM5 algorithm only)
687
+
688
+
689
+In the SM5 algorithm, the initial interval after the first successful
690
+presentation of an item is /always/ 4 days. If you wish to change this for some
691
+reason, you can do so with:
692
+
693
+#+BEGIN_EXAMPLE
694
+(setq org-drill-sm5-initial-interval 5.0)
695
+#+END_EXAMPLE
696
+
697
+note that this will have no effect if you are not using the SM5 algorithm.
698
+
699
+
700
+*** Adjusting item difficulty globally
701
+
702
+
703
+The =learn fraction= is a global value which affects how quickly the intervals
704
+(times between each retest of an item) increase with successive repetitions,
705
+for /all/ items. The default value is 0.5, and this is the value used in
706
+SuperMemo. For some collections of information, you may find that you are
707
+reviewing items too often (they are too easy and the workload is too high), or
708
+too seldom (you are failing them too often). In these situations, it is
709
+possible to alter the learn fraction from its default in order to increase or
710
+decrease the frequency of repetition of items over time. Increasing the value
711
+will make the time intervals grow faster, and lowering it will make them grow
712
+more slowly. The table below shows the growth in intervals (in days) with some
713
+different values of the learn fraction (F). The table assumes that the item is
714
+successfully recalled each time, with an average quality of just under 4.
715
+
716
+
717
+| Repetition | F=0.3 | F=0.4 | *F=0.5* | F=0.6 | F=0.7 |
718
+|------------+-------+-------+---------+-------+-------|
719
+| 1st        |     2 |     2 |       2 |     2 |     2 |
720
+| 2nd        |     7 |     7 |       7 |     7 |     7 |
721
+| 5th        |    26 |    34 |      46 |    63 |    85 |
722
+| 10th       |    85 |   152 |     316 |   743 |  1942 |
723
+| 15th       |   233 |   501 |    1426 |  5471 | 27868 |
724
+
725
+To alter the learn fraction, put the following in your .emacs:
726
+
727
+#+BEGIN_EXAMPLE
728
+(setq org-drill-learn-fraction 0.45)   ; change the value as desired
729
+#+END_EXAMPLE
730
+
731
+
732
+** Per-file customisation settings
733
+# <<per-file settings>>
734
+
735
+Most of Org-Drill's customisation settings are safe as file-local
736
+variables. This means you can include a commented section like this at the end
737
+of your .org file to apply special settings when running a Drill session using
738
+that file:
739
+
740
+#+BEGIN_EXAMPLE
741
+# Local Variables:
742
+# org-drill-maximum-items-per-session:    50
743
+# org-drill-spaced-repetition-algorithm:  simple8
744
+# End:
745
+#+END_EXAMPLE
746
+
747
+You can achieve the same effect by including the settings in the 'mode line'
748
+(this must be the *first line* in the file), like so:
749
+
750
+#+BEGIN_EXAMPLE
751
+# -*- org-drill-maximum-items-per-session: 50; org-drill-spaced-repetition-algorithm: simple8 -*-
752
+#+END_EXAMPLE
753
+
754
+In either case you will need to reload the file for the changes to take effect.
755
+
756
+
757
+* Coping with large collections
758
+
759
+
760
+If you keep all your items in a single file, it may eventually get very
761
+large. The file will be slow to load, and Emacs may have trouble
762
+syntax-highlighting the file contents correctly.
763
+
764
+The easiest way to solve this problem is:
765
+1. Move your file into its own dedicated directory.
766
+2. Divide the file into two or more smaller files.
767
+3. Within each file, set =org-drill-scope= to 'directory'. See
768
+   [[per-file settings]] above for instructions about how to do this.
769
+
770
+
771
+* Sharing, merging and synchronising item collections
772
+
773
+
774
+Every drill item is automatically given a persistent unique "ID" the first time
775
+it is seen by Org-Drill. This means that if two different people subsequently
776
+edit or reschedule that item, Org-Drill can still tell that it is the same
777
+item. This in turn means that collections of items can be shared and edited in
778
+a collaborative manner.
779
+
780
+There are two commands that are useful in this regard:
781
+1. =org-drill-strip-all-data= - this command deletes all user-specific
782
+   scheduling data from every item in the current collection. (It takes the
783
+   same optional 'scope' argument as =org-drill= to define which items will
784
+   be processed by the command). User-specific data includes scheduling dates,
785
+   ease factors, number of failures and repetitions, and so on. All items are
786
+   reset to 'new' status. This command is useful if you want to share your
787
+   item collection with someone else.
788
+2. =org-drill-merge-buffers= - When called from buffer A, it prompts you for
789
+   another buffer (B), which must also be loaded into Emacs. This command
790
+   imports all the user-specific scheduling data from buffer B into buffer A,
791
+   and deletes any such information in A. Matching items are identified by
792
+   their ID. Any items in B that do not exist in A are copied to A, in
793
+   the same hierarchical location if all the parent headings exist, otherwise
794
+   at the end of the buffer.
795
+
796
+An example scenario:
797
+
798
+Tim decides to learn Swedish using an item collection (=.org= file) made
799
+publically available by Jane.  (Before publishing it Jane used
800
+'org-drill-strip-all-data' to remove her personal scheduling data from the
801
+collection.)  A few weeks later, Jane updates her collection, adding new items
802
+and revising some old ones. Tim downloads the new collection and imports his
803
+progress from his copy of the old collection, using 'org-drill-merge-buffers',
804
+using the new collection as buffer A and the old one as buffer B. He can then
805
+discard the old copy. Any items HE added to HIS copy of the old collection
806
+(buffer B) will not be lost -- they will be appended to his copy of the new
807
+collection.
808
+
809
+Of course the sharing does not need to be 'public'. You and a friend might be
810
+learning a language or some other topic together. You each maintain a card
811
+collection. Periodically your friend sends you a copy of their collection --
812
+you run =org-drill-merge-buffers= on it, always using your own collection as
813
+buffer B so that your own scheduling progress is carried over. Other times you
814
+send your friend a copy of your collection, and he or she follows the same
815
+procedure.
816
+
817
+
818
+* Incremental reading
819
+
820
+
821
+An innovative feature of the program SuperMemo is so-called "incremental
822
+reading". This refers to the ability to quickly and easily make drill items
823
+from selected portions of text as you read an article (a web page for
824
+example). See [[http://www.supermemo.com/help/read.htm][the SuperMemo website]] for more on incremental reading.
825
+
826
+Much of the infrastructure for incremental reading is already provided by Org
827
+Mode, with the help of some other emacs packages. You can provide yourself with
828
+an incremental reading facility by using 'org-capture' alongside a package that
829
+allows you to browse web pages either in emacs (w3 or [[http://www.emacswiki.org/emacs/emacs-w3m][emacs-w3m]]) or in the
830
+external browser of your choice ([[http://orgmode.org/worg/org-contrib/org-protocol.php][org-protocol]]).
831
+
832
+Another important component of incremental reading is the ability to save your
833
+exact place in a document, so you can read it /incrementally/ rather than all
834
+at once. There is a large variety of bookmarking packages for emacs which
835
+provide advanced bookmarking functionality: see the [[http://www.emacswiki.org/emacs/BookMarks][Emacs Wiki]] for details.
836
+Bookmarking exact webpage locations in an external browser seems to be a bit
837
+more difficult. For Firefox, the [[http://www.wired-marker.org/][Wired Marker]] addon works well.
838
+
839
+An example of using Org-Drill for incremental reading is given below. First,
840
+and most importantly, we need to define a couple of =org-capture= templates for
841
+captured facts.
842
+
843
+#+BEGIN_EXAMPLE
844
+(setq org-capture-templates
845
+       `(("u"
846
+         "Task: Read this URL"
847
+         entry
848
+         (file+headline "tasks.org" "Articles To Read")
849
+         ,(concat "* TODO Read article: '%:description'\nURL: %c\n\n")
850
+         :empty-lines 1
851
+         :immediate-finish t)
852
+
853
+        ("w"
854
+         "Capture web snippet"
855
+         entry
856
+         (file+headline "my-facts.org" "Inbox")
857
+         ,(concat "* Fact: '%:description'        :"
858
+                  (format "%s" org-drill-question-tag)
859
+                  ":\n:PROPERTIES:\n:DATE_ADDED: %u\n:SOURCE_URL: %c\n:END:\n\n%i\n%?\n")
860
+         :empty-lines 1
861
+         :immediate-finish t)
862
+        ;; ...other capture templates...
863
+    ))
864
+#+END_EXAMPLE
865
+
866
+Using these templates and =org-protocol=, you can set up buttons in your web
867
+browser to:
868
+- Create a task telling you to read the URL of the currently viewed webpage
869
+- Turn a region of selected text on a webpage, into a new fact which is saved
870
+  to whichever file and heading you nominate in the template. The fact will
871
+  contain a timestamp, and a hyperlink back to the webpage where you created
872
+  it.
873
+
874
+For example, suppose you are reading the Wikipedia entry on tuberculosis [[http://en.wikipedia.org/wiki/Tuberculosis][here]].
875
+
876
+You read the following:
877
+
878
+#+BEGIN_QUOTE
879
+The classic symptoms of tuberculosis are a chronic cough with blood-tinged
880
+sputum, fever, night sweats, and weight loss. Infection of other organs causes
881
+a wide range of symptoms. Treatment is difficult and requires long courses of
882
+multiple antibiotics. Antibiotic resistance is a growing problem in
883
+(extensively) multi-drug-resistant tuberculosis. Prevention relies on screening
884
+programs and vaccination, usually with Bacillus Calmette-Guérin vaccine.
885
+#+END_QUOTE
886
+
887
+You decide you want to remember that "Bacillus Calmette-Guérin vaccine" is the
888
+name of the vaccine against tuberculosis. First, you select the `interesting'
889
+portion of the text with the mouse:
890
+
891
+#+BEGIN_QUOTE
892
+The classic symptoms of tuberculosis are a chronic cough with blood-tinged
893
+sputum, fever, night sweats, and weight loss. Infection of other organs causes
894
+a wide range of symptoms. Treatment is difficult and requires long courses of
895
+multiple antibiotics. Antibiotic resistance is a growing problem in
896
+(extensively) multi-drug-resistant tuberculosis.
897
+@<font style="background-color: yellow;">Prevention relies
898
+on screening programs and vaccination, usually with Bacillus Calmette-Guérin
899
+vaccine.@</font>
900
+#+END_QUOTE
901
+
902
+Then you press the button you created when setting up =org-protocol=, which is
903
+configured to activate the capture template "w: Capture web snippet". The
904
+selected text will be sent to Emacs, turned into a new fact using the template,
905
+and filed away for your later attention.
906
+
907
+(Note that it might be more efficient to turn the entire paragraph into a drill
908
+item -- since it contains several important facts -- then split it up into
909
+multiple items when you edit it later in Emacs.)
910
+
911
+Once you have had enough of reading the article, save your place, then go to
912
+your "fact" file in Emacs. You should see that each piece of text you selected
913
+has been turned into a drill item. Continuing the above example, you would see
914
+something like:
915
+
916
+#+BEGIN_EXAMPLE
917
+** Fact: 'Tuberculosis - Wikipedia, the Free Encyclopedia'        :drill:
918
+
919
+Prevention relies on screening programs and vaccination, usually with Bacillus
920
+Calmette-Guérin vaccine.
921
+#+END_EXAMPLE
922
+
923
+You need to edit this fact so it makes sense independent of its context, as
924
+that is how it will be presented to you in future. The easiest way to turn the
925
+text into a 'question' is by cloze deletion. All you need to do is surround the
926
+'hidden' parts of the text with square brackets.
927
+
928
+: Prevention of tuberculosis relies on screening programs and vaccination,
929
+: usually with [Bacillus Calmette-Guérin vaccine].
930
+
931
+
932
+You can of course define browser buttons that use several different "fact"
933
+templates, each of which might send its fact to a different file or subheading,
934
+or give it different tags or properties, for example.
935
+
936
+
937
+* Author
938
+
939
+Org-Drill is written by Paul Sexton.

+ 407
- 0
external/org-drill/spanish.org View File

@@ -0,0 +1,407 @@
1
+# -*- mode: org; coding: utf-8 -*-
2
+#+STARTUP: showall
3
+
4
+# examples of card definitions for use with org-drill.
5
+# Cards, AKA topics, have the 'drill' tag. Note that the higher-level headings
6
+# in the file do NOT have this tag.
7
+
8
+* Spanish questions
9
+
10
+** Greetings
11
+
12
+# Simple cards. When each card is presented, all subheadings are collapsed, but
13
+# the text under the topic's main heading remains visible.
14
+
15
+*** Greeting 1                                       :drill:
16
+    :PROPERTIES:
17
+    :ID:       aa8ed357-3d0a-4862-90a0-c82726c25b0b
18
+    :END:
19
+
20
+Translate into Spanish:
21
+What is your name? (formal)
22
+
23
+**** Answer
24
+
25
+¿Cómo se llama usted?
26
+
27
+**** Notes
28
+
29
+llamar = to be named
30
+
31
+*** Greeting 2                                       :drill:
32
+    :PROPERTIES:
33
+    :ID:       6a9cd993-4353-4180-b5a4-8fcc65e19854
34
+    :END:
35
+
36
+Translate into Spanish:
37
+What is your name? (informal)
38
+
39
+**** Answer
40
+
41
+¿Cómo te llamas?
42
+
43
+**** Notes
44
+
45
+llamar = to be named
46
+
47
+
48
+** Grammar rules 1
49
+
50
+# More simple cards -- here the question and answer are produced purely using
51
+# cloze deletion of test in [square brackets], without the need to hide any
52
+# subtopics (though they WILL still be hidden if present).
53
+
54
+# If the text between the brackets contains a `|' character, everything after
55
+# that character is considered to be a `hint', and will remain visible when the
56
+# rest of the clozed text is hidden.
57
+
58
+# Set the variable `org-drill-use-visible-cloze-face-p' to `t' if you want
59
+# cloze-deleted text to be shown in a special face when you are editing org
60
+# mode buffers.
61
+
62
+*** Grammar Rule                                     :drill:
63
+    :PROPERTIES:
64
+    :ID:       b54a1009-ecb2-4a0f-a2ac-3d77c46288c8
65
+    :END:
66
+
67
+To form the plural of a noun ending in a consonant, add [-es] to the end.
68
+
69
+*** Grammar Rule                                     :drill:
70
+    SCHEDULED: <2018-08-31 Fri>
71
+    :PROPERTIES:
72
+    :ID:       a61c3409-391b-4f0d-8e00-6b0943b3a6fe
73
+    :DRILL_LAST_INTERVAL: 4.14
74
+    :DRILL_REPEATS_SINCE_FAIL: 2
75
+    :DRILL_TOTAL_REPEATS: 1
76
+    :DRILL_FAILURE_COUNT: 0
77
+    :DRILL_AVERAGE_QUALITY: 5.0
78
+    :DRILL_EASE: 2.6
79
+    :DRILL_LAST_QUALITY: 5
80
+    :DRILL_LAST_REVIEWED: [2018-08-27 Mon 14:37]
81
+    :END:
82
+
83
+To make the plural of an adjective ending in [a stressed vowel or a consonant
84
+other than -z], add /-es/.
85
+
86
+** Grammar rules 2
87
+
88
+# An example of a 'hide1cloze' card. One of the areas marked with square
89
+# brackets will be hidden (chosen at random), the others will remain visible.
90
+
91
+# This card also illustrates the use of hints inside clozed text. Note how
92
+# during testing, the hint text `gender' is invisible unless its clozed text
93
+# area is being hidden, in which case that text is replaced by `[gender...]'
94
+
95
+*** Grammar Rule                                     :drill:
96
+    :PROPERTIES:
97
+    :DRILL_CARD_TYPE: hide1cloze
98
+    :ID:       931062b9-96f3-41a1-a929-c2c485a13551
99
+    :END:
100
+
101
+To form [an adverb] from an adjective, add [-mente] to the [feminine|gender]
102
+form of the adjective.
103
+
104
+** Vocabulary
105
+
106
+# Examples of 'twosided' cards. These are 'flip cards' where one of the
107
+# first 2 'sides' (subheadings) is presented at random, while all others stay
108
+# hidden.
109
+
110
+# There is another builtin card type called 'multisided'. These are like
111
+# 'twosided' cards, but can have any number of sides. So we could extend the
112
+# examples below by changing their type to multisided and adding a third
113
+# subheading which contains an inline image.
114
+
115
+
116
+*** Noun                                             :drill:
117
+    :PROPERTIES:
118
+    :DRILL_CARD_TYPE: twosided
119
+    :ID:       39879b31-3e28-4af0-8e6b-65fb2d30b1c3
120
+    :END:
121
+
122
+Translate this word.
123
+
124
+**** Spanish
125
+
126
+el gato
127
+
128
+**** English
129
+
130
+the cat
131
+
132
+**** Example sentence
133
+
134
+*El gato* se sentó en la estera.
135
+*The cat* sat on the mat.
136
+
137
+
138
+*** Noun                                             :drill:
139
+    :PROPERTIES:
140
+    :DRILL_CARD_TYPE: hide1cloze
141
+    :ID:       3abd7e8e-2747-4f1a-92e7-b998dd3c7be4
142
+    :END:
143
+
144
+Sp: [el perro]
145
+En: [the dog]
146
+
147
+**** Example sentence
148
+
149
+Cuidado con *el perro*.
150
+Beware of *the dog*.
151
+
152
+
153
+*** Noun                                             :drill:
154
+    :PROPERTIES:
155
+    :DRILL_CARD_TYPE: multisided
156
+    :ID:       32e53f30-a510-48d5-9fef-c869cec2f74a
157
+    :END:
158
+
159
+**** Spanish
160
+
161
+la manzana
162
+
163
+**** English
164
+
165
+the apple
166
+
167
+**** Picture
168
+
169
+The Spanish word for...
170
+
171
+[[file:apple.jpg][Picture]]
172
+
173
+
174
+*** Adjective                                        :drill:
175
+    :PROPERTIES:
176
+    :DRILL_CARD_TYPE: twosided
177
+    :ID:       bf0ae223-ae91-40b1-818b-095b990c39b6
178
+    :END:
179
+
180
+Translate this word.
181
+
182
+**** Spanish
183
+
184
+caliente
185
+
186
+**** English
187
+
188
+hot
189
+
190
+**** Example sentence
191
+
192
+El agua está muy caliente.
193
+The water is very hot.
194
+
195
+
196
+** Verbs
197
+
198
+[[Regular Verb: bailar][Below]] is an example of a complex drill item. The main item is itself a drill
199
+item which tests your ability to translate 'bailar' to and from English (which
200
+direction is chosen at random).
201
+
202
+The item has several child items, some of which contain notes about the verb,
203
+others of which are separate drill items relating to the verb. In this example,
204
+all of the child drill items test verb conjugation, and have the 'conjugate'
205
+card type. Which tense to test is specified by the =VERB_TENSE= property in
206
+each item, and the information about the verb is retrieved from the parent's
207
+=VERB_INFINITIVE=, =VERB_TRANSLATION= and =VERB_INFINITIVE_HINT= properties.
208
+
209
+Some of the conjugation items are empty -- this allows the user to paste in
210
+conjugations as they are learned. They will automatically be excluded from
211
+drill sessions as long as their bodies remain empty.
212
+
213
+Following this item is an [[Old Style Verb][example]] of the older "spanish_verb" card type. This
214
+is not as sophisticated or useful as the first example, but is intended to
215
+demonstrate how a function can control which subheadings are visible when an
216
+item is tested.
217
+
218
+
219
+*** Regular Verb: bailar                                            :verb:drill:
220
+  :PROPERTIES:
221
+  :VERB_INFINITIVE: "bailar"
222
+  :VERB_TRANSLATION: "to dance"
223
+  :DRILL_CARD_TYPE: hide1cloze
224
+  :DATE_ADDED: [2011-04-30 Sat]
225
+  :VERB_INFINITIVE_HINT: "b..."
226
+  :ID:       98512533-b497-49c8-9b89-3c021877fcb3
227
+  :END:
228
+
229
+Sp:  [bailar]
230
+En:  [to dance] (verb)
231
+
232
+**** Notes
233
+
234
+This is a regular verb.
235
+
236
+**** Examples
237
+
238
+Bailé con mi novia.
239
+I danced with my girlfriend.
240
+
241
+**** Simple present tense                                           :verb:drill:
242
+     :PROPERTIES:
243
+     :VERB_TENSE: "simple present"
244
+     :DRILL_CARD_TYPE: conjugate
245
+     :ID:       02efc0a0-b829-4bc6-ac12-59861f47516e
246
+     :END:
247
+
248
+| yo            | bailo    |
249
+| tú            | bailas   |
250
+| él/usted      | baila    |
251
+| nosotros      | bailamos |
252
+| vosotros      | bailáis  |
253
+| ellos/ustedes | bailan   |
254
+
255
+**** Participles                                                    :verb:drill:
256
+     :PROPERTIES:
257
+     :ID:       43e5fa9b-5709-4d7c-9084-6c65afad3458
258
+     :END:
259
+Present participle of bailar:  [bailando]
260
+Past participle of bailar:     [bailado]
261
+
262
+**** Preterite tense                                                :verb:drill:
263
+     SCHEDULED: <2018-08-31 Fri>
264
+     :PROPERTIES:
265
+     :VERB_TENSE: "preterite"
266
+     :DRILL_CARD_TYPE: conjugate
267
+     :ID:       275a184a-eb91-4abb-9cff-bfd2429dcb91
268
+     :DRILL_LAST_INTERVAL: 4.14
269
+     :DRILL_REPEATS_SINCE_FAIL: 2
270
+     :DRILL_TOTAL_REPEATS: 1
271
+     :DRILL_FAILURE_COUNT: 0
272
+     :DRILL_AVERAGE_QUALITY: 5.0
273
+     :DRILL_EASE: 2.6
274
+     :DRILL_LAST_QUALITY: 5
275
+     :DRILL_LAST_REVIEWED: [2018-08-27 Mon 14:36]
276
+     :END:
277
+
278
+| yo            | bailé      |
279
+| tú            | bailaste   |
280
+| él/usted      | bailó      |
281
+| nosotros      | bailamos   |
282
+| vosotros      | bailasteis |
283
+| ellos/ustedes | bailaron   |
284
+
285
+**** Imperfect tense                                                :verb:drill:
286
+     :PROPERTIES:
287
+     :VERB_TENSE: "imperfect"
288
+     :DRILL_CARD_TYPE: conjugate
289
+     :ID:       bc8e401e-f3d0-4fa4-9ab4-bff0f26d342c
290
+     :END:
291
+
292
+**** Future tense                                                   :verb:drill:
293
+    :PROPERTIES:
294
+    :VERB_TENSE: "future"
295
+    :DRILL_CARD_TYPE: conjugate
296
+    :ID:       ae7adfb4-ff50-4654-8b64-966311aace42
297
+    :END:
298
+
299
+
300
+*** Old Style Verb                                                       :drill:
301
+    :PROPERTIES:
302
+    :DRILL_CARD_TYPE: spanish_verb
303
+    :ID:       18a71a06-0343-486c-b9f3-b586584e7b39
304
+    :END:
305
+
306
+**** Infinitive
307
+
308
+cantar
309
+
310
+**** English
311
+
312
+to sing
313
+
314
+**** Present Tense
315
+
316
+| yo canto  | nosotros cantamos |
317
+| tú cantas | vosotros cantáis  |
318
+| él canta  | ellos cantan      |
319
+
320
+**** Past Tense
321
+
322
+| yo canté    | nosotros cantamos   |
323
+| tú cantaste | vosotros cantasteis |
324
+| él cantó    | ellos cantaron      |
325
+
326
+**** Future Perfect Tense
327
+
328
+| yo cantaré  | nosotros cantaremos |
329
+| tú cantarás | vosotros cantaréis  |
330
+| él cantarán | ellos cantarán      |
331
+
332
+
333
+**** Notes
334
+
335
+Regular verb.
336
+
337
+
338
+** Sentences
339
+
340
+
341
+It is generally a lot harder for language students to translate /to/ the
342
+foreign language, than to translate /from/ it. This is because when you see a
343
+sentence in the foreign language, you can often get the sense of the sentence
344
+by recognising the nouns and verbs; once this is achieved, combining them into
345
+a grammatically correct sentence in your native tongue is automatic and
346
+effortless. However, in the other direction, not only do you have to recall the
347
+correct nouns, verbs and so on, but you also have to put the words in the right
348
+order and get all the grammar and "in-between words" correct.
349
+
350
+Therefore, if you are learning a language you should generally test your
351
+ability to translate into the language, more often than you test your ability
352
+in the other direction.
353
+
354
+The following is an example of the card type =hide1_firstmore=. This card type
355
+works like =hide1cloze= but the /first/ clozed text area is guaranteed to be
356
+hidden 75% of the time.
357
+
358
+The second example is of a similar card type, =show1_firstless=. Here only 1
359
+clozed text area is visible during testing. 75% of the time, the /first/ area
360
+is guaranteed to be one of the hidden areas.
361
+
362
+
363
+*** Sentence                                                             :drill:
364
+    :PROPERTIES:
365
+    :DRILL_CARD_TYPE: hide1_firstmore
366
+    :ID:       86182cd7-145d-4e87-82f2-2fe03c92bde1
367
+    :END:
368
+
369
+Sp:  [La mujer cuyo perro estamos buscando es mi jefe.]
370
+En:  [The woman whose dog we’re seeking is my boss.]
371
+
372
+*** Adverb                                                               :drill:
373
+    :PROPERTIES:
374
+    :DRILL_CARD_TYPE: show1_firstless
375
+    :ID:       82d682e3-89ab-4d3c-9dd2-c5f8e5ce6452
376
+    :END:
377
+
378
+Sp:  [entre]
379
+En:  [between] or [among]
380
+
381
+
382
+** Random Numbers
383
+
384
+Below is an example of a card that tests the user's ability to translate random
385
+whole numbers to and from a non-English language. For it to work correctly, you
386
+must have the third party library [[http://www.emacswiki.org/emacs/spell-number.el][spell-number.el]] installed and loaded.
387
+
388
+The meaning of the item's properties is as follows:
389
+- =DRILL_LANGUAGE=: any language recognised by spell-number.el. At the time of
390
+  writing these include: catalan, danish, dutch, english-eur, english-gb,
391
+  english-us, esperanto, finnish, french-fr, french-ch, german, italian,
392
+  japanese, norwegian, portuguese-br, portuguese-pt, spanish and swedish.
393
+- =DRILL_NUMBER_MIN= and =DRILL_NUMBER_MAX=: the range between which the random
394
+  number will fall.
395
+
396
+
397
+*** Random Number 20-99                                                  :drill:
398
+  :PROPERTIES:
399
+  :DRILL_NUMBER_MIN: 20
400
+  :DRILL_NUMBER_MAX: 99
401
+  :DRILL_LANGUAGE: spanish
402
+  :DRILL_CARD_TYPE: translate_number
403
+  :ID:       a4020b52-02d6-4128-af5c-53ce3c0e906c
404
+  :END:
405
+
406
+# This comment is included so that the item body is non-empty. Items with
407
+# empty bodies are skipped during drill sessions.

+ 177
- 0
external/org-learn.el View File

@@ -0,0 +1,177 @@
1
+;;; org-learn.el --- Implements SuperMemo's incremental learning algorithm
2
+
3
+;; Copyright (C) 2009-2018 Free Software Foundation, Inc.
4
+
5
+;; Author: John Wiegley <johnw at gnu dot org>
6
+;; Keywords: outlines, hypermedia, calendar, wp
7
+;; Homepage: https://orgmode.org
8
+;; Version: 6.32trans
9
+;;
10
+;; This file is not part of GNU Emacs.
11
+;;
12
+;; This program is free software: you can redistribute it and/or modify
13
+;; it under the terms of the GNU General Public License as published by
14
+;; the Free Software Foundation, either version 3 of the License, or
15
+;; (at your option) any later version.
16
+
17
+;; This program is distributed in the hope that it will be useful,
18
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20
+;; GNU General Public License for more details.
21
+
22
+;; You should have received a copy of the GNU General Public License
23
+;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
24
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
25
+;;
26
+;;; Commentary:
27
+
28
+;; The file implements the learning algorithm described at
29
+;; http://supermemo.com/english/ol/sm5.htm, which is a system for reading
30
+;; material according to "spaced repetition".  See
31
+;; http://en.wikipedia.org/wiki/Spaced_repetition for more details.
32
+;;
33
+;; To use, turn on state logging and schedule some piece of information you
34
+;; want to read.  Then in the agenda buffer type
35
+
36
+(require 'org)
37
+(eval-when-compile
38
+  (require 'cl))
39
+
40
+(defgroup org-learn nil
41
+  "Options concerning the learning code in Org-mode."
42
+  :tag "Org Learn"
43
+  :group 'org-progress)
44
+
45
+(defcustom org-learn-always-reschedule nil
46
+  "If non-nil, always reschedule items, even if retention was \"perfect\"."
47
+  :type 'boolean
48
+  :group 'org-learn)
49
+
50
+(defcustom org-learn-fraction 0.5
51
+  "Controls the rate at which EF is increased or decreased.
52
+Must be a number between 0 and 1 (the greater it is the faster
53
+the changes of the OF matrix)."
54
+  :type 'float
55
+  :group 'org-learn)
56
+
57
+(defun initial-optimal-factor (n ef)
58
+  (if (= 1 n)
59
+      4
60
+    ef))
61
+
62
+(defun get-optimal-factor (n ef of-matrix)
63
+  (let ((factors (assoc n of-matrix)))
64
+    (or (and factors
65
+	     (let ((ef-of (assoc ef (cdr factors))))
66
+	       (and ef-of (cdr ef-of))))
67
+	(initial-optimal-factor n ef))))
68
+
69
+(defun set-optimal-factor (n ef of-matrix of)
70
+  (let ((factors (assoc n of-matrix)))
71
+    (if factors
72
+	(let ((ef-of (assoc ef (cdr factors))))
73
+	  (if ef-of
74
+	      (setcdr ef-of of)
75
+	    (push (cons ef of) (cdr factors))))
76
+      (push (cons n (list (cons ef of))) of-matrix)))
77
+  of-matrix)
78
+
79
+(defun inter-repetition-interval (n ef &optional of-matrix)
80
+  (let ((of (get-optimal-factor n ef of-matrix)))
81
+    (if (= 1 n)
82
+	of
83
+      (* of (inter-repetition-interval (1- n) ef of-matrix)))))
84
+
85
+(defun modify-e-factor (ef quality)
86
+  (if (< ef 1.3)
87
+      1.3
88
+    (+ ef (- 0.1 (* (- 5 quality) (+ 0.08 (* (- 5 quality) 0.02)))))))
89
+
90
+(defun modify-of (of q fraction)
91
+  (let ((temp (* of (+ 0.72 (* q 0.07)))))
92
+    (+ (* (- 1 fraction) of) (* fraction temp))))
93
+
94
+(defun calculate-new-optimal-factor (interval-used quality used-of
95
+						   old-of fraction)
96
+  "This implements the SM-5 learning algorithm in Lisp.
97
+INTERVAL-USED is the last interval used for the item in question.
98
+QUALITY is the quality of the repetition response.
99
+USED-OF is the optimal factor used in calculation of the last
100
+interval used for the item in question.
101
+OLD-OF is the previous value of the OF entry corresponding to the
102
+relevant repetition number and the E-Factor of the item.
103
+FRACTION is a number belonging to the range (0,1) determining the
104
+rate of modifications (the greater it is the faster the changes
105
+of the OF matrix).
106
+
107
+Returns the newly calculated value of the considered entry of the
108
+OF matrix."
109
+  (let (;; the value proposed for the modifier in case of q=5
110
+	(mod5 (/ (1+ interval-used) interval-used))
111
+	;; the value proposed for the modifier in case of q=2
112
+	(mod2 (/ (1- interval-used) interval-used))
113
+	;; the number determining how many times the OF value will
114
+	;; increase or decrease
115
+	modifier)
116
+    (if (< mod5 1.05)
117
+	(setq mod5 1.05))
118
+    (if (< mod2 0.75)
119
+	(setq mod5 0.75))
120
+    (if (> quality 4)
121
+	(setq modifier (1+ (* (- mod5 1) (- quality 4))))
122
+      (setq modifier (- 1 (* (/ (- 1 mod2) 2) (- 4 quality)))))
123
+    (if (< modifier 0.05)
124
+	(setq modifier 0.05))
125
+    (setq new-of (* used-of modifier))
126
+    (if (> quality 4)
127
+	(if (< new-of old-of)
128
+	    (setq new-of old-of)))
129
+    (if (< quality 4)
130
+	(if (> new-of old-of)
131
+	    (setq new-of old-of)))
132
+    (setq new-of (+ (* new-of fraction) (* old-of (- 1 fraction))))
133
+    (if (< new-of 1.2)
134
+	(setq new-of 1.2)
135
+      new-of)))
136
+
137
+(defvar initial-repetition-state '(-1 1 2.5 nil))
138
+
139
+(defun determine-next-interval (n ef quality of-matrix)
140
+  (assert (> n 0))
141
+  (assert (and (>= quality 0) (<= quality 5)))
142
+  (if (< quality 3)
143
+      (list (inter-repetition-interval n ef) (1+ n) ef nil)
144
+    (let ((next-ef (modify-e-factor ef quality)))
145
+      (setq of-matrix
146
+	    (set-optimal-factor n next-ef of-matrix
147
+				(modify-of (get-optimal-factor n ef of-matrix)
148
+					   quality org-learn-fraction))
149
+	    ef next-ef)
150
+      ;; For a zero-based quality of 4 or 5, don't repeat
151
+      (if (and (>= quality 4)
152
+	       (not org-learn-always-reschedule))
153
+	  (list 0 (1+ n) ef of-matrix)
154
+	(list (inter-repetition-interval n ef of-matrix) (1+ n)
155
+	      ef of-matrix)))))
156
+
157
+(defun org-smart-reschedule (quality)
158
+  (interactive "nHow well did you remember the information (on a scale of 0-5)? ")
159
+  (let* ((learn-str (org-entry-get (point) "LEARN_DATA"))
160
+	 (learn-data (or (and learn-str
161
+			      (read learn-str))
162
+			 (copy-list initial-repetition-state)))
163
+	 closed-dates)
164
+    (setq learn-data
165
+	  (determine-next-interval (nth 1 learn-data)
166
+				   (nth 2 learn-data)
167
+				   quality
168
+				   (nth 3 learn-data)))
169
+    (org-entry-put (point) "LEARN_DATA" (prin1-to-string learn-data))
170
+    (if (= 0 (nth 0 learn-data))
171
+	(org-schedule t)
172
+      (org-schedule nil (time-add (current-time)
173
+				  (days-to-time (nth 0 learn-data)))))))
174
+
175
+(provide 'org-learn)
176
+
177
+;;; org-learn.el ends here

+ 2
- 1
init.el View File

@@ -26,7 +26,7 @@
26 26
 ;; set this to t in order to rebuild isg-init.el from isg-init.org
27 27
 ;;
28 28
 
29
-(defvar isg--fully-refreshed-load nil)
29
+(defvar isg--fully-refreshed-load t)
30 30
 (defvar isg--timing-hash (make-hash-table :test 'equal))
31 31
 
32 32
 ;; here's the most recent package-selected-packages list which should be copied into isg-custom.el:
@@ -98,6 +98,7 @@
98 98
 (require 'cl)
99 99
 ; third party code that isn't in melpa-stable yet
100 100
 (push "~/.emacs.d/external" load-path)
101
+(push "~/.emacs.d/external/org-drill" load-path)
101 102
 
102 103
 (if isg--fully-refreshed-load
103 104
     (isg--timer "load isg-init.org"

+ 2
- 1
isg-init.org View File

@@ -526,7 +526,8 @@
526 526
                                           (org-bullets-mode 1)))
527 527
                :config
528 528
                (setq org-hide-leading-stars t)
529
-               (setq org-startup-folded t)))
529
+               (setq org-startup-folded t)
530
+               (require 'org-drill)))
530 531
 #+END_SRC
531 532
 
532 533
        <2017-05-15 Mon>