user
152 lines
4.5 KiB
Markdown
152 lines
4.5 KiB
Markdown
# 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
|
|
│ ├── reference-registry.schema.json
|
|
│ └── series.schema.json
|
|
├── templates/
|
|
│ ├── karta-klasyczna.json
|
|
│ ├── karta-5a.json
|
|
│ └── karta-5b.json
|
|
├── tools/render_card.py
|
|
├── docs/
|
|
│ ├── CARD.md
|
|
│ ├── api.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`. Workflow Gitei pozostaje samowystarczalny i zawsze uruchamia
|
|
walidację relacji generatora; pełną walidację schematów można włączyć lokalnie:
|
|
|
|
```bash
|
|
python3 -m pip install -r requirements-dev.txt
|
|
CARD_LAYOUTS_REQUIRE_JSONSCHEMA=1 python3 scripts/check_repository.py
|
|
```
|
|
|
|
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.
|
|
|
|
Sekcje mogą także deklarować strukturalne `assets` (najczęściej zrzuty ekranu
|
|
z `doc/assets`). Generator wstawia je do TeX/PDF i HTML, zachowuje podpis,
|
|
tekst alternatywny i stabilną etykietę oraz przygotowuje link do pełnego
|
|
obrazu w wersji ekranowej.
|
|
|
|
Szczegóły modelu karty opisuje [docs/CARD.md](docs/CARD.md), manifestu
|
|
serii [docs/SERIES.md](docs/SERIES.md), a wspólnego serwera aplikacji
|
|
[docs/api.md](docs/api.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.
|
|
|
|
## Rejestry referencji
|
|
|
|
Wspólnej strategii, innej karty, treści ani wzoru nie kopiujemy do karty.
|
|
`card_source.json` przechowuje stabilne UUID-y, a generator rozwiązuje je przez
|
|
lokalny kanoniczny rejestr JSON. Widocznym hiperłączem jest kod strategii
|
|
(`Mxx`), nazwa karty albo etykieta treści/wzoru. Model danych i przykład są w
|
|
[docs/CARD.md](docs/CARD.md#referencje-zewnętrzne-bez-kopiowania-treści).
|
|
|
|
## 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ść.
|