# PB029: Zadání zápočtových dokumentů

Zápočtové úlohy jsou dvě: první je TeXem vysázený text odevzdávaný na papíře, druhou úlohou je návrh a použití vlastního jednoduchého XML jazyka.

Pozdní odevzdání zápočtových dokumentů z jiného důvodu než omluveného (doložená nemoc apod.) je možné do prvního vypsaného zkouškového termínu, ale bude bodově penalizováno 5 body za každý zápočtový dokument. O opravu pozdě odevzdaných dokumentů požádejte vyučující e-mailem.

Pokud nejste s hodnocením svých zápočtových dokumentů spokojeni, můžete je přepracovat a požádat o opětovné ohodnocení na svém opravném termínu. Přepracované dokumenty budou penalizovány 5 body.

Závěrečné úlohy student vypracovává samostatně.

## První zápočtový dokument – TeXem sázený dokument

1. Dokument bude v češtině nebo slovenštině.
2. Dokument bude napsán pravopisně správně.
3. Dokument bude mít dvě obsahově stejné podoby – elektronickou a papírovou:

- Elektronická verze bude klikací (hypertextový rejstřík apod.).
- Před tiskem papírové verze použijte šablonu `odplist` (dostupnou také na službě Overleaf) a dokument vytiskněte jednostranně na papír formátu A4, abychom ho mohli automaticky naskenovat.

4. Na výběr máte ze dvou typů dokumentů: váš životopis, nebo referát o TeXu.

1. Životopis

1. Váš dokument bude sestávat ze dvou částí: První část bude obsahově váš strukturovaný životopis, druhý bude průvodní nebo doporučující dopis k životopisu, anebo jiný obsahově kompaktní text (esej, seminární práce, kapitola závěrečné práce, atd.). Tento text má mít jasně odlišená a vysázená metadata (autor, nadpis), číslování stránek. Měl by být napsán odborným stylem. Rozsahově ho však upravte tak, aby se vešel do zadaného rozsahu.
2. Rozsah vašeho dokumentu bude právě pět stran.
3. Dokument bude obsahovat bibliografii zpracovanou programem BibTeX nebo BibLaTeX. Bibliografie se nebude nacházet na samostatné straně.
4. Dokument bude obsahovat rejstřík vytvořený programem `xindy`/`texindy`. Rejstřík se rovněž nebude nacházet na samostatné straně (jinými slovy tedy není možné zaplnit dvě a více stran pouze rejstříkem a bibliografií).
5. Dokument bude mít vloženou bitmapovou grafiku (například, ale ne nutně, vaši fotku v životopisu).
6. Dokument bude obsahovat vektorovou grafiku: obrázky vytvořené v LaTeXu nebo pomocí WYSIWYG nástroje Inkscape.

2. Referát

1. Ve svém dokumentu poreferujte o zajímavé TeXové technologii. Inspirovat se můžete (ale nemusíte):
   - články v časopise TUGboat; zaměřte se na články pro nováčky označené heslem „Introductory“
   - programem konference TUG 2023 nebo jiných TeXových setkání, ze kterých jsou často dostupné i videozáznamy
   - TeXovými balíčky dostupnými ve webovém katalogu CTAN
   Vybrané téma konzultujte s vyučujícím.
2. Očekává se, že popisovanou TeXovou technologii použijete pro řešení vlastního problému, nebo ji zasadíte do širšího kontextu. Pokud vycházíte z příspěvku na konferenci nebo jiného zdrojového dokumentu, snažte se obohatit čtenáře nad rámec toho, co by se dozvěděl ze zdrojového dokumentu, ne ho otrocky převyprávět.
3. Rozsah vašeho dokumentu budou nejméně čtyři strany.
4. Dokument bude napsán odborným stylem a bude členěný na abstrakt, úvod, stať a závěr. Pro lepší představu si můžete prohlédnout povedené dokumenty svých kolegů z minulých let:
   - Sazba hudebních skladeb, Karel Šebela
   - Pohľad TeXového nováčika na prezentáciu „Bricks and Jigsaw Pieces“ z TUGu 2022, Matúš Vančík
5. Pro přípravu dokumentu použijte šablonu `csbulletin` (dostupnou také na službě Overleaf).
6. Dokument bude obsahovat bibliografii zpracovanou programem BibTeX nebo BibLaTeX. Pokud vycházíte z příspěvku na konferenci nebo jiného zdrojového dokumentu, vaše bibliografie bude odkazovat přinejmenším tento zdrojový dokument.
7. Odevzdáním svého dokumentu jej nabízíte k vydání ve Zpravodaji CSTUGu. Kromě výše uvedených požadavků by měl váš dokument splňovat požadavky uvedené v pokynech pro autory.

