From 0e2040ba7e03aa23dc76eecc5b1df1f3d14be0b3 Mon Sep 17 00:00:00 2001 From: eeeickythump Date: Fri, 17 Sep 2010 12:13:40 +1200 Subject: * Documentation added for multicloze cards and cram mode. * Multicloze card example added in 'spanish.org'. --- README.html | 217 +++++++++++++++++++++++++++++++++++++++++++++-------------- README.org | 119 +++++++++++++++++++++++++++----- org-drill.el | 18 +++-- spanish.org | 16 ++++- 4 files changed, 299 insertions(+), 71 deletions(-) diff --git a/README.html b/README.html index b8f23f2..75a7a43 100644 --- a/README.html +++ b/README.html @@ -7,7 +7,7 @@ lang="en" xml:lang="en"> Org-Drill - + @@ -79,28 +79,30 @@ lang="en" xml:lang="en">

Table of Contents

-

1 Synopsis

+

Synopsis

@@ -142,7 +144,7 @@ that use it, see:
-

2 Installation and Customisation

+

Installation and Customisation

@@ -232,7 +234,7 @@ your .emacs:
-

3 Demonstration

+

Demonstration

@@ -251,7 +253,7 @@ drill topics are written.
-

4 Writing the questions

+

Writing the questions

@@ -282,7 +284,7 @@ recall purposes.
-

4.1 Simple topics

+

Simple topics

@@ -314,17 +316,18 @@ be visible, but the contents of the subheading ("The Answer") will be hidden.
-

4.2 Cloze deletion

+

Cloze deletion

Cloze deletion can be used in any drill topic regardless of whether it is -otherwise 'simple', or one of the specialised topic types discussed below. To -use cloze deletion, part of the body of the topic is marked as cloze text by -surrounding it with single square brackets, [like so]. When the topic is -presented for review, the text within square brackets will be obscured. The -text is then revealed after the user presses a key. For example: +otherwise 'simple', or is one of the specialised topic types discussed +below. To use cloze deletion, one or more parts of the body of the topic is +marked as cloze text by surrounding it with single square brackets, [like +so]. When the topic is presented for review, the text within square brackets +will be obscured. The text is then revealed after the user presses a key. For +example:

@@ -384,7 +387,7 @@ and
-

4.3 Two-sided cards

+

Two-sided cards

@@ -441,7 +444,7 @@ not one of the first two 'sides' of the topic.
-

4.4 Multi-sided cards

+

Multi-sided cards

@@ -476,16 +479,115 @@ the table The user will be shown the main text and either 'la mujer', or 'the woman', or a picture of a table.

-
-

4.5 User-defined topic types

+

Multi-cloze cards

+

+Often, you will wish to create cards out of sentences that express several +facts, such as the following: +

+
+ +

The capital city of New Zealand is Wellington, which is located in the +South Island and has a population of about 400,000. +

+
+ + +

+There is more than one fact in this statement – you could create a single +'simple' card with all the facts marked as cloze text, like so: +

+
+ +

The capital city of [New Zealand] is [Wellington], which is located in +[the South Island] and has a population of about [400,000]. +

+
+ + +

+But this card will be difficult to remember. If you get just one of the 4 +hidden facts wrong, you will fail the card. A card like this is likely to +become a leech. +

+

+A better way to express all these facts using 'simple' cards is to create +several cards, with one fact per card. You might end up with something +like this: +

+ + + +
* Fact
+The capital city of [New Zealand] is Wellington, which has a population of
+about 400,000.
+
+* Fact
+The capital city of New Zealand is [Wellington], which has a population of
+about 400,000.
+
+* Fact
+The capital city of New Zealand is Wellington, which has a population of
+about [400,000].
+
+* Fact
+The capital city of [New Zealand] is Wellington, which is located in the
+the South Island.
+
+* Fact
+The capital city of New Zealand is [Wellington], which is located in 
+the South Island.
+
+* Fact
+The capital city of New Zealand is Wellington, which is located in 
+[the South Island].
+
+ + + +

+However, this is really cumbersome. The 'multicloze' card type exists for this +situation. Multicloze cards behave like 'simple' cards, except that when there +is more than one area marked as cloze text, only one of the marked areas will +be hidden during review – the others all remain visible. The hidden text area +is chosen randomly at each review. +

+

