deklaratywne-machen/README.md

# Baza pytań quizu

To repozytorium zawiera dane quizu: `pytania.txt` oraz opcjonalny katalog `img/` z obrazkami używanymi w pytaniach.

Kod aplikacji nie jest częścią tego repozytorium. Zmiany w pytaniach należy zgłaszać przez Pull Request.

## QAML — Question Answer Markdown Lines

QAML to prosty liniowy format zapisu pytań testowych wielokrotnego wyboru.

Format wygląda jak Markdown, ale jego składnia strukturalna jest znacznie prostsza. Parser nie analizuje pełnego Markdowna. 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

### 1. Pytanie

Pytaniem jest każda niepusta linia, która:

- nie zaczyna się od znaku `-`,
- nie zaczyna się od `//`.

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

Drugi zapis zostanie zinterpretowany jako dwa osobne pytania.

### 2. 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.

### 3. 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.

### 4. Pytania jednokrotnego i wielokrotnego wyboru

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

Pytanie jednokrotnego wyboru:

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

Pytanie wielokrotnego wyboru:

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

Parser nie narzuca liczby poprawnych odpowiedzi. Zero poprawnych odpowiedzi może oznaczać zadanie, w którym żadna odpowiedź nie jest prawdziwa, a oznaczenie wszystkich odpowiedzi jako `-|` może oznaczać zadanie, w którym wszystkie odpowiedzi są prawdziwe.

### 5. Komentarze

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

Przykłady:

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

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

### 6. 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}$?
```

Dozwolony przykład:

```text
-| Liczba kombinacji wynosi $\binom{n}{k}$.
```

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

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

oraz:

```text
\[ a^2 + b^2 = c^2 \]
```

Parser demonstracyjny nie waliduje poprawności LaTeX-a. Traktuje zapis `$...$` jako zwykły fragment tekstu.

## HTML i obrazki

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

Przykład:

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

To najważniejsza zasada formatu.

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

Parser potraktuje drugą linię jako nowe pytanie.

## Walidacja lokalna

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