5. Nejpozději do neděle 12. 11. 2023, 23:59 můžete plné zdroje elektronické verze umožňující přesazbu dokumentu ve formě jediného komprimovaného archivu odevzdat nanečisto a zapojit se do vzájemného hodnocení s ostatními studenty. Odměnou vám bude zpětná vazba k vašemu dokumentu a až 6 bodů.
6. Hotová papírová verze bude odevzdána na papíře, s podpisem tvůrce, nejpozději do pondělí 18. 12. 2023, 12:00. sekretářce kateder (FI MU místnost B407, případně schránka před ní), Dejte si prosím pozor na kvalitu tisku – kontury znaků by měly být jasně viditelné a grafické prvky by neměly být rozpixelované.
7. Plné zdroje elektronické verze umožňující přesazbu dokumentu budou ve formě jediného komprimovaného archivu nejpozději do téhož data v Odevzdávárně předmětu v IS MU.

## Druhý zápočtový dokument – návrh vlastního jazyka XML

Úkolem je navrhnout vlastní jednoduchý XML jazyk pro uchovávání databáze kontaktů (adresář osob).

1. Každá osoba je (ne nutně jednoznačně) identifikována svým jménem.
   - To je značkami logicky rozděleno minimálně na křestní jméno a příjmení.
2. Pro každou osobu je možné evidovat libovolné množství
   - e-mailových adres,
   - telefonních čísel a
   - odkazů na webové stránky.
   Volitelně je pro adresy, čísla a odkazy možné specifikovat typ z předdefinovaného seznamu přípustných voleb, např. `osobní`, `pracovní`, `jiná`.
3. Krom e-mailů, telefonů a odkazů na web umožněte specifikaci jiného typu kontaktu jako dvojice jména služby (libovolný uživatelem zadaný rozumně dlouhý řetěz písmen a číslic, např. `Skype`, `Jabber` apod.) a ID uživatele v dané službě (opět libovolný rozumně dlouhý řetězec s povolenými speciálními znaky jako zavináč [`@`] apod.).
4. Umožněte ke kontaktu přidat libovolný počet poštovních adres strukturovaných na
   - jméno ulice,
   - číslo orientační/popisné,
   - PSČ,
   - město apod.
5. Umožněte přidat libovolný počet poznámek (nestrukturované textové pole s větší povolenou délkou a možností zadávat více řádků textu).

Technicky je úkolem:

1. Navrhnout XML jazyk dle volného textového zadání výše,
2. formalizovat jeho specifikaci vytvořením strojově validovatelné gramatiky v jazyce XML Schema (případně jiném formalizmu typu RELAX NG, Schematron apod.; to ale předem konzultujte s vyučujícím) a
3. připravit XSL stylesheet, který každý platný dokument v tomto jazyce převede na validní XHTML (1.0 či vyšší) nebo HTML (4.01 či vyšší) stránku splňující zásady W4D s vhodnou grafickou reprezentací obsažených dat,
   - tj. řadit seznam dle abecedy (dle příjmení),
   - jména osob zobrazovat v jednotném formátu (např. „Příjmení, Jméno“ apod.),
   - e-mailové adresy a odkazy na webové adresy prezentovat jako „klikatelné“ odkazy,
   - vhodně graficky oddělit jednotlivé záznamy (jméno kontaktu je nadpis a jemu příslušející údaje využívají značkování logicky podřízené) atd.

Technické řešení demonstrujte:

1. Vytvořením sady tří platných databází kontaktů (třech samostatných XML souborů) ve vašem jazyce:
   1. soubor nebude obsahovat žádné kontakty, tj. bude demonstrovat platný dokument, který ale neobsahuje žádné záznamy.
   2. soubor bude obsahovat právě jeden kontakt s využitím všech datových polí a jejich možností, které váš jazyk umožňuje, tj. bude představovat příklad maximální podoby záznamu, kterou je možné vaším jazykem vyjádřit.
   3. soubor bude obsahovat 5 různých záznamů s různým stupněm vyplnění údajů, tj. bude příkladem reálného dokumentu, kde pro různé kontakty bude využita různá sada podporovaných údajů.
2. Připravte také sadu několika nevalidních dokumentů, které budou demonstrovat možné chyby v dokumentech, které jsou odhaleny jejich validací, např.
   - nepovolený formát e-mailové adresy (kde např. úplně chybí znak `@` apod.) či telefonního čísla,
   - chybějící povinné datové pole,
   - výskyt neznámého pole,
   - nepovolený počet výskytů platného pole apod.

