Miguel Barão / perguntations

Download as
Browse Code »

Commit 2e43c7a2a2c6d55e5fd1b42a821cd98727fb4254

Authored by Miguel Barão
1 parent bbfa03c9
Exists in master and in 1 other branch dev

updates demo-tutorial

Showing 3 changed files with 34 additions and 32 deletions   Show diff stats
demo/demo.yaml
  Diff comments   View file @2e43c7a
... ... @@ -22,7 +22,7 @@ title: Teste de demonstração (tutorial)
22 22  
23 23 # Duration in minutes.
24 24 # (0 or undefined means infinite time)
25   -duration: 5
  25 +duration: 20
26 26  
27 27 # Automatic test submission after the given 'duration' timeout
28 28 # (default: false)
... ... @@ -37,11 +37,6 @@ show_points: true
37 37 # (default: no scaling, just use question points)
38 38 scale: [0, 5]
39 39  
40   -# DEPRECATED: old version, to be removed
41   -# scale_max: 20
42   -# scale_min: 0
43   -# scale_points: true
44   -
45 40 # ----------------------------------------------------------------------------
46 41 # Base path applied to the questions files and all the scripts
47 42 # including question generators and correctors.
... ...
demo/questions/generators/generate-question.py
  Diff comments   View file @2e43c7a
... ... @@ -8,6 +8,7 @@ Arguments are read from stdin.
8 8 from random import randint
9 9 import sys
10 10  
  11 +# read two arguments from the field `args` specified in the question yaml file
