- 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.
...	...	@@ -75,7 +75,7 @@ The simplest format is
75	75
76	76	```yaml
77	77	- type: checkbox
78		- ref: question_reference
	78	+ ref: question_reference
79	79	title: My second question
80	80	text: \|
81	81	Please mark the correct options.
...	...	@@ -83,7 +83,7 @@ The simplest format is
83	83	- this one is correct
84	84	- wrong
85	85	- this one is also correct
86		- correct: [1, -1, 1] # default: [0, 0, 0]
	86	+ correct: [1, -1, 1] # default: [1, 1, 1]
87	87	shuffle: yes # default: yes
88	88	choose: 2 # default: choose all options
89	89	discount: yes # default: yes
...	...	@@ -96,7 +96,9 @@ When correcting an answer, each correctly marked/unmarked option gets the corres
96	96	If `discount: no` then wrong options are given a value of 0.
97	97	Options are shuffled by default. A smaller number of options may be randomly selected by setting the option `choose`.
98	98
99		-A more advanced format is to have
	99	+A more advanced format is to have two versions for each option, one right and one wrong.
	100	+One of the versions is randomly selected when the question is generated.
	101	+For example,
100	102
101	103	```yaml
102	104	options:
...	...	@@ -106,21 +108,21 @@ A more advanced format is to have
106	108	correct: [1, -1, -1]
107	109	```
108	110
109		-In this case, there are options that contain a list of 2 suboptions.
110		-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.
	111	+If the first version is selected then the corresponding `correct` value is used, otherwise if
	112	+the second version is selected, then the symmetrical value is used instead.
111	113
112		-This format is useful to write options with 2 different versions to avoid cheating. Example:
	114	+This format is useful to write questions that are presented in different ways to different students.
	115	+It also minimizes solution memorization. Example:
113	116
114	117	```yaml
115	118	options:
116	119	- ['$\pi$ is a real number', '$\pi$ is an integer']
117	120	- ['there are more reals than integers', 'there are more integers than reals']
118		-
119	121	```
120	122
121		-## text
	123	+### text
122	124
123		-Answer is a line of text. Just compare the answered text with string provided in a list of acceptable answers.
	125	+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.
124	126
125	127	```yaml
126	128	- type: text
...	...	@@ -130,9 +132,9 @@ Answer is a line of text. Just compare the answered text with string provided in
130	132	correct: ['week', 'Week'] # default: [] always wrong
131	133	```
132	134
133		-## text-regex
	135	+### text-regex
134	136
135		-Similar to text, but validade using a regular expression.
	137	+Similar to text, but answers are validated by a regular expression.
136	138
137	139	```yaml
138	140	- type: text-regex
...	...	@@ -142,10 +144,12 @@ Similar to text, but validade using a regular expression.
142	144	correct: !regex '[wW]eek' # default: '$.^' always wrong
143	145	```
144	146
	147	+The regular expression is in a string and must be prefixed by the keyword `!regex`.
145	148
146		-## numeric-interval
	149	+### numeric-interval
147	150
148		-Similar to text, but expects an integer or floating point number. The answer is correct if the number is in the given interval.
	151	+Similar to text, but expects an integer or floating point number.
	152	+The answer is converted to a float and is considered correct if the number is in the given closed interval.
149	153
150	154	```yaml
151	155	- type: numeric-interval
...	...	@@ -155,9 +159,11 @@ Similar to text, but expects an integer or floating point number. The answer is
155	159	correct: [3.141, 3.142] # default: [1.0, -1.0] always wrong
156	160	```
157	161
158		-## textarea
	162	+### textarea
159	163
160		-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.
	164	+Provides a multiline textarea for the answer.
	165	+The answered text is sent to the standard input of an external program for grading.
	166	+The printed output to standard output of the program is parsed as YAML to get the grade and optional comments.
161	167
162	168	```yaml
163	169	- type: textarea
...	...	@@ -169,14 +175,20 @@ Provides a multiline textarea for the answer. The answered text is sent to the s
169	175	timeout: 15 # default: 5
170	176	```
171	177
172		-Example program output:
	178	+The external program prints a dictionary with the grade and optional comments.
	179	+For example,
173	180
174	181	```yaml
175	182	grade: 0.8
176	183	comments: Almost there
177	184	```
178	185
179		-## information, warning, alert and success
	186	+It can also just print the grade as a single number.
	187	+
	188	+
	189	+### information, warning, alert and success
	190	+
	191	+These are not really questions, but just provides information for the student.
180	192
181	193	```yaml
182	194	- type: information
...	...	@@ -185,12 +197,30 @@ comments: Almost there
185	197	text: You can use your calculator.
186	198	```
187	199
188		-## generator
	200	+Grading these type of "questions" yields always correct.
	201	+
	202	+### generator
189	203
190		-Generators are external programs that generate a question dynamically.
191		-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.
	204	+Questions can be generated by external programs instead of being defined directly.
	205	+This allows great flexibility, and allows each instance of a question to be always different.
192	206
193		-Example of a generator written in python (any language can do):
	207	+```yaml
	208	+type: generator
	209	+ref: some-reference
	210	+script: executable_program
	211	+arg: 10,20
	212	+```
	213	+
	214	+A generator is an external program that generates a question dynamically.
	215	+In the example above, the program to be run is `executable_program`.
	216	+The `arg` is sent to the standard input of the `executable_program`.
	217	+
	218	+Questions should be printed to the stdout in YAML format, similarly to how they are defined above (but without the list dash).
	219	+The printed question is then parsed to a dictionary which is then used to update the question.
	220	+The `type` is redefined from generator to something else and the other fields are also updated.
	221	+
	222	+A generator can be any executable program (written in any language) that prints to the standard output.
	223	+Example of a generator written in python:
194	224
195	225	```python
196	226	#!/usr/bin/env python3
...	...	@@ -198,7 +228,7 @@ Example of a generator written in python (any language can do):
198	228	from random import randint
199	229	import sys
200	230
201		-arg = sys.stdin.read() # read arguments
	231	+arg = sys.stdin.read() # read arguments from stdin as a string
202	232	a,b = (int(n) for n in arg.split(','))
203	233
204	234	q = fr'''
...	...	@@ -222,13 +252,15 @@ q += 'correct: ' + str(correct)
222	252	print(q)
223	253	```
224	254
	255	+A generator cannot generate another generator, only real questions are acceptable.
	256	+
225	257	# Writing text
226	258
227		-The text in the questions is interpreted as markdown with LaTeX formulas.
228		-The best way to avoid gotchas is to indent text like this:
	259	+The text in the questions is interpreted as markdown with support for LaTeX formulas.
	260	+The best way to write text is to use indentation like this:
229	261
230	262	```yaml
231		- text: \|
	263	+text: \|
232	264	Yes. this is ok: If not indented, "Yes" would be a boolean
233	265	and colon would be interpreted as a dictionary key.
234	266
...	...	@@ -246,4 +278,6 @@ The best way to avoid gotchas is to indent text like this:
246	278	header1 \| header2
247	279	--------\|---------
248	280	value1 \| value2
249		-```
250	281	\ No newline at end of file
	282	+```
	283	+
	284	+Options of radio and checkbox questions are also interpreted as markdown.
...	...