Commits

Anonymous committed 1c08302

Entries in 'org-drill-card-type-alist' can now take a fourth argument, 'drill-empty-p' (boolean). If true, items of this type are not skipped if their bodies are empty.
Bugfixes related to cram mode.
Cram mode displays a coloured 'C' in the mode line.
Sped up testing whether items have empty bodies.
Updated documentation.

  • Participants
  • Parent commits b592f3f

Comments (0)

Files changed (3)

File org-drill.el

 ;;; org-drill.el - Self-testing using spaced repetition
 ;;;
 ;;; Author: Paul Sexton <eeeickythump@gmail.com>
-;;; Version: 2.3.6
+;;; Version: 2.3.7
 ;;; Repository at http://bitbucket.org/eeeickythump/org-drill/
 ;;;
 ;;;
 
 
 (defcustom org-drill-card-type-alist
-  '((nil . org-drill-present-simple-card)
-    ("simple" . org-drill-present-simple-card)
-    ("twosided" . org-drill-present-two-sided-card)
-    ("multisided" . org-drill-present-multi-sided-card)
-    ("hide1cloze" . org-drill-present-multicloze-hide1)
-    ("hide2cloze" . org-drill-present-multicloze-hide2)
-    ("show1cloze" . org-drill-present-multicloze-show1)
-    ("show2cloze" . org-drill-present-multicloze-show2)
-    ("multicloze" . org-drill-present-multicloze-hide1)
-    ("hidefirst" . org-drill-present-multicloze-hide-first)
-    ("hidelast" . org-drill-present-multicloze-hide-last)
-    ("hide1_firstmore" . org-drill-present-multicloze-hide1-firstmore)
-    ("show1_lastmore" . org-drill-present-multicloze-show1-lastmore)
-    ("show1_firstless" . org-drill-present-multicloze-show1-firstless)
-    ("conjugate" org-drill-present-verb-conjugation
+  '((nil org-drill-present-simple-card)
+    ("simple" org-drill-present-simple-card)
+    ("twosided" org-drill-present-two-sided-card nil t)
+    ("multisided" org-drill-present-multi-sided-card nil t)
+    ("hide1cloze" org-drill-present-multicloze-hide1)
+    ("hide2cloze" org-drill-present-multicloze-hide2)
+    ("show1cloze" org-drill-present-multicloze-show1)
+    ("show2cloze" org-drill-present-multicloze-show2)
+    ("multicloze" org-drill-present-multicloze-hide1)
+    ("hidefirst" org-drill-present-multicloze-hide-first)
+    ("hidelast" org-drill-present-multicloze-hide-last)
+    ("hide1_firstmore" org-drill-present-multicloze-hide1-firstmore)
+    ("show1_lastmore" org-drill-present-multicloze-show1-lastmore)
+    ("show1_firstless" org-drill-present-multicloze-show1-firstless)
+    ("conjugate"
+     org-drill-present-verb-conjugation
      org-drill-show-answer-verb-conjugation)
-    ("spanish_verb" . org-drill-present-spanish-verb)
+    ("spanish_verb" org-drill-present-spanish-verb)
     ("translate_number" org-drill-present-translate-number))
-  "Alist associating card types with presentation functions. Each entry in the
-alist takes one of two forms:
-1. (CARDTYPE . QUESTION-FN), where CARDTYPE is a string or nil (for default),
-   and QUESTION-FN is a function which takes no arguments and returns a boolean
-   value.
-2. (CARDTYPE QUESTION-FN ANSWER-FN), where ANSWER-FN is a function that takes
-   one argument -- the argument is a function that itself takes no arguments.
-   ANSWER-FN is called with the point on the active item's
-   heading, just prior to displaying the item's 'answer'. It can therefore be
-   used to modify the appearance of the answer. ANSWER-FN must call its argument
-   before returning. (Its argument is a function that prompts the user and
-   performs rescheduling)."
+  "Alist associating card types with presentation functions. Each
+entry in the alist takes the form:
+
+;;; (CARDTYPE QUESTION-FN [ANSWER-FN DRILL-EMPTY-P])
+
+Where CARDTYPE is a string or nil (for default), and QUESTION-FN
+is a function which takes no arguments and returns a boolean
+value.
+
+When supplied, ANSWER-FN is a function that takes one argument --
+that argument is a function of no arguments, which when called,
+prompts the user to rate their recall and performs rescheduling
+of the drill item. ANSWER-FN is called with the point on the
+active item's heading, just prior to displaying the item's
+'answer'. It can therefore be used to modify the appearance of
+the answer. ANSWER-FN must call its argument before returning.
+
+When supplied, DRILL-EMPTY-P is a boolean value, default nil.
+When non-nil, cards of this type will be presented during tests
+even if their bodies are empty."
   :group 'org-drill
-  :type '(alist :key-type (choice string (const nil)) :value-type function))
+  :type '(alist :key-type (choice string (const nil))
+                :value-type function))
 
 
 (defcustom org-drill-scope
      ((and (>= ch ?0) (<= ch ?5))
       (let ((quality (- ch ?0))
             (failures (org-drill-entry-failure-count)))
-        (save-excursion
-          (org-drill-smart-reschedule quality
-                                      (nth quality next-review-dates)))
-        (push quality *org-drill-session-qualities*)
-        (cond
-         ((<= quality org-drill-failure-quality)
-          (when org-drill-leech-failure-threshold
-            ;;(setq failures (if failures (string-to-number failures) 0))
-            ;; (org-set-property "DRILL_FAILURE_COUNT"
-            ;;                   (format "%d" (1+ failures)))
-            (if (> (1+ failures) org-drill-leech-failure-threshold)
-                (org-toggle-tag "leech" 'on))))
-         (t
-          (let ((scheduled-time (org-get-scheduled-time (point))))
-            (when scheduled-time
-              (message "Next review in %d days"
-                       (- (time-to-days scheduled-time)
-                          (time-to-days (current-time))))
-              (sit-for 0.5)))))
-        (org-set-property "DRILL_LAST_QUALITY" (format "%d" quality))
-        (org-set-property "DRILL_LAST_REVIEWED"
-                          (time-to-inactive-org-timestamp (current-time)))
+        (unless *org-drill-cram-mode*
+          (save-excursion
+            (org-drill-smart-reschedule quality
+                                        (nth quality next-review-dates)))
+          (push quality *org-drill-session-qualities*)
+          (cond
+           ((<= quality org-drill-failure-quality)
+            (when org-drill-leech-failure-threshold
+              ;;(setq failures (if failures (string-to-number failures) 0))
+              ;; (org-set-property "DRILL_FAILURE_COUNT"
+              ;;                   (format "%d" (1+ failures)))
+              (if (> (1+ failures) org-drill-leech-failure-threshold)
+                  (org-toggle-tag "leech" 'on))))
+           (t
+            (let ((scheduled-time (org-get-scheduled-time (point))))
+              (when scheduled-time
+                (message "Next review in %d days"
+                         (- (time-to-days scheduled-time)
+                            (time-to-days (current-time))))
+                (sit-for 0.5)))))
+          (org-set-property "DRILL_LAST_QUALITY" (format "%d" quality))
+          (org-set-property "DRILL_LAST_REVIEWED"
+                            (time-to-inactive-org-timestamp (current-time))))
         quality))
      ((= ch ?e)
       'edit)
           (format "%s %s %s %s %s %s"
                   (propertize
                    (char-to-string
-                    (case status
-                      (:new ?N) (:young ?Y) (:old ?o) (:overdue ?!)
-                      (:failed ?F) (t ??)))
+                    (cond
+                     ((eql status :failed) ?F)
+                     (*org-drill-cram-mode* ?C)
+                     (t
+                      (case status
+                        (:new ?N) (:young ?Y) (:old ?o) (:overdue ?!)
+                        (t ??)))))
                    'face `(:foreground
                            ,(case status
                               (:new org-drill-new-count-color)
       (substring-no-properties text))))
 
 
-(defun org-drill-entry-empty-p ()
-  (zerop (length (org-drill-get-entry-text))))
-
+;; (defun org-entry-empty-p ()
+;;   (zerop (length (org-drill-get-entry-text))))
+
+;; This version is about 5x faster than the old version, above.
+(defun org-entry-empty-p ()
+  (save-excursion
+    (org-back-to-heading t)
+    (let ((lim (save-excursion
+                 (outline-next-heading) (point))))
+      (org-end-of-meta-data-and-drawers)
+      (or (>= (point) lim)
+          (null (re-search-forward "[[:graph:]]" lim t))))))
+
+(defun org-drill-entry-empty-p () (org-entry-empty-p))
 
 
 ;;; Presentation functions ====================================================
   ;;  (org-back-to-heading))
   (let ((card-type (org-entry-get (point) "DRILL_CARD_TYPE"))
         (answer-fn 'org-drill-present-default-answer)
+        (present-empty-cards nil)
         (cont nil)
         ;; fontification functions in `outline-view-change-hook' can cause big
         ;; slowdowns, so we temporarily bind this variable to nil here.
         (org-show-subtree)
         (org-cycle-hide-drawers 'all)
 
-        (let ((presentation-fn (cdr (assoc card-type org-drill-card-type-alist))))
+        (let ((presentation-fn
+               (cdr (assoc card-type org-drill-card-type-alist))))
           (if (listp presentation-fn)
               (psetq answer-fn (or (second presentation-fn)
                                    'org-drill-present-default-answer)
+                     present-empty-cards (third presentation-fn)
                      presentation-fn (first presentation-fn)))
           (cond
            ((null presentation-fn)
   "Returns true if the current drill session has continued past its
 maximum duration."
   (and org-drill-maximum-duration
+       (not *org-drill-cram-mode*)
        *org-drill-start-time*
        (> (- (float-time (current-time)) *org-drill-start-time*)
           (* org-drill-maximum-duration 60))))
   "Returns true if the current drill session has reached the
 maximum number of items."
   (and org-drill-maximum-items-per-session
+       (not *org-drill-cram-mode*)
        (>= (length *org-drill-done-entries*)
            org-drill-maximum-items-per-session)))
 
                                    (> qual org-drill-failure-quality))
                                  *org-drill-session-qualities*))
                 (max 1 (length *org-drill-session-qualities*))))
-        (prompt nil))
+        (prompt nil)
+        (max-mini-window-height 0.6))
     (setq prompt
           (format
            "%d items reviewed. Session duration %s.
        (cond
         ((not (org-drill-entry-p))
          nil)
-        ((org-drill-entry-empty-p)
-         nil)                           ; skip -- item body is empty
+        ((and (org-entry-empty-p)
+              (let* ((card-type (org-entry-get (point) "DRILL_CARD_TYPE" nil))
+                    (dat (cdr (assoc card-type org-drill-card-type-alist))))
+                (or (null card-type)
+                    (not (third dat)))))
+         ;; body is empty, and this is not a card type where empty bodies are
+         ;; meaningful, so skip it.
+         nil)
         ((null due)                     ; unscheduled - usually a skipped leech
          :unscheduled)
         ;; ((eql -1 due)
                          (:overdue
                           (push (cons (point-marker) due) overdue-data))
                          (:old
-                          (push (point-marker) *org-drill-old-mature-entries*)))))))
+                          (push (point-marker) *org-drill-old-mature-entries*))
+                         )))))
                  scope)
                 (org-drill-order-overdue-entries overdue-data)
                 (setq *org-drill-overdue-entry-count*
               (message "Drill session finished!"))))
         (progn
           (unless end-pos
+            (setq *org-drill-cram-mode* nil)
             (org-drill-free-markers *org-drill-done-entries*)))))
     (cond
      (end-pos
 have been reviewed within the last `org-drill-cram-hours'
 hours."
   (interactive)
-  (let ((*org-drill-cram-mode* t))
-    (org-drill scope)))
+  (setq *org-drill-cram-mode* t)
+  (org-drill scope))
 
 
 (defun org-drill-tree ()
 unreviewed items. If there are no leftover items in memory, a full
 scan will be performed."
   (interactive)
+  (setq *org-drill-cram-mode* nil)
   (cond
    ((plusp (org-drill-pending-entry-count))
     (org-drill-free-markers *org-drill-done-entries*)

File org-drill.html

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"
-lang="en" xml:lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
 <head>
 <title>org-drill.el &ndash; flashcards and spaced repetition for org-mode</title>
 <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
+<meta name="title" content="org-drill.el &ndash; flashcards and spaced repetition for org-mode"/>
 <meta name="generator" content="Org-mode"/>
-<meta name="generated" content="2011-05-21 00:08:14 NZST"/>
+<meta name="generated" content="2012-09-05T10:41+1200"/>
 <meta name="author" content="Paul Sexton"/>
 <meta name="description" content=""/>
 <meta name="keywords" content=""/>
   dt { font-weight: bold; }
   div.figure { padding: 0.5em; }
   div.figure p { text-align: center; }
+  div.inlinetask {
+    padding:10px;
+    border:2px solid gray;
+    margin:10px;
+    background: #ffffcc;
+  }
   textarea { overflow-x: auto; }
   .linenr { font-size:smaller }
   .code-highlighted {background-color:#ffff00;}
 
 </head>
 <body>
+
+<div id="preamble">
+
+</div>
+
 <div id="content">
+<h1 class="title">org-drill.el &ndash; flashcards and spaced repetition for org-mode</h1>
 
-<h1 class="title">org-drill.el &ndash; flashcards and spaced repetition for org-mode</h1>
 
 
 <div id="table-of-contents">
 <h2>Table of Contents</h2>
 <div id="text-table-of-contents">
 <ul>
-<li><a href="#sec-1">General </a></li>
-<li><a href="#sec-2">Installation </a></li>
-<li><a href="#sec-3">Demonstration </a></li>
-<li><a href="#sec-4">Writing the questions </a>
+<li><a href="#sec-1">General</a></li>
+<li><a href="#sec-2">Installation</a></li>
+<li><a href="#sec-3">Demonstration</a></li>
+<li><a href="#sec-4">Writing the questions</a>
 <ul>
-<li><a href="#sec-4_1">Simple topics </a></li>
-<li><a href="#sec-4_2">Cloze deletion </a></li>
-<li><a href="#sec-4_3">Clozed text hints </a></li>
-<li><a href="#sec-4_4">Two-sided cards </a></li>
-<li><a href="#sec-4_5">Multi-sided cards </a></li>
-<li><a href="#sec-4_6">Multi-cloze cards </a></li>
-<li><a href="#sec-4_7">User-defined card types </a></li>
-<li><a href="#sec-4_8">Empty cards </a></li>
+<li><a href="#sec-4-1">Simple topics</a></li>
+<li><a href="#sec-4-2">Cloze deletion</a></li>
+<li><a href="#sec-4-3">Clozed text hints</a></li>
+<li><a href="#sec-4-4">Two-sided cards</a></li>
+<li><a href="#sec-4-5">Multi-sided cards</a></li>
+<li><a href="#sec-4-6">Multi-cloze cards</a></li>
+<li><a href="#sec-4-7">User-defined card types</a></li>
+<li><a href="#sec-4-8">Empty cards</a></li>
 </ul>
 </li>
-<li><a href="#sec-5">Running the drill session </a></li>
-<li><a href="#sec-6">Multiple sequential drill sessions </a></li>
-<li><a href="#sec-7">Cram mode </a></li>
-<li><a href="#sec-8">Leeches </a></li>
-<li><a href="#sec-9">Customisation </a>
+<li><a href="#sec-5">Running the drill session</a></li>
+<li><a href="#sec-6">Multiple sequential drill sessions</a></li>
+<li><a href="#sec-7">Cram mode</a></li>
+<li><a href="#sec-8">Leeches</a></li>
+<li><a href="#sec-9">Customisation</a>
 <ul>
-<li><a href="#sec-9_1">Visual appearance of items during drill sessions </a></li>
-<li><a href="#sec-9_2">Duration of drill sessions </a></li>
-<li><a href="#sec-9_3">Saving buffers after drill sessions </a></li>
-<li><a href="#sec-9_4">Sources of items for drill sessions (scope) </a></li>
-<li><a href="#sec-9_5">Definition of old and overdue items </a></li>
-<li><a href="#sec-9_6">Spaced repetition algorithm </a>
+<li><a href="#sec-9-1">Visual appearance of items during drill sessions</a></li>
+<li><a href="#sec-9-2">Duration of drill sessions</a></li>
+<li><a href="#sec-9-3">Saving buffers after drill sessions</a></li>
+<li><a href="#sec-9-4">Sources of items for drill sessions (scope)</a></li>
+<li><a href="#sec-9-5">Definition of old and overdue items</a></li>
+<li><a href="#sec-9-6">Spaced repetition algorithm</a>
 <ul>
-<li><a href="#sec-9_6_1">Choice of algorithm </a></li>
-<li><a href="#sec-9_6_2">Random variation of repetition intervals </a></li>
-<li><a href="#sec-9_6_3">Adjustment for early or late review of items </a></li>
-<li><a href="#sec-9_6_4">Adjusting item difficulty globally </a></li>
+<li><a href="#sec-9-6-1">Choice of algorithm</a></li>
+<li><a href="#sec-9-6-2">Random variation of repetition intervals</a></li>
+<li><a href="#sec-9-6-3">Adjustment for early or late review of items</a></li>
+<li><a href="#sec-9-6-4">Adjusting the first interval (SM5 algorithm only)</a></li>
+<li><a href="#sec-9-6-5">Adjusting item difficulty globally</a></li>
 </ul>
 </li>
-<li><a href="#sec-9_7">Per-file customisation settings </a></li>
+<li><a href="#sec-9-7">Per-file customisation settings</a></li>
 </ul>
 </li>
-<li><a href="#sec-10">Coping with large collections </a></li>
-<li><a href="#sec-11">Sharing, merging and synchronising item collections </a></li>
-<li><a href="#sec-12">Incremental reading </a></li>
-<li><a href="#sec-13">Author </a></li>
+<li><a href="#sec-10">Coping with large collections</a></li>
+<li><a href="#sec-11">Sharing, merging and synchronising item collections</a></li>
+<li><a href="#sec-12">Incremental reading</a></li>
+<li><a href="#sec-13">Author</a></li>
 </ul>
 </div>
 </div>
 
 <div id="outline-container-1" class="outline-2">
-<h2 id="sec-1">General </h2>
+<h2 id="sec-1">General</h2>
 <div class="outline-text-2" id="text-1">
 
 
 </div>
 
 <div id="outline-container-2" class="outline-2">
-<h2 id="sec-2">Installation </h2>
+<h2 id="sec-2">Installation</h2>
 <div class="outline-text-2" id="text-2">
 
 
 
 
 
-
 </div>
 
 </div>
 
 <div id="outline-container-3" class="outline-2">
-<h2 id="sec-3">Demonstration </h2>
+<h2 id="sec-3">Demonstration</h2>
 <div class="outline-text-2" id="text-3">
 
 
 </div>
 
 <div id="outline-container-4" class="outline-2">
-<h2 id="sec-4">Writing the questions </h2>
+<h2 id="sec-4">Writing the questions</h2>
 <div class="outline-text-2" id="text-4">
 
 
 where you have more control over what information is hidden from the user for
 recall purposes. For this reason, some other card types are defined, including:
 </p><ul>
-<li><a href="#sec-4_4">Two-sided cards</a>
+<li><a href="#sec-4-4">Two-sided cards</a>
 </li>
-<li><a href="#sec-4_5">Multi-sided cards</a>
+<li><a href="#sec-4-5">Multi-sided cards</a>
 </li>
-<li><a href="#sec-4_6">Multi-cloze cards</a>
+<li><a href="#sec-4-6">Multi-cloze cards</a>
 </li>
-<li><a href="#sec-4_7">User-defined card types</a>
+<li><a href="#sec-4-7">User-defined card types</a>
 </li>
 </ul>
 
 
 </div>
 
-<div id="outline-container-4_1" class="outline-3">
-<h3 id="sec-4_1">Simple topics </h3>
-<div class="outline-text-3" id="text-4_1">
+<div id="outline-container-4-1" class="outline-3">
+<h3 id="sec-4-1">Simple topics</h3>
+<div class="outline-text-3" id="text-4-1">
 
 
 
 </pre>
 
 
-
 <p>
 When this item is presented for review, the text beneath the main heading will
 be visible, but the contents of the subheading ("The Answer") will be hidden.
 
 </div>
 
-<div id="outline-container-4_2" class="outline-3">
-<h3 id="sec-4_2">Cloze deletion </h3>
-<div class="outline-text-3" id="text-4_2">
+<div id="outline-container-4-2" class="outline-3">
+<h3 id="sec-4-2">Cloze deletion</h3>
+<div class="outline-text-3" id="text-4-2">
 
 
 
 </pre>
 
 
-
 <p>
 During review, the user will see:
 </p>
 
 </div>
 
-<div id="outline-container-4_3" class="outline-3">
-<h3 id="sec-4_3">Clozed text hints </h3>
-<div class="outline-text-3" id="text-4_3">
+<div id="outline-container-4-3" class="outline-3">
+<h3 id="sec-4-3">Clozed text hints</h3>
+<div class="outline-text-3" id="text-4-3">
 
 
 
 <p>
 Clozed text can contain a "hint" about the answer. If the text surrounded
-by single square brackets contains a `|' character (vertical bar), all text
+by single square brackets contains `||' (two vertical bars), all text
 after that character is treated as a hint. During testing, the hint text will
 be visible when the rest of the text is hidden, and invisible when the rest of
 the text is visible.
 
 
 
-<pre class="example">Type 1 hypersensitivity reactions are mediated by [immunoglobulin E|molecule]
-and [mast cells|cell type].
+<pre class="example">Type 1 hypersensitivity reactions are mediated by [immunoglobulin E||molecule]
+and [mast cells||cell type].
 </pre>
 
 
-
 <blockquote>
 
 <p>Type 1 hypersensitivity reactions are mediated by
 
 </div>
 
-<div id="outline-container-4_4" class="outline-3">
-<h3 id="sec-4_4"><a name="Two-sided-cards" id="Two-sided-cards"></a>Two-sided cards </h3>
-<div class="outline-text-3" id="text-4_4">
+<div id="outline-container-4-4" class="outline-3">
+<h3 id="sec-4-4"><a name="Two-sided-cards" id="Two-sided-cards"></a>Two-sided cards</h3>
+<div class="outline-text-3" id="text-4-4">
 
 
 <p>
 </pre>
 
 
-
 <p>
 In this example, the user will be shown the main text &ndash; "Translate this word"
 &ndash; and either 'la mujer', <i>or</i> 'the woman', at random. The section 'Example
 
 </div>
 
-<div id="outline-container-4_5" class="outline-3">
-<h3 id="sec-4_5"><a name="Multi-sided-cards" id="Multi-sided-cards"></a>Multi-sided cards </h3>
-<div class="outline-text-3" id="text-4_5">
+<div id="outline-container-4-5" class="outline-3">
+<h3 id="sec-4-5"><a name="Multi-sided-cards" id="Multi-sided-cards"></a>Multi-sided cards</h3>
+<div class="outline-text-3" id="text-4-5">
 
 
 
 </pre>
 
 
-
 <p>
 The user will be shown the main text and either 'la mesa', <i>or</i> 'the table',
 <i>or</i> a picture of a table.
 
 </div>
 
-<div id="outline-container-4_6" class="outline-3">
-<h3 id="sec-4_6"><a name="Multi-cloze-cards" id="Multi-cloze-cards"></a>Multi-cloze cards </h3>
-<div class="outline-text-3" id="text-4_6">
+<div id="outline-container-4-6" class="outline-3">
+<h3 id="sec-4-6"><a name="Multi-cloze-cards" id="Multi-cloze-cards"></a>Multi-cloze cards</h3>
+<div class="outline-text-3" id="text-4-6">
 
 
 
 </pre>
 
 
-
 <p>
 There is more than one fact in this statement &ndash; you could create a single
 'simple' card with all the facts marked as cloze text, like so:
 
 
 <pre class="example">The capital city of [New Zealand] is [Wellington], which is located in
-the [North|North/South] Island and has a population of about [400,000].
+the [North||North/South] Island and has a population of about [400,000].
 </pre>
 
 
-
 <p>
 But this card will be difficult to remember. If you get just one of the 4
 hidden facts wrong, you will fail the card. A card like this is likely to
 
 * Fact
 The capital city of New Zealand is Wellington, which is located in
-the [North|North/South] Island.
+the [North||North/South] Island.
 </pre>
 
 
-
 <p>
 However, this is really cumbersome. Multicloze card types exist for this
 situation. Multicloze cards behave like 'simple' cards, except that when there
   :END:
 
 The capital city of [New Zealand] is [Wellington], which is located in
-the [North|North/South] Island and has a population of about [400,000].
+the [North||North/South] Island and has a population of about [400,000].
 </pre>
 
 
 
-
 </div>
 
 </div>
 
-<div id="outline-container-4_7" class="outline-3">
-<h3 id="sec-4_7"><a name="User-defined-card-types" id="User-defined-card-types"></a>User-defined card types </h3>
-<div class="outline-text-3" id="text-4_7">
+<div id="outline-container-4-7" class="outline-3">
+<h3 id="sec-4-7"><a name="User-defined-card-types" id="User-defined-card-types"></a>User-defined card types</h3>
+<div class="outline-text-3" id="text-4-7">
 
 
 
 
 </div>
 
-<div id="outline-container-4_8" class="outline-3">
-<h3 id="sec-4_8">Empty cards </h3>
-<div class="outline-text-3" id="text-4_8">
+<div id="outline-container-4-8" class="outline-3">
+<h3 id="sec-4-8">Empty cards</h3>
+<div class="outline-text-3" id="text-4-8">
 
 
 
 </p>
 <p>
 If you have an item with an empty body, but still want it to be included in a
-drill session, put a brief comment ('# &hellip;')  in the item body.
-</p>
+drill session, you can either:
+</p><ol>
+<li>Put a brief comment ('# &hellip;')  in the item body.
+</li>
+<li>Change the entry for its card type in <code>org-drill-card-type-alist</code> so that
+   items of this type will always be tested, even if they have an empty body.
+   See the documentation for <code>org-drill-card-type-alist</code> for details.
+</li>
+</ol>
+
+
 
 </div>
 </div>
 </div>
 
 <div id="outline-container-5" class="outline-2">
-<h2 id="sec-5">Running the drill session </h2>
+<h2 id="sec-5">Running the drill session</h2>
 <div class="outline-text-2" id="text-5">
 
 
 
 <p>
-Start a drill session with <code>M-x org-drill</code>. By default, this includes all
+Start a drill session with <code>M-x org-drill</code>. By default, this tests all
 non-hidden topics in the current buffer. <code>org-drill</code> takes an optional
 argument, SCOPE, which allows it to take drill items from other
-sources. See <a href="#sec-9_4">below</a> for details.
+sources. See <a href="#sec-9-4">below</a> for details.
 </p>
 <p>
 During a drill session, you will be presented with each item, then asked to
 </div>
 
 <div id="outline-container-6" class="outline-2">
-<h2 id="sec-6">Multiple sequential drill sessions </h2>
+<h2 id="sec-6">Multiple sequential drill sessions</h2>
 <div class="outline-text-2" id="text-6">
 
 
 </div>
 
 <div id="outline-container-7" class="outline-2">
-<h2 id="sec-7">Cram mode </h2>
+<h2 id="sec-7">Cram mode</h2>
 <div class="outline-text-2" id="text-7">
 
 
 revise all of your cards regardless of when they are next due for review.
 </p>
 <p>
-To do this, run a <i>cram session</i> with the <code>org-drill-cram</code> command (<code>M-x org-drill-cram RET</code>). This works the same as a normal drill session, except
+To do this, run a <i>cram session</i> with the <code>org-drill-cram</code> command (<code>M-x org-drill-cram</code>). This works the same as a normal drill session, except
 that all items are considered due for review unless you reviewed them within
 the last 12 hours (you can change the number of hours by customising the
 variable <code>org-drill-cram-hours</code>).
 </p>
+<p>
+Cram sessions are not considered to be part of the normal learning process for
+the tested items. Cramming will not affect when items are next due for
+revision.
+</p>
 
 </div>
 
 </div>
 
 <div id="outline-container-8" class="outline-2">
-<h2 id="sec-8"><a name="leeches" id="leeches"></a>Leeches </h2>
+<h2 id="sec-8"><a name="leeches" id="leeches"></a>Leeches</h2>
 <div class="outline-text-2" id="text-8">
 
 
 </div>
 
 <div id="outline-container-9" class="outline-2">
-<h2 id="sec-9">Customisation </h2>
+<h2 id="sec-9">Customisation</h2>
 <div class="outline-text-2" id="text-9">
 
 
 
 </div>
 
-<div id="outline-container-9_1" class="outline-3">
-<h3 id="sec-9_1">Visual appearance of items during drill sessions </h3>
-<div class="outline-text-3" id="text-9_1">
+<div id="outline-container-9-1" class="outline-3">
+<h3 id="sec-9-1">Visual appearance of items during drill sessions</h3>
+<div class="outline-text-3" id="text-9-1">
 
 
 
 </pre>
 
 
-
 <p>
 Item headings may contain information that "gives away" the answer to the item,
 either in the heading text or in tags. If you want item headings to be made
 
 
 
-
 </div>
 
 </div>
 
-<div id="outline-container-9_2" class="outline-3">
-<h3 id="sec-9_2">Duration of drill sessions </h3>
-<div class="outline-text-3" id="text-9_2">
+<div id="outline-container-9-2" class="outline-3">
+<h3 id="sec-9-2">Duration of drill sessions</h3>
+<div class="outline-text-3" id="text-9-2">
 
 
 
 </pre>
 
 
-
 <p>
 If either of these variables is set to nil, then item count or elapsed time
 will not count as reasons to end the session. If both variables are nil, the
 
 </div>
 
-<div id="outline-container-9_3" class="outline-3">
-<h3 id="sec-9_3">Saving buffers after drill sessions </h3>
-<div class="outline-text-3" id="text-9_3">
+<div id="outline-container-9-3" class="outline-3">
+<h3 id="sec-9-3">Saving buffers after drill sessions</h3>
+<div class="outline-text-3" id="text-9-3">
 
 
 
 
 
 
-
 </div>
 
 </div>
 
-<div id="outline-container-9_4" class="outline-3">
-<h3 id="sec-9_4"><a name="scope" id="scope"></a>Sources of items for drill sessions (scope) </h3>
-<div class="outline-text-3" id="text-9_4">
+<div id="outline-container-9-4" class="outline-3">
+<h3 id="sec-9-4"><a name="scope" id="scope"></a>Sources of items for drill sessions (scope)</h3>
+<div class="outline-text-3" id="text-9-4">
 
 
 <p>
 </dl>
 
 
+
+
 </div>
 
 </div>
 
-<div id="outline-container-9_5" class="outline-3">
-<h3 id="sec-9_5">Definition of old and overdue items </h3>
-<div class="outline-text-3" id="text-9_5">
+<div id="outline-container-9-5" class="outline-3">
+<h3 id="sec-9-5">Definition of old and overdue items</h3>
+<div class="outline-text-3" id="text-9-5">
 
 
 
 </pre>
 
 
-
 <p>
 After prioritising overdue items, Org-Drill next prioritises <i>young</i>
 items. These are items which were recently learned (or relearned in the case of
 
 
 
-
 </div>
 
 </div>
 
-<div id="outline-container-9_6" class="outline-3">
-<h3 id="sec-9_6">Spaced repetition algorithm </h3>
-<div class="outline-text-3" id="text-9_6">
+<div id="outline-container-9-6" class="outline-3">
+<h3 id="sec-9-6">Spaced repetition algorithm</h3>
+<div class="outline-text-3" id="text-9-6">
 
 
 
 
 </div>
 
-<div id="outline-container-9_6_1" class="outline-4">
-<h4 id="sec-9_6_1">Choice of algorithm </h4>
-<div class="outline-text-4" id="text-9_6_1">
+<div id="outline-container-9-6-1" class="outline-4">
+<h4 id="sec-9-6-1">Choice of algorithm</h4>
+<div class="outline-text-4" id="text-9-6-1">
 
 
 
 </dd>
 </dl>
 
-<p>If you want Org-Drill to use the <code>SM2</code> algorithm, put the following in your
+
+
+<p>
+If you want Org-Drill to use the <code>SM2</code> algorithm, put the following in your
 <code>.emacs</code>:
 </p>
 
 
 
 
-
 </div>
 
 </div>
 
-<div id="outline-container-9_6_2" class="outline-4">
-<h4 id="sec-9_6_2">Random variation of repetition intervals </h4>
-<div class="outline-text-4" id="text-9_6_2">
+<div id="outline-container-9-6-2" class="outline-4">
+<h4 id="sec-9-6-2">Random variation of repetition intervals</h4>
+<div class="outline-text-4" id="text-9-6-2">
 
 
 
 deterministic. If you tend to add items in large, infrequent batches, the lack
 of variation in interval scheduling can lead to the problem of "lumpiness" --
 one day a large batch of items are due for review, the next there is almost
-nothing, a few days later another big pile of items is due.
+nothing, a few days later another big pile of items is due, and so on.
 </p>
 <p>
 This problem can be ameliorated by adding some random "noise" to the interval
 
 
 
-
 </div>
 
 </div>
 
-<div id="outline-container-9_6_3" class="outline-4">
-<h4 id="sec-9_6_3">Adjustment for early or late review of items </h4>
-<div class="outline-text-4" id="text-9_6_3">
+<div id="outline-container-9-6-3" class="outline-4">
+<h4 id="sec-9-6-3">Adjustment for early or late review of items</h4>
+<div class="outline-text-4" id="text-9-6-3">
 
 
 
 </pre>
 
 
-
 <p>
 This will affect both early and late repetitions if the Simple8 algorithm is
 used. For the SM5 algorithm it will affect early repetitions only. It has no
 
 </div>
 
-<div id="outline-container-9_6_4" class="outline-4">
-<h4 id="sec-9_6_4">Adjusting item difficulty globally </h4>
-<div class="outline-text-4" id="text-9_6_4">
+<div id="outline-container-9-6-4" class="outline-4">
+<h4 id="sec-9-6-4">Adjusting the first interval (SM5 algorithm only)</h4>
+<div class="outline-text-4" id="text-9-6-4">
+
+
+
+<p>
+In the SM5 algorithm, the initial interval after the first successful
+presentation of an item is <i>always</i> 4 days. If you wish to change this for some
+reason, you can do so with:
+</p>
+
+
+
+<pre class="example">(setq org-drill-sm5-initial-interval 5.0)
+</pre>
+
+
+<p>
+note that this will have no effect if you are not using the SM5 algorithm.
+</p>
+
+</div>
+
+</div>
+
+<div id="outline-container-9-6-5" class="outline-4">
+<h4 id="sec-9-6-5">Adjusting item difficulty globally</h4>
+<div class="outline-text-4" id="text-9-6-5">
 
 
 
 
 
 
-
 </div>
 </div>
 
 </div>
 
-<div id="outline-container-9_7" class="outline-3">
-<h3 id="sec-9_7"><a name="per-file-settings" id="per-file-settings"></a>Per-file customisation settings </h3>
-<div class="outline-text-3" id="text-9_7">
+<div id="outline-container-9-7" class="outline-3">
+<h3 id="sec-9-7"><a name="per-file-settings" id="per-file-settings"></a>Per-file customisation settings</h3>
+<div class="outline-text-3" id="text-9-7">
 
 
 <p>
 </pre>
 
 
-
 <p>
 You can achieve the same effect by including the settings in the 'mode line'
 (this must be the <b>first line</b> in the file), like so:
 </pre>
 
 
-
 <p>
-In either case you will need to save, close and re-open the file for the
-changes to take effect.
+In either case you will need to reload the file for the changes to take effect.
 </p>
 
 </div>
 </div>
 
 <div id="outline-container-10" class="outline-2">
-<h2 id="sec-10">Coping with large collections </h2>
+<h2 id="sec-10">Coping with large collections</h2>
 <div class="outline-text-2" id="text-10">
 
 
 syntax-highlighting the file contents correctly.
 </p>
 <p>
-The easiest steps to solve this problem are:
+The easiest way to solve this problem is:
 </p><ol>
 <li>Move your file into its own dedicated directory.
 </li>
 <li>Divide the file into two or more smaller files.
 </li>
 <li>Within each file, set <code>org-drill-scope</code> to 'directory'. See
-   <a href="#sec-9_7">per-file settings</a> above for instructions about how to do this.
+   <a href="#sec-9-7">per-file settings</a> above for instructions about how to do this.
 </li>
 </ol>
 
+
+
 </div>
 
 </div>
 
 <div id="outline-container-11" class="outline-2">
-<h2 id="sec-11">Sharing, merging and synchronising item collections </h2>
+<h2 id="sec-11">Sharing, merging and synchronising item collections</h2>
 <div class="outline-text-2" id="text-11">
 
 
 </div>
 
 <div id="outline-container-12" class="outline-2">
-<h2 id="sec-12">Incremental reading </h2>
+<h2 id="sec-12">Incremental reading</h2>
 <div class="outline-text-2" id="text-12">
 
 
 </pre>
 
 
-
 <p>
 Using these templates and <code>org-protocol</code>, you can set up buttons in your web
 browser to:
 </pre>
 
 
-
 <p>
 You need to edit this fact so it makes sense independent of its context, as
 that is how it will be presented to you in future. The easiest way to turn the
 </div>
 
 <div id="outline-container-13" class="outline-2">
-<h2 id="sec-13">Author </h2>
+<h2 id="sec-13">Author</h2>
 <div class="outline-text-2" id="text-13">
 
 
 <p>
 Org-Drill is written by Paul Sexton.
-</p>
+</p></div>
 </div>
 </div>
+
 <div id="postamble">
-<p class="date">Date: 2011-05-21 00:08:14 NZST</p>
-<p class="creator">Org version 7.5 with Emacs version 23</p>
+<p class="date">Date: 2012-09-05T10:41+1200</p>
+<p class="creator">Org version N/A with Emacs version 24</p>
 <a href="http://validator.w3.org/check?uri=referer">Validate XHTML 1.0</a>
-</div>
+
 </div>
 </body>
 </html>

File org-drill.org

 
 
 Clozed text can contain a "hint" about the answer. If the text surrounded
-by single square brackets contains a `|' character (vertical bar), all text
+by single square brackets contains `||' (two vertical bars), all text
 after that character is treated as a hint. During testing, the hint text will
 be visible when the rest of the text is hidden, and invisible when the rest of
 the text is visible.
 Example:
 
 #+BEGIN_EXAMPLE
-Type 1 hypersensitivity reactions are mediated by [immunoglobulin E|molecule]
-and [mast cells|cell type].
+Type 1 hypersensitivity reactions are mediated by [immunoglobulin E||molecule]
+and [mast cells||cell type].
 #+END_EXAMPLE
 
 #+BEGIN_QUOTE
 
 #+BEGIN_EXAMPLE
 The capital city of [New Zealand] is [Wellington], which is located in
-the [North|North/South] Island and has a population of about [400,000].
+the [North||North/South] Island and has a population of about [400,000].
 #+END_EXAMPLE
 
 But this card will be difficult to remember. If you get just one of the 4
 
 * Fact
 The capital city of New Zealand is Wellington, which is located in
-the [North|North/South] Island.
+the [North||North/South] Island.
 #+END_EXAMPLE
 
 However, this is really cumbersome. Multicloze card types exist for this
   :END:
 
 The capital city of [New Zealand] is [Wellington], which is located in
-the [North|North/South] Island and has a population of about [400,000].
+the [North||North/South] Island and has a population of about [400,000].
 #+END_EXAMPLE
 
 
 unless they are empty as well.
 
 If you have an item with an empty body, but still want it to be included in a
-drill session, put a brief comment ('# ...')  in the item body.
+drill session, you can either:
+1. Put a brief comment ('# ...')  in the item body.
+2. Change the entry for its card type in =org-drill-card-type-alist= so that
+   items of this type will always be tested, even if they have an empty body.
+   See the documentation for =org-drill-card-type-alist= for details.
 
 
 * Running the drill session
 
 
-Start a drill session with =M-x org-drill=. By default, this includes all
+Start a drill session with =M-x org-drill=. By default, this tests all
 non-hidden topics in the current buffer. =org-drill= takes an optional
 argument, SCOPE, which allows it to take drill items from other
 sources. See [[scope][below]] for details.
 revise all of your cards regardless of when they are next due for review.
 
 To do this, run a /cram session/ with the =org-drill-cram= command (=M-x
-org-drill-cram RET=). This works the same as a normal drill session, except
+org-drill-cram=). This works the same as a normal drill session, except
 that all items are considered due for review unless you reviewed them within
 the last 12 hours (you can change the number of hours by customising the
 variable =org-drill-cram-hours=).
 
+Cram sessions are not considered to be part of the normal learning process for
+the tested items. Cramming will not affect when items are next due for
+revision.
+
 
 * Leeches
 # <<leeches>>
 deterministic. If you tend to add items in large, infrequent batches, the lack
 of variation in interval scheduling can lead to the problem of "lumpiness" --
 one day a large batch of items are due for review, the next there is almost
-nothing, a few days later another big pile of items is due.
+nothing, a few days later another big pile of items is due, and so on.
 
 This problem can be ameliorated by adding some random "noise" to the interval
 scheduling algorithm. The author of SuperMemo actually recommends this approach
 # -*- org-drill-maximum-items-per-session: 50; org-drill-spaced-repetition-algorithm: simple8 -*-
 #+END_EXAMPLE
 
-In either case you will need to save, close and re-open the file for the
-changes to take effect.
+In either case you will need to reload the file for the changes to take effect.
 
 
 * Coping with large collections
 large. The file will be slow to load, and Emacs may have trouble
 syntax-highlighting the file contents correctly.
 
-The easiest steps to solve this problem are:
+The easiest way to solve this problem is:
 1. Move your file into its own dedicated directory.
 2. Divide the file into two or more smaller files.
 3. Within each file, set =org-drill-scope= to 'directory'. See
 * Author
 
 Org-Drill is written by Paul Sexton.
-