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