user
201 lines
7.3 KiB
Markdown
201 lines
7.3 KiB
Markdown
# Opis repozytorium pojedynczej karty
|
||
|
||
Każda karta jest osobnym repozytorium lub samodzielnym katalogiem. Jej źródłem
|
||
prawdy jest `json/card_source.json`; pliki TeX i HTML są artefaktami
|
||
generowanymi.
|
||
|
||
## Minimalne drzewo
|
||
|
||
```text
|
||
moja-karta/
|
||
├── README.md
|
||
├── json/card_source.json
|
||
├── doc/
|
||
├── web/
|
||
└── src/
|
||
```
|
||
|
||
## Obowiązkowe warstwy danych
|
||
|
||
### Metadane
|
||
|
||
Obiekt `card` identyfikuje serię, numer, wersję, UUID, autora i status.
|
||
Obiekt `generated` wskazuje ścieżki wyjściowe TeX/HTML/CSS. Pole `template`
|
||
wybiera layout.
|
||
|
||
Opcjonalny obiekt `title_block` włącza tabliczkę zasobu o skonfigurowanej
|
||
wysokości 2,6 lub 3 cm na każdej stronie, także pierwszej, bibliografii,
|
||
słownika i stronach kontynuacji. Tabliczka zastępuje dużą tabelę metadanych
|
||
strony tytułowej.
|
||
Zawiera kategorię, tytuł, metadane karty, numer strony oraz widoczny,
|
||
kanoniczny URL. Ten sam URL jest kodowany lokalnie w QR: jako SVG w HTML i
|
||
przez pakiet `qrcode` w TeX. Opcjonalny `repository_url` dodaje drugi QR do
|
||
repozytorium. W layoutach klasycznym HTML i PDF komórki QR mają po 24 mm,
|
||
a kody po 22 mm: Gitea znajduje się po lewej, a wyrenderowany zasób po prawej.
|
||
Ramka ma 167 mm i biegnie między marginesami bocznymi po 21,5 mm. W HTML widok ekranowy ma rozmiar A4 (210 × 297 mm) i
|
||
nagłówek na każdej logicznej karcie, a wydruk używa `@page { size: A4; }` oraz
|
||
pól marginesu, dlatego nagłówek powtarza się również po automatycznym podziale
|
||
długiej sekcji.
|
||
|
||
Pole `height_cm` przyjmuje `2.6` (kompaktowy nagłówek z QR 22 mm i równym
|
||
światłem) albo `3`; pola `repeat_on_every_page: true` i
|
||
`replace_front_matter: true` dokumentują ten kontrakt. `show_qr: true` wymaga
|
||
kanonicznego adresu HTTP(S) w `url` albo pary `url_host_uuid`/`doc_uuid`, z
|
||
której powstaje `https://<url_host_uuid>/<doc_uuid>`.
|
||
`show_repository_qr: true` wymaga `repository_url`. Adres podglądu `localhost`
|
||
nie powinien być publikowany na karcie.
|
||
|
||
### Efekty i kryteria
|
||
|
||
- `educational_requirements` — wymagania `WE`;
|
||
- `learning_effects` — efekty `EN` lub `EK`;
|
||
- `assessment_criteria` — mierzalne kryteria `KW`;
|
||
- `educational_requirements.*.learning_tree` — połączenia renderowane na
|
||
marginesach.
|
||
|
||
Każdy wpis `learning_tree.ogolne[]` lub `learning_tree.zawodowe[]` ma stabilne
|
||
`tree_id`, odwołanie `effect_ref`, etykietę `display` oraz co najmniej jedno
|
||
powiązane `KW`.
|
||
|
||
### Sekcje i kroki
|
||
|
||
Pole `sections[]` porządkuje treść. Kroki `sections[].steps[]` mają:
|
||
|
||
- `id` i `title`;
|
||
- `tree_refs` wskazujące drzewka z marginesów;
|
||
- opcjonalne odwołania do wymagań, efektów, kryteriów, równań i figur.
|
||
|
||
### Referencje zewnętrzne bez kopiowania treści
|
||
|
||
Karta może ładować kanoniczne rejestry współdzielonych strategii, kart, treści
|
||
i wzorów. Lokalny plik JSON służy do walidacji oraz deterministycznego buildu:
|
||
|
||
```json
|
||
{
|
||
"reference_registries": [
|
||
{
|
||
"uuid": "03403a8a-e20d-5b17-9004-26d9fe6c3003",
|
||
"source": "../../../tools/debugging-strategies/json/reference_registry.json"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Krok przechowuje tylko rodzaj, UUID rejestru i UUID wpisu:
|
||
|
||
```json
|
||
{
|
||
"references": [
|
||
{
|
||
"kind": "strategy",
|
||
"registry_uuid": "03403a8a-e20d-5b17-9004-26d9fe6c3003",
|
||
"uuid": "1ecfc474-4fbd-5a56-8ef1-80ae557761d0"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Generator pobiera z rejestru etykietę, tytuł, ścieżkę i publiczny adres.
|
||
Strategię pokazuje jako kod `Mxx`, kartę jako jej nazwę, a treść lub wzór jako
|
||
kanoniczną etykietę. W TeX/PDF i HTML etykieta jest hiperłączem. Nazw ani URL-i
|
||
nie kopiujemy do `card_source.json`; brak rejestru, UUID albo lokalnego pliku
|
||
przerywa generowanie.
|
||
|
||
Layouty 5a/5b obsługują również:
|
||
|
||
- `model_block.steps` — kroki modelowania;
|
||
- `code_block.blocks[].web_steps` — interaktywne kroki HTML;
|
||
- `hardware_procedure[]` — tabela `step/action/condition` w TeX i HTML.
|
||
|
||
`code_block.blocks[]` jest rzeczywistym podziałem na bloki: każdy wpis jest
|
||
renderowany jako osobna, opisana ramka w sekcji implementacyjnej, a jego
|
||
`web_steps` zasila niezależną checklistę HTML. Kolejność głównych bloków
|
||
strony jest opisana przez `block_map` wybranego szablonu.
|
||
|
||
### Zrzuty ekranu i inne assety sekcji
|
||
|
||
Zrzutów nie wpisujemy jako ręcznego `\\includegraphics` w wygenerowanym TeX.
|
||
Sekcja może deklarować listę `assets`, a generator umieszcza każdy element w
|
||
TeX/PDF i HTML, kopiuje plik do `figures/` strony oraz dodaje link do pełnego
|
||
rozmiaru:
|
||
|
||
```json
|
||
{
|
||
"title": "Pomiar w debuggerze",
|
||
"content_tex": "Zatrzymaj program przed pierwszą alokacją.",
|
||
"assets": [
|
||
{
|
||
"path": "assets/task04-first-allocation-annotated.png",
|
||
"caption": "Task04 przed pierwszym przydziałem pamięci.",
|
||
"label": "fig:task04-first-allocation",
|
||
"alt": "Termdebug: kod C, listing, rejestry i allocbuf",
|
||
"kind": "screenshot",
|
||
"width": 1.0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
- `path` jest liczony względem katalogu `doc/` karty; standardem jest
|
||
`doc/assets/`;
|
||
- obsługiwane są PNG, JPG/JPEG i PDF;
|
||
- `width` jest ułamkiem szerokości kolumny od `0.1` do `1.0`;
|
||
- `label` jest stabilnym identyfikatorem używanym przez `figure_refs`;
|
||
- `full_size_link` domyślnie włącza otwieranie zrzutu HTML w pełnym rozmiarze.
|
||
|
||
Jeśli każda figura ma odpowiadać osobnej stronie wydruku, sekcja deklaruje
|
||
`"asset_page_mode": "one-per-page"`. Generator wtedy wstawia jawne podziały
|
||
stron w TeX i buduje osobne płótna A4 w React/HTML. Pierwsza strona zachowuje
|
||
nagłówek sekcji, a kolejne są stronami kontynuacji z powtórzoną tabliczką
|
||
zasobu. Widok ekranowy rozdziela płótna odstępem `5cm`; reguła nie wpływa na
|
||
wydruk.
|
||
|
||
Końcowy słownik jest domyślnie obecny w React/HTML dla zgodności. Karta, która
|
||
ma zawierać wyłącznie jawnie wymienione strony, ustawia na poziomie głównym
|
||
`"render_dictionary": false`.
|
||
|
||
### Zadania
|
||
|
||
`tasks` jest słownikiem zadań, a `tasks_order` określa ich kolejność. Każde
|
||
zadanie posiada polecenie `prompt_tex`, kryterium zaliczenia i odwołania do
|
||
modelu edukacyjnego.
|
||
|
||
Rozbudowane zadanie przechowuje przebieg dydaktyczny w uporządkowanym
|
||
`tasks.<id>.flow[]`:
|
||
|
||
- `kind: "block"` grupuje jedną część objaśnienia lub demonstracji;
|
||
- opcjonalne `block.steps[]` zachowują kolejność czynności wewnątrz bloku;
|
||
- `kind: "exercise"` jest samodzielną pracą ucznia należącą bezpośrednio do
|
||
zadania i podaje `prompt_tex`, `evidence_tex` oraz `criterion`;
|
||
- `exercise.based_on[]` może wskazać wcześniejsze bloki lub ich kroki.
|
||
|
||
Bloki i ćwiczenia są rodzeństwem w jednym `flow`, dzięki czemu renderer nie
|
||
gubi kolejności nauczania. `steps` nie może występować bezpośrednio w obiekcie
|
||
zadania. Dawne `prompt_tex` i `criterion` pozostają wymagane dla zgodności ze
|
||
starszymi konsumentami; gdy istnieje `flow`, renderer używa jego treści.
|
||
|
||
## Zalecany README karty
|
||
|
||
README konkretnej karty powinien zawierać:
|
||
|
||
1. nazwę, numer i miejsce w serii;
|
||
2. cel oraz rezultat obserwowalny;
|
||
3. mapowanie do źródeł i efektów nauczania;
|
||
4. listę kroków/zadań;
|
||
5. polecenia generowania i testowania;
|
||
6. warunek `PASS`;
|
||
7. informację, które pliki są źródłowe, a które generowane.
|
||
|
||
Gotowy przykład znajduje się w `examples/card/README.md`.
|
||
|
||
## Generowanie
|
||
|
||
Z katalogu repozytorium `card-layouts`:
|
||
|
||
```bash
|
||
python3 tools/render_card.py /sciezka/do/mojej-karty
|
||
```
|
||
|
||
Generator najpierw sprawdza spójność identyfikatorów WE/EN/EK/KW, kroków,
|
||
zadań, rejestrów UUID i odwołań, a dopiero potem zapisuje oba formaty.
|