+So, for the above example, we can actually use the original 'bad' simple card, +but change its card type to 'multicloze'. Each time the card is presented for +review, one of 'New Zealand', 'Wellington', 'the South Island' or '400,000' +will be hidden. +

+ + + +
* Fact
+  :PROPERTIES:
+  :DRILL_CARD_TYPE: multicloze
+  :END:
+
+The capital city of [New Zealand] is [Wellington], which is located in 
+[the South Island] and has a population of about [400,000].
+
+ + + +
+ +
+ +
+

User-defined topic types

+
+ +

Finally, you can write your own elisp functions to define new kinds of topics. Any new topic type will need to be added to @@ -504,7 +606,7 @@ See the file spanish.org for a full set of example ma

-

5 Running the drill session

+

Running the drill session

@@ -564,8 +666,9 @@ numbers is (taken from org-learn):

You can press '?' at the prompt if you have trouble remembering what the numbers 0–5 signify. At any time you can press 'q' to finish the drill early -(your progress will be saved), or 'e' to finish the drill and jump to the -current topic for editing (your progress up to that point will be saved). +(your progress will be saved), 's' to skip the current item without viewing the +answer, or 'e' to finish the drill and jump to the current topic for editing +(your progress up to that point will be saved).

@@ -573,11 +676,10 @@ current topic for editing (your progress up to that point will be saved).
-

6 Leeches

+

Leeches

-

From the Anki website, http://ichi2.net/anki/wiki/Leeches:

@@ -628,11 +730,32 @@ See the SuperMemo website
-

7 Incremental reading

+

Cram mode

+

+There are some situations, such as before an exam, where you will want to +revise all of your cards regardless of when they are next due for review. +

+

+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 +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). +

+ +
+ +
+ +
+

Incremental reading

+
+ + +

An innovative feature of the program SuperMemo is so-called "incremental reading". This refers to the ability to quickly and easily make drill items @@ -651,8 +774,8 @@ Another important component of incremental reading is the ability to save your exact place in a document, so you can read it incrementally rather than all at once. There is a large variety of bookmarking packages for emacs which provide advanced bookmarking functionality: see the Emacs Wiki for details. -Bookmarking exact webpage locations in an external browser is a bit more -difficult. For Firefox, the addon works well. +Bookmarking exact webpage locations in an external browser seems to be a bit +more difficult. For Firefox, the Wired Marker addon works well.

An example of using Org-Drill for incremental reading is given below. First, @@ -739,7 +862,7 @@ vaccine.

-Then you press the button you created when setting up org=protocol, which is +Then you press the button you created when setting up org-protocol, which is configured to activate the capture template "w: Capture web snippet". The selected text will be sent to Emacs, turned into a new fact using the template, and filed away for your later attention. @@ -751,9 +874,9 @@ multiple items when you edit it later in Emacs.)

Once you have had enough of reading the article, save your place, then go to -your "fact" file in Emacs. You should see that all the pieces of text you -selected have been turned into drill items. Continuing the above example, you -would see something like: +your "fact" file in Emacs. You should see that each piece of text you selected +has been turned into a drill item. Continuing the above example, you would see +something like:

@@ -789,9 +912,9 @@ or give it different tags or properties, for example.
-
-

8 Still to do

-
+
+

Still to do

+
    @@ -800,10 +923,6 @@ or give it different tags or properties, for example. single tag? Can use org-make-tag-matcher.
  • -progress indicator during drill session: cumulative time, time spent thinking -about this card -
    • -
  • perhaps take account of item priorities, showing high priority items first
@@ -812,7 +931,7 @@ perhaps take account of item priorities, showing high priority items first

Author: Paul Sexton

-

Date: 2010-09-04 17:22:25 NZST

+

Date: 2010-09-17 10:05:27

HTML generated by org-mode 7.01trans in emacs 23

