---
# ----------------------------------------------------------------------------
- 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:         Referência do teste. Pode ser reusada em vários turnos
    # title:       Título do teste
    # database:    Base de dados previamente inicializada com os alunos (usando initdb.py)
    # answers_dir: Directório onde vão ficar guardados os testes dos alunos
    ref: tutorial
    title: Teste de Avaliação
    database: demo/students.db
    answers_dir: demo/ans

    # Duração do teste em minutos, apenas informativo. (default: infinito)
    duration: 60

    # Mostrar cotação das perguntas. (default: false)
    show_points: true

    # Pontos das perguntas são automaticamente convertidos para a escala dada
    # (defaults: true, 20)
    scale_points: true
    scale_max: 20

    # (opcional, default: false)
    debug: false

    # ----------------------------------------------------------------------------
    # Directório base onde estão as perguntas
    questions_dir: ~/topics/P1

    # Ficheiros de perguntas a importar (relativamente a ~/topics/P1)
    files:
      - topico_A/parte_1/questions.yaml
      - topico_A/parte_2/questions.yaml
      - topico_B/questions.yaml

    # ----------------------------------------------------------------------------
    # Especificação das perguntas do teste e cotações.
    # O teste é uma lista de perguntas
    # Cada pergunta é um dicionário com ref da pergunta e cotação.
    questions:
      - ref: pergunta1
        points: 3.5

      - ref: pergunta2
        points: 2

      - ref: tabela-auxiliar

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

      # a cotação é 1.0 por defeito, caso não esteja definida
      - ref: pergunta4

      # ou ainda mais simples
      - pergunta5
    # ----------------------------------------------------------------------------
    ```

    A ordem das perguntas é mantida.

    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: info
      ref: chave-unica-2
      text: |
        Quando o texto da pergunta tem várias linhas, dá jeito usar o símbolo
        pipe, para indicar que tudo o que estiver indentado relativamente à
        linha `text: |` faz parte do corpo do texto.

        É o caso desta pergunta.

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

    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 ("Opção 0" neste
    caso) é a resposta correcta, e todas 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
    apresentada apenas uma delas.
    Por exemplo, se as 2 primeiras opções estiverem correctas e as restantes
    erradas, e quisermos apresentar 3 opções no total com uma delas correcta
    adiciona-se:

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

    Assim será escolhida uma opção certa e mais 2 opções erradas.

    Por defeito, as opções são sempre baralhadas. Adicionando `shuffle: False`
    evita que o sejam.

    Por defeito, as respostas erradas descontam 1/(n-1) do valor da pergunta,
    onde n é o número de opções apresentadas. Para não descontar usa-se
    `discount: False`.

  options:
      - Opção 0
      - Opção 1
      - Opção 2
      - Opção 3
      - Opção 4
  correct: [1, 1, 0, 0, 0]
  choose: 3
  shuffle: true
  solution: |
    A solução correcta é a **opção 0**.

# ----------------------------------------------------------------------------
- type: checkbox
  ref: tut-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 com a cotação indicada em
    `correct`. As opções não seleccionadas têm a cotação simétrica à indicada.
    Deste modo, um aluno só deve responder se tiver confiança em pelo menos
    metade das respostas, caso contrário arrisca-se a ter cotação negativa na
    pergunta.

    ```yaml
        - type: checkbox
          ref: tut-checkbox
          title: Escolha múltipla, várias opções correctas
          text: |
            Bla bla bla.
          options:
              - Opção 0
              - Opção 1
              - Opção 2
              - Opção 3
              - 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.

    Cada opção pode opcionalmente ser escrita como uma afirmação e o seu
    contrário, de maneira a dar mais aleatoriedade à apresentação deste tipo de
    perguntas. 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 +1,
    enquanto a segunda alternativa tem a cotação simétrica -1 (desconta se for
    seleccionada).

    Estão disponíveis as configurações `shuffle` e `discount`.
    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 1 (não)
      - Opção 2 (não)
      - Opção 3 (sim)
  correct: [1, -1, -1, 1]
  choose: 3
  shuffle: true


# ----------------------------------------------------------------------------
- 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 com alguma das respostas admissíveis.

    ```yaml
        - type: text
          ref: tut-text
          title: Resposta de texto em linha
          text: |
            Bla bla bla
          correct: ['azul', 'Azul', 'AZUL']
    ```

    Neste exemplo a resposta correcta é `azul`, `Azul` ou `AZUL`.
  correct: ['azul', 'Azul', 'AZUL']


# ---------------------------------------------------------------------------
- type: text-regex
  ref: tut-text-regex
  title: Resposta de texto em linha
  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: !regex '(VERDE|[Vv]erde)'
    ```

    Neste exemplo a expressão regular é `(VERDE|[Vv]erde)`.
  correct: !regex '(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: |
            Bla bla bla
          correct: [3.14, 3.15]
    ```

    Neste exemplo o intervalo de respostas correctas é [3.14, 3.15].
  correct: [3.14, 3.15]
  solution: |
    Um exemplo de uma resposta correcta é o número $\pi\approx 3.14159265359$.


# ---------------------------------------------------------------------------
- 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 validar código.
    A resposta é enviada para ser avaliada por um programa externo (programa
    executável).
    O programa externo, recebe a resposta 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
          lines: 3
          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 de
    0.0 a 1.0.
    O programa externo pode ser escrito em qualquer linguagem e a interacção
    com o servidor faz-se via stdin/stdout.
    Se o programa externo demorar mais do que o `timout` indicado, é
    automaticamente cancelado e é atribuída a classificação de 0.0 valores.
    `lines: 3` é a dimensão inicial da caixa de texto (pode depois ser
    redimensionada pelo aluno).

    O programa externo deve atribuir uma classificação entre 0.0 e 1.0. Pode
    simplesmente fazer print da classificação como um número, ou opcionalmente escrever em formato yaml eventualmente com um comentário. Exemplo:

    ```yaml
        grade: 0.5
        comments: A resposta correcta é "red green blue".
    ```

    O comentário é mostrado na revisão de prova.
  correct: correct/correct-question.py
  lines: 3
  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 como em todos os tipos de perguntas pode escrever-se fórmulas em
    LaTeX. Exemplo:

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

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

    Produz:

    A distribuição gaussiana $\mathcal{N}(x\mid\mu,\sigma^2)$ é definida por

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


# ---------------------------------------------------------------------------
- type: success
  ref: tut-success
  title: Texto informativo (sucesso)
  text: |
    Também não conta para avaliação.

    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
    }
    ```

    Faz-se assim:

        - type: success
          ref: tut-success
          title: Texto informativo (sucesso)
          text: |
            Também não conta para avaliação.

            Já vimos como se introduzem 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
    -----------------|:-------------:|----------:
    $\sin(x^2)$      | *hello*       | $1600.00
    $\frac{1}{2\pi}$ | **world**     |   $12.50
    $\sqrt{\pi}$     | `code`        |    $1.99

    As tabelas podem conter Markdown e LaTeX. Faz-se assim:

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

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

    A linha de separação entre o cabeçalho e o corpo da tabela indica o
    alinhamento da coluna com os sinais de dois-pontos.


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

    ![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.


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