branch: elpa/org-drill
commit c44ca7447b9b4f53f568e4d55614a5848717fd78
Author: Phillip Lord <[email protected]>
Commit: Phillip Lord <[email protected]>
Document explainer
---
Makefile | 3 ++
README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++
org-drill.el | 3 +-
robot/explainer-run.el | 22 +++++++++++++++
robot/explainer-run.org | 36 ++++++++++++++++++++++++
robot/explainer-run.sh | 43 +++++++++++++++++++++++++++++
6 files changed, 178 insertions(+), 2 deletions(-)
diff --git a/Makefile b/Makefile
index 9d0afbc4bd..4a8b4ad858 100644
--- a/Makefile
+++ b/Makefile
@@ -57,4 +57,7 @@ all-card-robot-test: clean-elc
spanish-robot-test: clean-elc
$(EMACS_ENV) ./robot/spanish-run.sh $(SMALL)
+explainer-robot-test: clean-elc
+ $(EMACS_ENV) ./robot/explainer-run.sh $(SMALL)
+
.PHONY: test
diff --git a/README.md b/README.md
index d667eb8f77..b3002639ab 100644
--- a/README.md
+++ b/README.md
@@ -300,6 +300,79 @@ will be hidden.
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].
+## Explainers
+
+It is sometimes useful to add notes that give context to the
+answer. This can be achieved through subheadings. In the example
+below, `Notes` will be hidden when the question is raised, and
+displayed with the answer.
+
+ *** Greeting 1 :drill:
+
+ Translate into Spanish:
+ What is your name? (formal)
+
+ **** Answer
+
+ ¿Cómo se llama usted?
+
+ **** Notes
+
+ llamar = to be named
+
+While this works well, there times when it would be useful to add the
+same note to several cards. Explainers allows this. An explanation
+goes in the super heading and will be displayed with the answer. For
+example:
+
+ ** Addition
:explain:
+
+ Addition is used to combine two values into a larger one
+
+ *** Question
:drill:
+
+ 2 + 2 = [4]
+
+ *** Question
+
+ 3 + 3 = [6]
+
+When `2 + 2 = 4` is shown the explanation will be shown
+also. Higher-level of explanations can be used also. For example, in
+this case, both explanations will be shown for any question.
+
+
+ * Mathematical Operators
:explain:
+
+ Mathematical operators are used to change several numbers into one
+
+ ** Addition
:explain:
+
+ Addition is used to combine two values into a larger one
+
+ *** Question
:drill:
+
+ 2 + 2 = [4]
+
+ *** Question
+
+ 3 + 3 = [6]
+
+ ** Subtraction
:explain:
+
+ Subtraction is used to remove one value from another to make a smaller one
+
+ *** Question
:drill:
+
+ 3 - 2 = [1]
+
+ *** Question
:drill:
+
+ 5 - 2 = [3]
+
+This can be very useful, for example, when learning multiple examples
+for grammatical rules.
+
## User-defined card types
Finally, you can write your own emacs lisp functions to define new kinds of
diff --git a/org-drill.el b/org-drill.el
index 00837b5efe..a09b3b4b53 100644
--- a/org-drill.el
+++ b/org-drill.el
@@ -3948,7 +3948,7 @@ shuffling is done in place."
#'org-drill-test-display-rescheduler))
(org-toggle-tag "zysygy")))
-(defun org-drill-test-display-rescheduler ()
+(defun org-drill-test-display-rescheduler (session)
(run-hooks 'org-drill-display-answer-hook)
;; Normally, the rescheduler waits for input at this point
(read-key-sequence "Press anything to continue"))
@@ -3972,6 +3972,5 @@ shuffling is done in place."
(+ (length org-drill-leitner-boxed-entries)
(length org-drill-leitner-unboxed-entries))))))
-
(provide 'org-drill)
;;; org-drill.el ends here
diff --git a/robot/explainer-run.el b/robot/explainer-run.el
new file mode 100644
index 0000000000..66c985c9c7
--- /dev/null
+++ b/robot/explainer-run.el
@@ -0,0 +1,22 @@
+(load-file "robot/robot.el")
+(load-file "org-drill.el")
+
+(defun org-drill-do-drill ()
+ (copy "explainer-run.org" "explainer-run-copy.org")
+ (find "explainer-run-copy.org")
+
+ (org-drill)
+ (set-buffer-modified-p nil)
+ (kill-buffer)
+ )
+
+(org-drill-do-drill)
+
+(message "First drill complete")
+
+(setq org-drill-presentation-prompt-with-typing t)
+
+(org-drill-do-drill)
+
+
+(robot-check-cards-seen-and-die 6)
diff --git a/robot/explainer-run.org b/robot/explainer-run.org
new file mode 100644
index 0000000000..4116b983c3
--- /dev/null
+++ b/robot/explainer-run.org
@@ -0,0 +1,36 @@
+* Mathematical Operators :explain:
+
+Mathematical operators are used to change several numbers into one
+
+** Addition :explain:
+
+Addition is used to combine two values into a larger one
+
+*** Question :drill:
+ :PROPERTIES:
+ :ID: 8f6d0b14-b9b2-477e-a01d-aea780860b7c
+ :END:
+
+2 + 2 = [4]
+
+*** Question
+
+3 + 3 = [6]
+
+** Subtraction :explain:
+
+Subtraction is used to remove one value from another to make a smaller one
+
+*** Question :drill:
+ :PROPERTIES:
+ :ID: 05b2019b-c1e3-423d-aad4-b6464c2ad613
+ :END:
+
+3 - 2 = [1]
+
+*** Question :drill:
+ :PROPERTIES:
+ :ID: 1f22df13-2b2e-4f2c-be04-fd40a5dcbcd8
+ :END:
+
+5 - 2 = [3]
diff --git a/robot/explainer-run.sh b/robot/explainer-run.sh
new file mode 100755
index 0000000000..a876561b8f
--- /dev/null
+++ b/robot/explainer-run.sh
@@ -0,0 +1,43 @@
+#!/bin/bash
+
+set -e
+
+function run_drill {
+ ## Org-drill should be running at this point, so give three answers
+ ## with a score of file
+ sleep_small
+
+ echo answer one
+ send_answer
+
+ echo answer two
+ send_answer
+
+ echo answer three
+ send_answer
+
+ ## Press any key to continue
+ echo press any key to continue
+ retn
+
+ echo Save file
+ key y
+}
+
+this_dir="$(dirname "$0")"
+source $this_dir/robot.sh
+
+
+launch_emacs $this_dir/explainer-run.el
+
+{
+ find_bot
+
+ ## Run once with default options
+ run_drill
+
+ ## Run once with presentation-prompt-with-typing
+ run_drill
+
+ wait_emacs
+} || cat robot/failure.txt
