updates demo-tutorial

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