# Deklaratywne-Machen

Repozytorium zawiera bazę pytań do quizu z Programowania Deklaratywnego.

W repozytorium znajdują się dane quizu: `pytania.txt` oraz opcjonalnie katalog `img/` z obrazkami używanymi w pytaniach. Kod aplikacji nie jest częścią tego repozytorium.

## Jak zgłaszać poprawki

Poprawki zgłaszamy przez Pull Request.

Logowanie w systemie nie wymaga weryfikacji e-mail. Można podać dowolne dane; system jest w pełni anonimowy.

Najczęstsze dobre zmiany:

- poprawienie literówki,
- oznaczenie prawidłowej odpowiedzi jako `-|`,
- usunięcie błędnej odpowiedzi,
- dopisanie źródła w komentarzu `//`,
- dodanie brakującego obrazka do `img/`.

Nie zmieniaj formatu pliku na pełny Markdown, JSON, CSV ani HTML. To repozytorium używa prostego formatu QAML opisanego niżej.

## QAML

QAML, czyli Question Answer Markdown Lines, to prosty liniowy format zapisu pytań testowych wielokrotnego wyboru.

Parser interpretuje wyłącznie początki linii:

- linia pytania,
- linia odpowiedzi błędnej,
- linia odpowiedzi poprawnej,
- komentarz,
- pusta linia.

Treść pytania i odpowiedzi może zawierać Markdown, HTML oraz inline LaTeX, ale parser traktuje je jako zwykły tekst.

## Minimalny przykład

```text
// Przykładowa sekcja

Zaznacz zdania prawdziwe
- To jest odpowiedź błędna.
-| To jest odpowiedź poprawna.
- To jest kolejna odpowiedź błędna.

Ile wynosi $2 + 2$?
- 3
-| 4
- 5
```

## Reguły składni

### Pytanie

Pytaniem jest każda niepusta linia, która nie zaczyna się od `-` ani `//`.

Pytanie musi mieścić się w jednej linii.

Poprawnie:

```text
Zaznacz zdania prawdziwe dotyczące indukcji matematycznej.
```

Niepoprawnie:

```text
Zaznacz zdania prawdziwe
dotyczące indukcji matematycznej.
```

Druga linia zostanie zinterpretowana jako osobne pytanie.

### Odpowiedź błędna

Odpowiedź błędna zaczyna się od pojedynczego myślnika `-`.

Poprawne są oba style:

```text
- Odpowiedź błędna
-Odpowiedź błędna
```

Parser usuwa znak `-`, a następnie przycina białe znaki z początku i końca odpowiedzi.

### Odpowiedź poprawna

Odpowiedź poprawna zaczyna się od `-|`.

Poprawne są oba style:

```text
-| Odpowiedź poprawna
-|Odpowiedź poprawna
```

Parser usuwa prefiks `-|`, a następnie przycina białe znaki z początku i końca odpowiedzi.

### Liczba poprawnych odpowiedzi

Format dopuszcza dowolną liczbę poprawnych odpowiedzi, w tym zero poprawnych odpowiedzi albo wszystkie odpowiedzi poprawne.

```text
Wskaż liczby pierwsze
-| 2
-| 3
- 4
-| 5
```

Parser nie narzuca liczby poprawnych odpowiedzi.

### Komentarze

Komentarzem jest linia zaczynająca się od `//`.

```text
// Sterna 2024/2025 B
// Formanowicz 2021-2022
```

Komentarze są ignorowane przez parser. Można ich używać jako nagłówków sekcji, źródeł, dat albo notatek.

### Puste linie

Puste linie są ignorowane. Można ich używać do oddzielania pytań, odpowiedzi lub sekcji.

## LaTeX

Dozwolony jest inline LaTeX między pojedynczymi znakami dolara:

```text
Ile wynosi $\binom{n}{k}$?
```

Nie jest częścią formalnej składni:

```text
$$
a^2 + b^2 = c^2
$$
```

Parser nie waliduje poprawności LaTeX-a.

## HTML i obrazki

HTML jest dopuszczony jako część treści pytania lub odpowiedzi.

```text
Zaznacz funkcję odpowiadającą obrazkowi <img src="img/example.png" height="100" />
-| $f(x) = x^2$
- $f(x) = x$
```

Jeżeli `pytania.txt` odwołuje się do obrazka przez `img/...`, plik musi istnieć w katalogu `img/` w tym repozytorium.

## Jedna linia = jeden element

Każde pytanie i każda odpowiedź muszą mieścić się w jednej fizycznej linii.

Poprawnie:

```text
Zaznacz zdania prawdziwe dotyczące funkcji $f(x) = x^2$.
-| Funkcja jest parzysta.
- Funkcja jest nieparzysta.
```

Niepoprawnie:

```text
Zaznacz zdania prawdziwe dotyczące funkcji
$f(x) = x^2$.
-| Funkcja jest parzysta.
```

Druga linia zostanie zinterpretowana jako nowe pytanie.

## Walidacja lokalna

```bash
php tools/validate_qaml.php pytania.txt
```