11 12 a, b = (int(n) for n in sys.argv[1:])
12 13  
13 14 x = randint(a, b)
... ... @@ -18,10 +19,13 @@ print(f"""---
18 19 type: text
19 20 title: Geradores de perguntas
20 21 text: |
21   - Existe a possibilidade da pergunta ser gerada por um programa externo. O
22   - programa deve escrever no `stdout` uma pergunta em formato `yaml` tal como os
23   - exemplos anteriores. Pode também receber argumentos para parametrizar a
24   - pergunta. Aqui está um exemplo de uma pergunta gerada por um script python:
  22 +
  23 + As perguntas podem ser estáticas (como as que vimos até aqui), ou serem
  24 + geradas dinâmicamente por um programa externo. Para gerar uma pergunta, o
  25 + programa deve escrever texto no `stdout` em formato `yaml` tal como os
  26 + exemplos das perguntas estáticas dos tipos apresentados anteriormente. Pode
  27 + também receber argumentos de linha de comando para parametrizar a pergunta.
  28 + Aqui está um exemplo de uma pergunta gerada por um script python:
25 29  
26 30 ```python
27 31 #!/usr/bin/env python3
... ... @@ -46,7 +50,7 @@ text: |
46 50 ```
47 51  
48 52 Este script deve ter permissões para poder ser executado no terminal.
49   - Podemos testar o programa no terminal `./gen-somar.py 1 50` e verificar que
  53 + Podemos testar o programa no terminal `./gen-somar.py 1 100` e verificar que
50 54 o output é uma pergunta válida em formato `yaml`. Agora é necessário indicar
51 55 que este script deve ser usado para gerar uma pergunta.
52 56  
... ... @@ -60,7 +64,8 @@ text: |
60 64 args: [1, 100]
61 65 ```
62 66  
63   - O programa pode receber uma lista de argumentos declarados em `args`.
  67 + O programa pode receber uma lista de argumentos de linha de comando
  68 + declarados em `args`.
64 69  
65 70 ---
66 71  
... ...
demo/questions/questions-tutorial.yaml
  Diff comments   View file @2e43c7a
... ... @@ -24,9 +24,8 @@
24 24 duration: 60 # duração da prova em minutos (default: inf)
25 25 autosubmit: true # submissão automática (default: false)
26 26 show_points: true # mostra cotação das perguntas (default: true)
27   - scale_points: true # recalcula cotações para [scale_min, scale_max]
28   - scale_max: 20 # limite superior da escala (default: 20)
29   - scale_min: 0 # limite inferior da escala (default: 0)
  27 + scale: [0, 20] # limites inferior e superior da escala (default: [0,20])
  28 + scale_points: true # normaliza cotações para a escala definida
30 29 debug: false # mostra informação de debug no browser
31 30  
32 31 # --------------------------------------------------------------------------
... ... @@ -48,9 +47,9 @@
48 47 points: 3.5
49 48  
50 49 - ref: pergunta2
51   - point: 2.0
  50 + points: 2.0
52 51  
53   - # a cotação é 1.0 por defeito, se omitida
  52 + # a cotação é 1.0 por defeito
54 53 - ref: pergunta3
55 54  
56 55 # uma string (não dict), é interpretada como referência
... ... @@ -153,17 +152,19 @@
153 152 entre 0 e 1, sendo atribuída a respectiva cotação, mas só o valor 1
154 153 representa uma opção certa.
155 154  
156   - Por defeito, as opções são apresentadas por ordem aleatória.
157   - Para manter a ordem definida acrescenta-se:
  155 + Por defeito, as opções são apresentadas por ordem aleatória, mas é possível
  156 + usar a ordem predefinida. Por exemplo, para manter a ordem e indicar que a
  157 + resposta correcta é a do meio define-se:
158 158  
159 159 ```yaml
  160 + correct: [0, 0, 1, 0, 0]
160 161 shuffle: false
161 162 ```
162 163  
163   - Por defeito, as respostas erradas descontam, tendo uma cotação de
164   - $-1/(n-1)$ do valor da pergunta, onde $n$ é o número de opções apresentadas
165   - ao aluno (a ideia é o valor esperado ser zero quando as respostas são
166   - aleatórias e uniformemente distribuídas). Para não descontar acrescenta-se:
  164 + As respostas erradas descontam, tendo uma cotação de $-1/(n-1)$ do valor da
  165 + pergunta, onde $n$ é o número de opções apresentadas ao aluno (a ideia é o
  166 + valor esperado ser zero quando as respostas são aleatórias e uniformemente
  167 + distribuídas). Para não descontar acrescenta-se:
167 168  
168 169 ```yaml
169 170 discount: false
... ... @@ -269,7 +270,7 @@
269 270 Neste caso, as respostas aceites são `azul`, `Azul` ou `AZUL`.
270 271  
271 272 Em alguns casos pode ser conveniente transformar a resposta antes de a
272   - comparar, por exemplo para remover espaços ou converter para maiúsculas.
  273 + comparar, por exemplo para remover espaços ou converter para minúsculas.
273 274 A opção `transform` permite dar uma sequência de transformações a aplicar à
274 275 resposta do aluno, por exemplo:
275 276  
... ... @@ -278,10 +279,10 @@
278 279 correct: ['azul']
279 280 ```
280 281  
281   - Neste momento estão disponíveis as seguintes transformações:
  282 + Estão disponíveis as seguintes transformações:
282 283  
283   - * `trim` remove os espaços do início e fim da resposta, os do meio mantêm-se
284   - inalterados.
  284 + * `trim` remove os espaços do início e fim da resposta, os espaços do meio
  285 + mantêm-se inalterados.
285 286 * `remove_space` remove todos os espaços (início, meio e fim).
286 287 * `normalize_space` remove espaços do início e fim (trim), e substitui
287 288 múltiplos espaços por um único espaço (no meio).
... ... @@ -375,10 +376,11 @@
375 376 são as mais flexíveis.
376 377  
377 378 A resposta é enviada para um programa externo para ser avaliada.
378   - O programa externo é um programa escrito numa linguagem qualquer, desde que
379   - seja executável pelo sistema operativo (pode ser um script ou binário).
380   - Este programa recebe a resposta submetida pelo aluno via `stdin` e devolve
381   - a classificação via `stdout`.
  379 + O programa externo é um programa que tem de ser executável pelo pelo
  380 + sistema operativo (pode ser um binário ou script desde que o respectivo
  381 + interpretador instalado).
  382 + Este programa externo recebe a resposta submetida pelo aluno via `stdin` e
  383 + devolve a classificação via `stdout`.
382 384 Exemplo:
383 385  
384 386 ```yaml
... ... @@ -566,7 +568,7 @@
566 568 duas possibilidads:
567 569  
568 570 - Imagens inline: não têm título definido e podem ser incluídas no meio de
569   - uma linha de texto usando`![alt text](image.jpg)`.
  571 + uma linha de texto usando `![alt text](image.jpg)`.
570 572 - Imagens centradas com título: `![alt text](image.jpg "Título da imagem")`.
571 573 O título é colocado por baixo da imagem. Pode ser uma string vazia.
572 574  
... ...