Document explainer

6 files changed, 178 insertions, 2 deletions

diff --git a/Makefile b/Makefile
index 9d0afbc..4a8b4ad 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 d667eb8..b300263 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 00837b5..a09b3b4 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 0000000..66c985c
--- /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 0000000..4116b98
--- /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 0000000..a876561
--- /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