Sadu všech souborů (včetně vygenerovaných [X]HTML reprezentací) vhodně pojmenujte (např. `schema.xsd`; `to-html.xsl`; `valid-empty.{xml,html}`, `valid-full-record.{xml,html}`, `valid-real-world-records.{xml,html}`; `invalid-email-format.xml`, ... apod.).

Nejpozději do neděle 3. 12. 2023, 23:59 můžete svůj dokument ve formě jediného komprimovaného archivu odevzdat nanečisto a zapojit se do vzájemného hodnocení s ostatními studenty. Odměnou vám bude zpětná vazba k vašemu dokumentu a až 6 bodů.

Hotový dokument odevzdejte ve formě jediného komprimovaného archivu do Odevzdávárny předmětu v IS MU do pondělí 18. 12. 2023, 12:00.

Zadání obou zápočtových úloh není (a ani nemůže a nechce být) vyčerpávající a není možné jej brát jako seznam povinných bodů, jejichž doslovné splnění vede k plnému počtu bodů a nesplnění některých z nich k přesné bodové srážce „za kus“. Konečné hodnocení bude reflektovat celkovou funkčnost a kvalitu provedení, preciznost formální definice (co všechno a jak přesně kontrolujete), dojem z grafického provedení (X)HTML reprezentace dat apod. Precizní provedení jazyka s menším množstvím možností může být cennější než rozsáhlý jazyk s chabou definicí platných dat.

Nadstandardně pěkné provedení může být snadno ohodnoceno i více než 100 % bodů plánovaných na tento zápočtový dokument. Zapojte vlastní invenci a nápady – co třeba poštovní adresy obohatit o odkazy na zobrazení místa v Google Maps / OpenStreetMap / Mapy.cz apod.? (Stačí řešit vygenerováním odkazu, který text adresy zadá dané službě k vyhledání.) Bonusové body lze rovněž získat za přípravu XSL transformací, které vstupní XML dokument převedou do alternativního formátu, např. LaTeXu.

## Vzájemné hodnocení

Peer assessment neboli vzájemné hodnocení studentů je proces hodnocení, při kterém se studenti hodnotí mezi sebou a učí se tak podávat a přijímat konstruktivní zpětnou vazbu.

Pokud do neděle 12. 11. 2023, 23:59 odevzdáte první zápočtové dokumenty do Odevzdávárny předmětu v IS MU, budete e-mailem od IS MU vyzváni, abyste do neděle 19. 11. 2023, 23:59 ohodnotili první zápočtové dokumenty třech svých kolegů. Detailní instrukce, jak při vzájemném hodnocení postupovat, budou součástí e-mailu od IS MU.

Pokud do neděle 3. 12. 2023, 23:59 odevzdáte druhé zápočtové dokumenty do Odevzdávárny předmětu v IS MU, budete e-mailem od IS MU vyzváni, abyste do neděle 10. 12. 2023, 23:59 ohodnotili druhé zápočtové dokumenty třech svých kolegů. Detailní instrukce, jak při vzájemném hodnocení postupovat, budou součástí e-mailu od IS MU.

Během hodnocení zběžně projděte dokumenty svých kolegů a poskytněte jim konstruktivní zpětnou vazbu. Kontrola jednoho dokumentu by vám neměla zabrat více než půl hodiny.

## Použití systému pro správu verzí

Při přípravě elektronických dokumentů je velmi žádoucí používat systém pro správu verzí, např. Git. Jeho korektní použití bude odměněno až 5 bonusovými body.

Při použití Gitu si vytvořte v GitLabu FI repozitář pojmenovaný ve tvaru `<váš-fi-login>_PB029` (`PB` verzálkami!). Po vytvoření repozitáře přidejte v levé postranní nabídce „Manage“ → „Members“ tlačítkem „Invite members“ uživatele `xnovot32` a `sojka` s přístupovými právy v nabídce „Select a role“ nastavenými na hodnotu „Reporter“ nebo vyšší. Odkazy na příslušný repozitář a další informace potřebné pro kontrolu zdokumentujte v rámci archivů odevzdávaných do Odevzdávárny předmětu v IS MU (ideálně např. pomocí textového souboru `README.md`).

Prémiové body budou přiděleny jen v případě, že od odevzdání zápočtových dokumentů bude až do jejich konečného vyhodnocení dostupný repozitář splňující uvedené požadavky, a pokud tento repozitář byl při vývoji dokumentů skutečně použit (tzn. byly do něj ukládány jednotlivé vývojové verze dokumentů v průběhu jejich přípravy během semestru, ne jen vložena jejich finální verze předtím připravená bez použití systému pro správu verzí).