Add shared card schemas layouts and renderer

2026-07-15 08:41:20 +02:00
commit 65299458ed
19 changed files with 7786 additions and 0 deletions
@@ -0,0 +1,129 @@
+# card-layouts
+
+Wspólne źródło schematów, layoutów i generatora kart pracy używanych przez
+serie edukacyjne. Jeden plik `card_source.json` opisuje treść oraz mapowanie
+edukacyjne, a `tools/render_card.py` generuje z niego równolegle LaTeX i HTML.
+
+Repozytorium rozdziela trzy warstwy:
+
+1. **Treść karty** — `card_source.json`: cele, efekty nauczania, kryteria,
+   drzewka marginesowe, kroki oraz zadania.
+2. **Layout** — `templates/*.json`: geometria strony, role marginesów,
+   komponenty i wybór emitera TeX/HTML.
+3. **Seria** — `series.json`: kolejność kart, repozytoria, wersje i kontrakt
+   uruchamiania zadań.
+
+## Zawartość
+
+```text
+card-layouts/
+├── schemas/
+│   ├── card-source.schema.json
+│   ├── card-template.schema.json
+│   └── series.schema.json
+├── templates/
+│   ├── karta-klasyczna.json
+│   ├── karta-5a.json
+│   └── karta-5b.json
+├── tools/render_card.py
+├── docs/
+│   ├── CARD.md
+│   └── SERIES.md
+└── examples/
+    ├── card/
+    └── series/
+```
+
+## Layouty
+
+| Layout | Przeznaczenie | Marginesy | Emitery |
+|---|---|---|---|
+| `karta-klasyczna` | elastyczna karta sekcyjna | dwa panele drzewek | TeX + HTML |
+| `karta-5a` | wielostronicowa karta A4 landscape | TECH po lewej, OG po prawej | TeX + HTML |
+| `karta-5b` | referencyjna karta A4 portrait | gołe drzewka TECH/OG | TeX + HTML |
+
+`karta-5b` jest obecnym layoutem referencyjnym. Używa geometrii
+`0,55 / 2,05 / 0,55 / 14,70 / 0,55 / 2,05 / 0,55 cm`; lewy margines
+zawiera efekty zawodowe `TECH`, a prawy efekty ogólne `OG`.
+
+## Szybki start
+
+Wygenerowanie przykładowej karty:
+
+```bash
+make render-example
+```
+
+Powstaną:
+
+```text
+examples/card/build/tex/main.tex
+examples/card/build/html/index.html
+examples/card/build/html/style.css
+```
+
+Złożenie kontrolnego PDF-u wymaga `latexmk` i pakietów LaTeX używanych przez
+generator:
+
+```bash
+make pdf-example
+```
+
+Pełna kontrola repozytorium:
+
+```bash
+make check
+```
+
+Walidacja względem JSON Schema jest wykonywana, gdy dostępny jest pakiet
+`jsonschema`; CI instaluje go z `requirements-dev.txt`.
+
+Generator można też wywołać bezpośrednio dla dowolnego katalogu karty:
+
+```bash
+python3 tools/render_card.py /sciezka/do/karty
+python3 tools/render_card.py /sciezka/do/karty --template templates/karta-5b.json
+```
+
+Katalog karty musi zawierać `json/card_source.json`. Ścieżki wyjściowe
+określa obiekt `generated` w tym pliku.
+
+## Model edukacyjny
+
+Źródłem marginesów nie jest luźny tekst. Relacje są jawne:
+
+```text
+WE (wymaganie edukacyjne)
+└── EN/EK (efekt nauczania lub efekt kształcenia)
+    └── KW (kryterium weryfikacji)
+```
+
+Każda sekcja i każdy krok mogą wskazywać te same drzewka przez `tree_refs`.
+Dzięki temu TeX i HTML pokazują identyczne powiązanie treści z efektami.
+
+Szczegóły modelu karty opisuje [docs/CARD.md](docs/CARD.md), a manifestu
+serii [docs/SERIES.md](docs/SERIES.md).
+
+## Słowniki podstaw programowych
+
+Generator może rozszerzać skróty z zewnętrznych słowników JSON. Karta podaje
+ich katalog przez:
+
+```json
+{
+  "dictionary_refs": {
+    "pp_json_root": "../../pp/json"
+  }
+}
+```
+
+Brak słowników nie blokuje generowania, jeśli karta zawiera kompletne pola
+`display` i `text` we własnych drzewkach.
+
+## Zasada zmian
+
+- zmiana treści należy do `card_source.json`;
+- zmiana geometrii i stylu należy do `templates/*.json` oraz emitera;
+- wygenerowanych plików nie edytujemy ręcznie;
+- nowa wersja layoutu wymaga aktualizacji numeru `version`, przykładu i testu
+  obu wyjść.