diff --git a/README.org b/README.org index 79625c3..bd49ee7 100644 --- a/README.org +++ b/README.org @@ -1,5 +1,6 @@ # -*- mode: org; coding: utf-8 -*- #+STARTUP: showall +#+OPTIONS: num:nil #+TITLE: Org-Drill #+AUTHOR: Paul Sexton @@ -134,11 +135,12 @@ be visible, but the contents of the subheading ("The Answer") will be hidden. ** Cloze deletion Cloze deletion can be used in any drill topic regardless of whether it is -otherwise 'simple', or one of the specialised topic types discussed below. To -use cloze deletion, part of the body of the topic is marked as /cloze text/ by -surrounding it with single square brackets, [like so]. When the topic is -presented for review, the text within square brackets will be obscured. The -text is then revealed after the user presses a key. For example: +otherwise 'simple', or is one of the specialised topic types discussed +below. To use cloze deletion, one or more parts of the body of the topic is +marked as /cloze text/ by surrounding it with single square brackets, [like +so]. When the topic is presented for review, the text within square brackets +will be obscured. The text is then revealed after the user presses a key. For +example: #+BEGIN_EXAMPLE * Item :drill: @@ -244,6 +246,78 @@ the table The user will be shown the main text and either 'la mujer', /or/ 'the woman', /or/ a picture of a table. +** Multi-cloze cards + +Often, you will wish to create cards out of sentences that express several +facts, such as the following: + +#+BEGIN_QUOTE +The capital city of New Zealand is Wellington, which is located in the +South Island and has a population of about 400,000. +#+END_QUOTE + +There is more than one fact in this statement -- you could create a single +'simple' card with all the facts marked as cloze text, like so: + +#+BEGIN_QUOTE +The capital city of [New Zealand] is [Wellington], which is located in +[the South Island] and has a population of about [400,000]. +#+END_QUOTE + +But this card will be difficult to remember. If you get just one of the 4 +hidden facts wrong, you will fail the card. A card like this is likely to +become a [[leeches][leech]]. + +A better way to express all these facts using 'simple' cards is to create +several cards, with one fact per card. You might end up with something +like this: + +#+BEGIN_EXAMPLE +* Fact +The capital city of [New Zealand] is Wellington, which has a population of +about 400,000. + +* Fact +The capital city of New Zealand is [Wellington], which has a population of +about 400,000. + +* Fact +The capital city of New Zealand is Wellington, which has a population of +about [400,000]. + +* Fact +The capital city of [New Zealand] is Wellington, which is located in the +the South Island. + +* Fact +The capital city of New Zealand is [Wellington], which is located in +the South Island. + +* Fact +The capital city of New Zealand is Wellington, which is located in +[the South Island]. +#+END_EXAMPLE + +However, this is really cumbersome. The 'multicloze' card type exists for this +situation. Multicloze cards behave like 'simple' cards, except that when there +is more than one area marked as cloze text, only one of the marked areas will +be hidden during review -- the others all remain visible. The hidden text area +is chosen randomly at each review. + +So, for the above example, we can actually use the original 'bad' simple card, +but change its card type to 'multicloze'. Each time the card is presented for +review, one of 'New Zealand', 'Wellington', 'the South Island' or '400,000' +will be hidden. + +#+BEGIN_EXAMPLE +* Fact + :PROPERTIES: + :DRILL_CARD_TYPE: multicloze + :END: + +The capital city of [New Zealand] is [Wellington], which is located in +[the South Island] and has a population of about [400,000]. +#+END_EXAMPLE ** User-defined topic types @@ -289,12 +363,13 @@ numbers is (taken from =org-learn=): You can press '?' at the prompt if you have trouble remembering what the numbers 0--5 signify. At any time you can press 'q' to finish the drill early -(your progress will be saved), or 'e' to finish the drill and jump to the -current topic for editing (your progress up to that point will be saved). +(your progress will be saved), 's' to skip the current item without viewing the +answer, or 'e' to finish the drill and jump to the current topic for editing +(your progress up to that point will be saved). * Leeches - +# <> From the Anki website, http://ichi2.net/anki/wiki/Leeches: @@ -325,6 +400,19 @@ card. See [[http://www.supermemo.com/help/leech.htm][the SuperMemo website]] for more on leeches. +* Cram mode + + +There are some situations, such as before an exam, where you will want to +revise all of your cards regardless of when they are next due for review. + +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 +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=). + + * Incremental reading @@ -343,8 +431,8 @@ Another important component of incremental reading is the ability to save your exact place in a document, so you can read it /incrementally/ rather than all at once. There is a large variety of bookmarking packages for emacs which provide advanced bookmarking functionality: see the [[http://www.emacswiki.org/emacs/BookMarks][Emacs Wiki]] for details. -Bookmarking exact webpage locations in an external browser is a bit more -difficult. For Firefox, the addon works well. +Bookmarking exact webpage locations in an external browser seems to be a bit +more difficult. For Firefox, the [[http://www.wired-marker.org/][Wired Marker]] addon works well. An example of using Org-Drill for incremental reading is given below. First, and most importantly, we need to define a couple of =org-capture= templates for @@ -409,7 +497,7 @@ on screening programs and vaccination, usually with Bacillus Calmette-Guérin vaccine.@ #+END_QUOTE -Then you press the button you created when setting up =org=protocol=, which is +Then you press the button you created when setting up =org-protocol=, which is configured to activate the capture template "w: Capture web snippet". The selected text will be sent to Emacs, turned into a new fact using the template, and filed away for your later attention. @@ -419,9 +507,9 @@ item -- since it contains several important facts -- then split it up into multiple items when you edit it later in Emacs.) Once you have had enough of reading the article, save your place, then go to -your "fact" file in Emacs. You should see that all the pieces of text you -selected have been turned into drill items. Continuing the above example, you -would see something like: +your "fact" file in Emacs. You should see that each piece of text you selected +has been turned into a drill item. Continuing the above example, you would see +something like: #+BEGIN_EXAMPLE ** Fact: 'Tuberculosis - Wikipedia, the Free Encyclopedia' :drill: @@ -448,6 +536,5 @@ or give it different tags or properties, for example. - =org-drill-question-tag= should use a tag match string, rather than a single tag? Can use =org-make-tag-matcher=. -- progress indicator during drill session: cumulative time, time spent thinking - about this card - perhaps take account of item priorities, showing high priority items first +- get tooltips to work for old/new/etc counts during review? diff --git a/org-drill.el b/org-drill.el index a0b0f1b..6b5ff06 100644 --- a/org-drill.el +++ b/org-drill.el @@ -581,17 +581,23 @@ the current topic." (format "%s %s %s %s %s" (propertize (number-to-string (length *org-drill-done-entries*)) - 'face `(:foreground ,org-drill-done-count-color)) + 'face `(:foreground ,org-drill-done-count-color) + 'help-echo "The number of items you have reviewed this session.") (propertize (number-to-string (+ (length *org-drill-again-entries*) (length *org-drill-failed-entries*))) - 'face `(:foreground ,org-drill-failed-count-color)) + 'face `(:foreground ,org-drill-failed-count-color) + 'help-echo (concat "The number of items that you failed, " + "and need to review again.")) (propertize (number-to-string (length *org-drill-mature-entries*)) - 'face `(:foreground ,org-drill-mature-count-color)) + 'face `(:foreground ,org-drill-mature-count-color) + 'help-echo "The number of old items due for review.") (propertize (number-to-string (length *org-drill-new-entries*)) - 'face `(:foreground ,org-drill-new-count-color)) + 'face `(:foreground ,org-drill-new-count-color) + 'help-echo (concat "The number of new items that you " + "have never reviewed.")) prompt)) (if (and (eql 'warn org-drill-leech-method) (org-drill-entry-leech-p)) @@ -1115,6 +1121,10 @@ agenda-with-archives (defun org-drill-cram (&optional scope) + "Run an interactive drill session in 'cram mode'. In cram mode, +all drill items are considered to be due for review, unless they +have been reviewed within the last `org-drill-cram-hours' +hours." (interactive) (let ((*org-drill-cram-mode* t)) (org-drill scope))) diff --git a/spanish.org b/spanish.org index 4f32563..387b37a 100644 --- a/spanish.org +++ b/spanish.org @@ -39,7 +39,7 @@ What is your name? (informal) llamar = to be named -** Grammar rules +** Grammar rules 1 # More simple cards -- here the question and answer are produced purely using # cloze deletion of test in [square brackets], without the need to hide any @@ -55,12 +55,24 @@ llamar = to be named *** Grammar Rule :drill: +To form the plural of a noun ending in a consonant, add [-es] to the end. + +*** Grammar Rule :drill: + To make the plural of an adjective ending in [a stressed vowel or a consonant other than -z], add /-es/. +** Grammar rules 2 + +# An example of a 'multicloze' card. One of the areas marked with square +# brackets will be hidden (chosen at random), the others will remain visible. + *** Grammar Rule :drill: + :PROPERTIES: + :DRILL_CARD_TYPE: multicloze + :END: -To form an adverb from an adjective, add [-mente] to the [feminine|gender] +To form [an adverb] from an adjective, add [-mente] to the [feminine|gender] form of the adjective. ** Vocabulary -- cgit v1.2.3