- updated QUESTIONS.md

Miguel Barão
1 parent 69d2f61d
Showing 1 changed file with 60 additions and 26 deletions Show diff stats
QUESTIONS.md
@@ -75,7 +75,7 @@ The simplest format is
 ```yaml
 - type: checkbox
-  ref: question_reference 
+  ref: question_reference
   title: My second question
   text: |                 
     Please mark the correct options.
@@ -83,7 +83,7 @@ The simplest format is
     - this one is correct
     - wrong
     - this one is also correct
-  correct: [1, -1, 1]            # default: [0, 0, 0]
+  correct: [1, -1, 1]            # default: [1, 1, 1]
   shuffle: yes                   # default: yes
   choose: 2                      # default: choose all options
   discount: yes                  # default: yes
@@ -96,7 +96,9 @@ When correcting an answer, each correctly marked/unmarked option gets the corres
 If `discount: no` then wrong options are given a value of 0.
 Options are shuffled by default. A smaller number of options may be randomly selected by setting the option `choose`.
-A more advanced format is to have
+A more advanced format is to have two versions for each option, one right and one wrong.
+One of the versions is randomly selected when the question is generated.
+For example,
 ```yaml
   options:
@@ -106,21 +108,21 @@ A more advanced format is to have
   correct: [1, -1, -1]
 ```
-In this case, there are options that contain a list of 2 suboptions.
-When the question is generated, one of the suboptions is randomly  selected. If it's the first then the corresponding `correct` value is used, if it's the second then it's symmetrical is used instead.
+If the first version is selected then the corresponding `correct` value is used, otherwise if 
+the second version is selected, then the symmetrical value is used instead.
-This format is useful to write options with 2 different versions to avoid cheating. Example: 
+This format is useful to write questions that are presented in different ways to different students.
+It also minimizes solution memorization. Example:
 ```yaml
   options:
     - ['$\pi$ is a real number', '$\pi$ is an integer']
     - ['there are more reals than integers', 'there are more integers than reals']
-
 ```
-## text
+### text
-Answer is a line of text. Just compare the answered text with string provided in a list of acceptable answers.
+The answer is a single line of text. Just compare the answered text with the strings provided in a list of answers considered to be right.
 ```yaml
 - type: text
@@ -130,9 +132,9 @@ Answer is a line of text. Just compare the answered text with string provided in
   correct: ['week', 'Week']      # default: [] always wrong
 ```
-## text-regex
+### text-regex
-Similar to text, but validade using a regular expression.
+Similar to text, but answers are validated by a regular expression.
 ```yaml
 - type: text-regex
@@ -142,10 +144,12 @@ Similar to text, but validade using a regular expression.
   correct: !regex '[wW]eek'      # default: '$.^' always wrong
 ```
+The regular expression is in a string and must be prefixed by the keyword `!regex`.
-## numeric-interval
+### numeric-interval
-Similar to text, but expects an integer or floating point number. The answer is correct if the number is in the given interval.
+Similar to text, but expects an integer or floating point number. 
+The answer is converted to a float and is considered correct if the number is in the given closed interval.
 ```yaml
 - type: numeric-interval
@@ -155,9 +159,11 @@ Similar to text, but expects an integer or floating point number. The answer is 
   correct: [3.141, 3.142]      # default: [1.0, -1.0] always wrong
 ```
-## textarea
+### textarea
-Provides a multiline textarea for the answer. The answered text is sent to the stdin of an external program for assessment. The printed stdout output of the program is parsed as YAML to get the grade and optional comments.
+Provides a multiline textarea for the answer. 
+The answered text is sent to the standard input of an external program for grading. 
+The printed output to standard output of the program is parsed as YAML to get the grade and optional comments.
 ```yaml
 - type: textarea
@@ -169,14 +175,20 @@ Provides a multiline textarea for the answer. The answered text is sent to the s
   timeout: 15                   # default: 5
 ```
-Example program output:
+The external program prints a dictionary with the grade and optional comments.
+For example,
 ```yaml
 grade: 0.8
 comments: Almost there
 ```
-## information, warning, alert and success
+It can also just print the grade as a single number.
+
+
+### information, warning, alert and success
+
+These are not really questions, but just provides information for the student.
 ```yaml
 - type: information
@@ -185,12 +197,30 @@ comments: Almost there
   text: You can use your calculator.
 ```
-## generator
+Grading these type of "questions" yields always correct.
+
+### generator
-Generators are external programs that generate a question dynamically.
-Questions should be printed to the stdout in YAML format (without the list dash). The parsed output is used to update the question dict, redefining `type` and other fields.
+Questions can be generated by external programs instead of being defined directly.
+This allows great flexibility, and allows each instance of a question to be always different.
-Example of a generator written in python (any language can do):
+```yaml
+type: generator
+ref: some-reference
+script: executable_program
+arg: 10,20
+```
+
+A generator is an external program that generates a question dynamically. 
+In the example above, the program to be run is `executable_program`.
+The `arg` is sent to the standard input of the `executable_program`.
+
+Questions should be printed to the stdout in YAML format, similarly to how they are defined above (but without the list dash).
+The printed question is then parsed to a dictionary which is then used to update the question.
+The `type` is redefined from generator to something else and the other fields are also updated.
+
+A generator can be any executable program (written in any language) that prints to the standard output.
+Example of a generator written in python:
 ```python
 #!/usr/bin/env python3
@@ -198,7 +228,7 @@ Example of a generator written in python (any language can do):
 from random import randint
 import sys
-arg = sys.stdin.read()  # read arguments
+arg = sys.stdin.read()  # read arguments from stdin as a string
 a,b = (int(n) for n in arg.split(','))
 q = fr'''
@@ -222,13 +252,15 @@ q += &#39;correct: &#39; + str(correct)
 print(q)
 ```
+A generator cannot generate another generator, only real questions are acceptable.
+
 # Writing text
-The text in the questions is interpreted as markdown with LaTeX formulas.
-The best way to avoid gotchas is to indent text like this:
+The text in the questions is interpreted as markdown with support for LaTeX formulas.
+The best way to write text is to use indentation like this:
 ```yaml
-  text: |
+text: |
     Yes. this is ok: If not indented, "Yes" would be a boolean 
     and colon would be interpreted as a dictionary key.
@@ -246,4 +278,6 @@ The best way to avoid gotchas is to indent text like this:
     header1 | header2
     --------|---------
     value1  | value2
-```
 \ No newline at end of file
+```
+
+Options of radio and checkbox questions are also interpreted as markdown.