Initial QAML question data

README.md

@@ -0,0 +1,203 @@
+# 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
+```