- type: information
  ref: tut-test
  title: Configuração do teste
  text: |
    O teste é configurado num ficheiro `yaml` (ver especificação [aqui](https://yaml.org)).
    Esta configuração indica 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
        title: Teste de Avaliação
        database: demo/students.db
        answers_dir: demo/ans

        # (opcional) minutos
        duration: 90

        # (opcional, default: False) mostra cotação das perguntas aos alunos, escala 0-20.
        show_points: True

        # (opcional, default: False)
        debug: False

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

        # Ficheiros de perguntas a importar
        files:
          - topico_A/parte_1/questions.yaml
          - topico_A/parte_2/questions.yaml
          - topico_B/parte_3/questions.yaml

        #-----------------------------------------------------------------------------
        # Perguntas do teste e respectivas cotações
        questions:
          - ref: pergunta1
            grade: 3.5

          - ref: pergunta2
            grade: 2

          - ref: tabela-auxiliar
          
          # escolhe uma das seguintes aleatoriamente
          - ref: [ pergunta3a, pergunta3b ]
            grade: 0.5

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

    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
# ----------------------------------------------------------------------------
- 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]
  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]
# ---------------------------------------------------------------------------
- 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 (perigo!). Não conta para avaliação.

    ![imagem](image.jpg "Título da imagem")

    As imagens ainda não estão a funcionar.