---
# ----------------------------------------------------------------------------
- type: information
  ref: tut-test
  title: Configuração do teste
  text: |
    O teste é configurado num ficheiro `yaml`
    (ver especificação [aqui](https://yaml.org)).
    A configuração contém a identificação do teste, base de dados dos alunos,
    ficheiros de perguntas a importar e uma selecção de perguntas e respectivas
    cotações.

    Exemplo:

    ```yaml
    ---
    # --------------------------------------------------------------------------
    ref: tutorial              # referência, pode ser reusada em vários turnos
    title: Demonstração        # título da prova
    database: students.db      # base de dados já inicializada com initdb
    answers_dir: ans           # directório onde ficam os testes entregues

    # opcional
    duration: 60               # duração da prova em minutos (default=inf)
    show_points: true          # mostra cotação das perguntas
    scale_points: true         # recalcula cotações para a escala [0, scale_max]
    scale_max: 20              # limite superior da escala
    debug: false               # mostra informação de debug na prova (browser)

    # --------------------------------------------------------------------------
    questions_dir: ~/topics    # raíz da árvore de directórios das perguntas

    # Ficheiros de perguntas a importar (relativamente a `questions_dir`)
    files:
      - tabelas.yaml
      - topic_A/questions.yaml
      - topic_B/part_1/questions.yaml
      - topic_B/part_2/questions.yaml

    # --------------------------------------------------------------------------
    # Especificação das perguntas do teste e respectivas cotações.
    # O teste é uma lista de perguntas, onde cada pergunta é especificada num
    # dicionário com a referência da pergunta e a respectiva cotação.
    questions:
      - ref: pergunta1
        points: 3.5

      - ref: pergunta2
        points: 2

      - ref: tabela-auxiliar

      # escolhe aleatoriamente uma das variantes
      - ref: [pergunta3a, pergunta3b]
        points: 0.5

      # a cotação é 1.0 por defeito (se omitida)
      - ref: pergunta4

      # se for uma string (não dict), é interpretada como referência
      - pergunta5
    # --------------------------------------------------------------------------
    ```

    A ordem das perguntas é mantida quando apresentada para o aluno.

    O mesmo teste pode ser realizado várias vezes em vários turnos, não é
    necessário alterar nada.

# ----------------------------------------------------------------------------
- type: information
  ref: tut-questions
  title: Especificação das perguntas
  text: |
    As perguntas estão definidas num ou mais ficheiros `yaml` como uma lista de
    dicionários, onde cada pergunta é um dicionário.

    Por exemplo, um ficheiro com o conteúdo abaixo contém duas perguntas, uma
    de escolha múltipla e outra apenas informativa:

    ```yaml
    ---
    #-----------------------------------------------------------------------------
    - type: radio
      ref: chave-unica-1
      text: Quanto é $1+1$?
      options:
        - 1
        - 2
        - 3

    #-----------------------------------------------------------------------------
    - type: information
      ref: chave-unica-2
      text: |
        Quando o texto da pergunta tem várias linhas, dá jeito usar o símbolo
        `|` de pipe, para indicar que tudo o que estiver indentado faz parte do
        texto.
        É o caso desta pergunta.

        O texto das perguntas é escrito em `markdown`.

    #-----------------------------------------------------------------------------
    ```

    As chaves são usadas para construir o teste e não se podem repetir em
    ficheiros diferentes. A seguir vamos ver exemplos de cada tipo de pergunta.

# ----------------------------------------------------------------------------
- type: radio
  ref: tut-radio
  title: Escolha simples, uma opção correcta.
  text: |
    As perguntas de escolha simples, permitem fazer uma pergunta e apresentar
    várias opções de resposta em que apenas uma delas está certa.
    A utilização mais simples é a seguinte:

    ```yaml
    - type: radio
      ref: pergunta-1
      title: Escolha simples, uma opção correcta.
      text: |
        Bla bla bla.
      options:
        - Opção 0
        - Opção 1
        - Opção 2
        - Opção 3
        - Opção 4
    ```

    Sem outras configurações, assume-se que a primeira opção é a resposta
    correcta ("Opção 0" neste caso) e as 5 opções são apresentadas por ordem
    aleatória.

    Para evitar que os alunos memorizem os textos das opções, podem definir-se
    várias opções correctas com escrita ligeiramente diferente, sendo escolhida
    apenas uma delas para apresentação.
    Por exemplo, se as 2 primeiras opções estiverem correctas e as restantes
    erradas, e quisermos apresentar ao aluno 3 opções no total, acrescenta-se:

    ```yaml
      correct: [1, 1, 0, 0, 0]
      choose: 3
    ```

    Neste caso, será escolhida uma opção certa de entre o conjunto das certas
    e duas erradas de entre o conjunto das erradas.
    Os valores em `correct` representam o grau de correcção no intervalo [0, 1]
    onde 1 representa 100% certo e 0 representa 0%.

    Por defeito, as opções são apresentadas por ordem aleatória.
    Para manter a ordem acrescenta-se:

    ```yaml
      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:

    ```yaml
      discount: false
    ```
  options:
    - Opção 0 (certa)
    - Opção 1 (certa)
    - Opção 2
    - Opção 3
    - Opção 4
  correct: [1, 1, 0, 0, 0]
  choose: 3
  solution: |
    A solução correcta é a **Opção 0** ou a **Opção 1**.

# ----------------------------------------------------------------------------
- ref: tut-checkbox
  type: checkbox
  title: Escolha múltipla, várias opções correctas
  text: |
    As perguntas de escolha múltipla permitem apresentar um conjunto de opções
    podendo ser seleccionadas várias em simultaneo.
    Funcionam como múltiplas perguntas independentes de resposta sim/não.

    Cada opção seleccionada (`sim`) recebe a cotação indicada em `correct`.
    Cada opção não seleccionadas (`não`) tem a cotação simétrica.

    ```yaml
    - type: checkbox
      ref: tut-checkbox
      title: Escolha múltipla, várias opções correctas
      text: |
        Bla bla bla.
      options:
        - Opção 0 (certa)
        - Opção 1
        - Opção 2
        - Opção 3 (certa)
        - Opção 4
      correct: [1, -1, -1, 1, -1]
    ```

    Neste exemplo, seleccionando as opções 0 e 3 obtém-se cotação +1 em cada
    uma, enquanto que seleccionando as opções 1, 2 e 4 obtém-se cotação -1.
    As opções não seleccionadas pelo aluno dão a cotação simétrica à indicada.
    Por exemplo se não seleccionar a opção 0, tem cotação -1, e não
    seleccionando a opção 1 obtém-se +1.

    *(Note que o `correct` não funciona do mesmo modo que nas perguntas do
    tipo `radio`. Em geral, um aluno só deve responder se souber mais de metade
    das respostas, caso contrário arrisca-se a ter cotação negativa na
    pergunta. Não há forma de não responder a apenas algumas delas.)*

    Cada opção pode opcionalmente ser escrita como uma afirmação e o seu
    contrário, de maneira a aumentar a variabilidade dos textos.
    Por exemplo:

    ```yaml
      options:
        - ["O céu é azul", "O céu não é azul"]
        - ["Um triangulo tem 3 lados", "Um triangulo tem 2 lados"]
        - O nosso planeta tem um satélite natural
      correct: [1, 1, 1]
    ```

    Assume-se que a primeira alternativa de cada opção tem a cotação indicada
    em `correct`, enquanto a segunda alternativa tem a cotação simétrica.

    Tal como nas perguntas do tipo `radio`, podem ser usadas as configurações
    `shuffle` e `discount` com valor `false` para as desactivar.
    Se `discount` é `false` então as respostas erradas têm cotação 0 em vez do
    simétrico.
  options:
    - ['Opção 0 (sim)', 'Opção 0 (não)']
    - ['Opção 1 (não)', 'Opção 1 (sim)']
    - Opção 2 (não)
    - Opção 3 (sim)
  correct: [1, -1, -1, 1]
  shuffle: false

# ----------------------------------------------------------------------------
- type: text
  ref: tut-text
  title: Resposta de texto em linha
  text: |
    Este tipo de perguntas permite uma resposta numa linha de texto. A resposta
    está correcta se coincidir exactamente com alguma das respostas admissíveis.

    ```yaml
    - type: text
      ref: tut-text
      title: Resposta de texto em linha
      text: |
        De que cor é o céu?

        Escreva a resposta em português.
      correct: ['azul', 'Azul', 'AZUL']
    ```

    Neste caso, as respostas aceites são `azul`, `Azul` ou `AZUL`.
  correct: ['azul', 'Azul', 'AZUL']

# ---------------------------------------------------------------------------
- type: text-regex
  ref: tut-text-regex
  title: Resposta de texto em linha, expressão regular
  text: |
    Este tipo de pergunta é semelhante à linha de texto da pergunta anterior.
    A única diferença é que esta é validada por uma expressão regular.

    ```yaml
    - type: text-regex
      ref: tut-text-regex
      title: Resposta de texto em linha
      text: |
        Bla bla bla
      correct: '(VERDE|[Vv]erde)'
    ```

    Neste exemplo a expressão regular é `(VERDE|[Vv]erde)`.

    ---

    **Atenção:** A expressão regular deve seguir as convenções da suportadas em
    python (ver
    [Regular expression operations](https://docs.python.org/3/library/re.html)).
    Em particular, a expressão regular acima também aceita a resposta
    `verde, azul`.
    Possivelmente devia marcar-se o final com o cifrão `(VERDE|[Vv]erde)$`.

  correct: '(VERDE|[Vv]erde)'

# ---------------------------------------------------------------------------
- type: numeric-interval
  ref: tut-numeric-interval
  title: Resposta numérica em linha de texto
  text: |
    Este tipo de perguntas esperam uma resposta numérica (vírgula flutuante).
    O resultado é considerado correcto se estiver dentro do intervalo fechado
    indicado.

    ```yaml
    - type: numeric-interval
      ref: tut-numeric-interval
      title: Resposta numérica em linha de texto
      text: |
        Escreva o número $\pi$ com pelo menos duas casa decimais.
      correct: [3.14, 3.15]
    ```

    Neste exemplo o intervalo de respostas correctas é [3.14, 3.15].

    **Atenção:** as respostas têm de usar o ponto como separador decimal.
    Em geral são aceites números inteiros, como `123`,
    ou em vírgula flutuante, como em `0.23`, `1e-3`.
  correct: [3.14, 3.15]
  solution: |
    Sabems que $\pi\approx 3.14159265359$.
    Portanto, um exemplo de uma resposta correcta é `3.1416`.

# ---------------------------------------------------------------------------
- type: textarea
  ref: tut-textarea
  title: Resposta em múltiplas linhas de texto
  text: |
    Este tipo de perguntas permitem respostas em múltiplas linhas de texto, que
    podem ser úteis por exemplo para introduzir código.

    A resposta é enviada para um programa externo para ser avaliada.
    O programa externo é um programa qualquer executável pelo sistema.
    Este recebe a resposta submetida pelo aluno via `stdin` e devolve a
    classificação via `stdout`.
    Exemplo:

    ```yaml
    - type: textarea
      ref: tut-textarea
      title: Resposta em múltiplas linhas de texto
      text: |
        Bla bla bla
      correct: correct/correct-question.py   # programa a executar
      timeout: 5
    ```

    Neste exemplo, o programa de avaliação é um script python que verifica se a
    resposta contém as três palavras red, green e blue, e calcula uma nota no
    intervalo 0.0 a 1.0.
    O programa externo é um programa executável no sistema, escrito em
    qualquer linguagem de programação. A interacção com o servidor faz-se
    sempre via stdin/stdout.

    Se o programa externo exceder o `timeout` indicado (em segundos),
    é automaticamente cancelado e é atribuída a classificação de 0.0 valores.

    Após terminar a correcção, o programa externo deve enviar a classificação
    para o stdout.
    Pode simplesmente fazer `print` da classificação como um número em vírgula
    flutuante, por exemplo

    ```yaml
    0.75
    ```

    ou opcionalmente escrever em formato yaml, eventualmente com um comentário
    que será arquivado com o teste.
    Exemplo:

    ```yaml
    grade: 0.5
    comments: |
      Esqueceu-se de algumas cores.
      A resposta correcta era `red green blue`.
    ```

    O comentário é mostrado na revisão de prova.
  answer: |
    Esta caixa aumenta de tamanho automaticamente e
    pode estar previamente preenchida (use answer: texto).
  correct: correct/correct-question.py
  timeout: 5

# ---------------------------------------------------------------------------
- type: information
  ref: tut-information
  title: Texto informativo
  text: |
    As perguntas deste tipo não contam para avaliação. O objectivo é fornecer
    instruções para os alunos, por exemplo tabelas para consulta, fórmulas, etc.
    Nesta, tal como em todos os tipos de perguntas podem escrever-se fórmulas
    em LaTeX. Exemplo:

    A distribuição gaussiana $\mathcal{N}(x\mid\mu,\sigma^2)$ é
    definida pela função densidade de probabilidade

    $$
    p(x) = \frac{1}{\sqrt{2\pi\sigma^2}}
           \exp\Big({-\frac{(x-\mu)^2}{2\sigma^2}}\Big).
    $$

    ---

    ```yaml
    - type: information
      ref: tut-information
      title: Texto informativo
      text: |
        A distribuição gaussiana $\mathcal{N}(x\mid\mu,\sigma^2)$ é
        definida pela função densidade de probabilidade

        $$
        p(x) = \frac{1}{\sqrt{2\pi\sigma^2}}
               \exp\Big({-\frac{(x-\mu)^2}{2\sigma^2}}\Big).
        $$
    ```

# ---------------------------------------------------------------------------
- type: success
  ref: tut-success
  title: Texto informativo (sucesso)
  text: |
    Também não conta para avaliação. É apenas o aspecto gráfico que muda.

    Além das fórmulas LaTeX, também se pode escrever troços de código:

    ```C
    int main() {
        printf("Hello world!");
        return 0;   // comentario
    }
    ```

    ---

        - type: success
          ref: tut-success
          title: Texto informativo (sucesso)
          text: |
            Também não conta para avaliação.
            É apenas o aspecto gráfico que muda.

            Além das fórmulas LaTeX, também se pode escrever troços de código:

            ```C
            int main() {
                printf("Hello world!");
                return 0;   // comentario
            }
            ```

# ---------------------------------------------------------------------------
- type: warning
  ref: tut-warning
  title: Texto informativo (aviso)
  text: |
    Não conta para avaliação.

    Neste exemplo mostramos como se pode construir uma tabela como a seguinte:

    Left             | Center           | Right
    -----------------|:----------------:|----------:
    *hello*          | $\sin(x^2)$      | $1600.00
    **world**        | $\frac{1}{2\pi}$ |   $12.50
    `code`           | $\sqrt{\pi}$     |    $1.99

    As tabelas podem conter Markdown e LaTeX.

    ---

    ```yaml
    - type: warning
      ref: tut-warning
      title: Texto informativo (aviso)
      text: |
        Bla bla bla

        Left             | Center           | Right
        -----------------|:----------------:|----------:
        *hello*          | $\sin(x^2)$      | $1600.00
        **world**        | $\frac{1}{2\pi}$ |   $12.50
        `code`           | $\sqrt{\pi}$     |    $1.99
    ```

# ----------------------------------------------------------------------------
- type: alert
  ref: tut-alert
  title: Texto informativo (perigo)
  text: |
    Não conta para avaliação. Texto importante.

    ![planetas](planets.png "Planetas do Sistema Solar")

    As imagens podem ser adicionadas usando a notação standard em markdown. Há
    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)`.
    - Imagens centradas com título: `![alt text](image.jpg "Título da imagem")`.
    O título aprece por baixo da imagem. O título pode ser uma string vazia.

# ----------------------------------------------------------------------------
- type: information
  text: This question is not included in the test and will not show up.

# ----------------------------------------------------------------------------