- Added new example card types, more useful than 'spanish_verb':2.2

  - 'conjugate': retrieves properties VERB_INFINITIVE and VERB_TRANSLATION
    from parent item, and uses its own property VERB_TENSE to prompt the
    student 'Translate the verb INFINITIVE and conjugate for the TENSE tense'
    or 'Give the verb meaning TRANSLATION and conjugate for the TENSE tense'
  - 'translate_number': using third party library spell-number.el,
    prompt the student to translate a random number to or from a non-English
    language (the library can handle numerous languages)
  - examples of both in spanish.org
- org-drill-card-type-alist can now take a second function name, for
  controlling how the ANSWER is displayed
- items can have weights (DRILL_CARD_WEIGHT). The interval is divided by
  the weight when scheduling, so eg an item with a weight of 2.0 will be
  tested twice as often as a normal item.
- New command: org-drill-tree. Same as org-drill using 'tree' argument.
- New command: org-drill-strip-data: deletes all scheduling data from
  every item in scope. Intended for use if you wish to share your item
  library with someone else.
- Fixed bug in simple8 algorithm where items failed on their first review
  were not having intervals reset
- Ensure all markers are freed before starting a new drill session.

1 files changed, 40 insertions, 12 deletions

diff --git a/README.org b/README.org
index 168182b..8e689f8 100755
--- a/README.org
+++ b/README.org
@@ -1,8 +1,6 @@
 # -*- mode: org; coding: utf-8 -*-
 #+STARTUP: showall
 #+OPTIONS: num:nil
-# Make absolutely sure the emacs lisp examples below don't get spuriously evaluated
-#+BABEL: :exports code
 #+TITLE: Org-Drill
 #+AUTHOR: Paul Sexton
 
@@ -66,13 +64,14 @@ the topic must have a tag that matches the value of
 =org-drill-question-tag=. This is =:drill:= by default. Any other org topics
 will be ignored.
 
-You don't need to schedule the topics initially.  However =org-drill= *will*
-recognise items that have been scheduled previously with
-=org-learn=. Unscheduled items are considered to be 'new' and ready for
-memorisation.
+Drill items can have other drill items as children. When a drill item is being
+tested, the contents of any child drill items will be hidden.
+
+You don't need to schedule the topics initially.  Unscheduled items are
+considered to be 'new' and ready for memorisation.
 
 How should 'drill topics' be structured? Any org topic is a legal drill topic
--- it will simply be shown with all subheadings collapsed, so thta only the
+-- it will simply be shown with all subheadings collapsed, so that only the
 material beneath the main item heading is visible. After pressing a key, any
 hidden subheadings will be revealed, and you will be asked to rate your
 "recall" of the item.
@@ -322,12 +321,38 @@ the [North|North/South] Island and has a population of about [400,000].
 Finally, you can write your own emacs lisp functions to define new kinds of
 topics. Any new topic type will need to be added to
 =org-drill-card-type-alist=, and cards using that topic type will need to have
-it as the value of their =DRILL_CARD_TYPE= property. For an example, see the
-function =org-drill-present-spanish-verb=, which defines the new topic type
-=spanish_verb=, used in 'spanish.org'.
+it as the value of their =DRILL_CARD_TYPE= property. For examples, see the
+functions at the end of org-drill.el -- these include:
+- =org-drill-present-verb-conjugation=, which implements the 'conjugate'
+  card type. This asks the user to conjugate a verb in a particular tense. It
+  demonstrates how the appearance of an entry can be completely altered during
+  a drill session, both during testing and during the display fo the answer.
+- =org-drill-present-translate-number=, which uses a third-party emacs lisp
+  library ([[http://www.emacswiki.org/emacs/spell-number.el][spell-number.el]]) to prompt the user to translate random numbers
+  to and from any language recognised by that library.
+- =org-drill-present-spanish-verb=, which defines the new topic type
+  =spanish_verb=. This illustrates how a function can control which of an
+  item's subheadings are visible during the drill session.
+
+See the file [[file:spanish.org][spanish.org]] for a full set of example material, including examples
+of all the card types discussed above.
+
+
+** Empty cards
+
+
+If the body of a drill item is completely empty (ignoring properties and child
+items), then the item will be skipped during drill sessions. The purpose of
+this behaviour is to allow you to paste in 'skeletons' of complex items, then
+fill in missing information later. For example, you may wish to include an
+empty drill item for each tense of a newly learned verb, then paste in the
+actual conjugation later as you learn each tense.
 
-See the file [[file:spanish.org][spanish.org]] for a full set of example material.
+Note that if an item is empty, any child drill items will *not* be ignored,
+unless they are empty as well.
 
+If you have an item with an empty body, but still want it to be included in a
+drill session, put a brief comment ('# ...')  in the item body.
 
 
 * Running the drill session
@@ -338,7 +363,10 @@ non-hidden topics in the current buffer. =org-drill= takes an optional
 argument, SCOPE, which allows it to take drill items from other
 sources. Possible values for SCOPE are:
 
-- tree :: The subtree starting with the entry at the cursor.
+- tree :: The subtree starting with the entry at the cursor. (Alternatively you
+          can use =M-x org=drill-tree= to run the drill session -- this will
+          behave the same as =org-drill= if 'tree' was used as the value of
+          SCOPE.)
 - file :: The current buffer, including both hidden and non-hidden items.
 - file-with-archives :: The current buffer, and any archives associated with it.
 - agenda :: All agenda files.