add readme

.gitignore

@@ -1 +1,2 @@
 /*.pdf
+/pack

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Ondřej Mekina, Matěj Žucha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -5,6 +5,33 @@ view_example: example.pdf
 .PHONY: example
 example: example.pdf
 
+TO_PACK := $(shell find template -type f) template/LICENSE
+PACK_TARGETS := $(TO_PACK:%=pack/tultemplate2/%) pack/tultemplate2/example.typ
+
+.PHONY: pack
+pack: pack/tultemplate2.zip
+
+.PHONY: clean
+clean:
+	rm -rf pack
+	rm -f example.pdf
+
+pack/tultemplate2.zip: $(PACK_TARGETS)
+	@mkdir -p $(@D)
+	rm -f $@
+	cd pack && zip -r tultemplate2.zip tultemplate2
+
+pack/tultemplate2/example.typ: example.typ
+	ln -f $< $@
+
+pack/tultemplate2/template/LICENSE: LICENSE
+	@mkdir -p $(@D)
+	ln -f $< $@
+
+pack/tultemplate2/template/%: template/%
+	@mkdir -p $(@D)
+	ln -f $< $@
+
 TEMPLATE_SRCS := $(shell find template -type f)
 
 %.pdf: %.typ $(TEMPLATE_SRCS)

README.md

@@ -0,0 +1,17 @@
+# tultemplate2
+
+Easy Typst template for TUL documents. Begin by compiling `example.typ` and reading it.
+
+## How to compile
+
+It is recommended to use either:
+- The on-line Typst editor (https://typst.app/play/) - use some zip build from releases
+- The `typst` CLI tool (available in Arch repos and Snap)
+
+On Linux, with the `typst` command available, you can just run:
+
+```sh
+make
+```
+
+That will compile the example document and view it.

example.typ

@@ -1,7 +1,7 @@
 #import "template/template.typ": *
 
-#show: tultemplate.with(
-  "classic", "fm", "cs",
+#show: tultemplate2.with(
+  "latex", "fm", "cs",
   title: "Návod na použití Typst TUL šablony",
   author: "Ondřej Mekina",
 )
@@ -192,6 +192,26 @@ Tady je praktická ukázka jednoduchého vložení obrázku s popiskem:
   Logo *TUL*
 ])
 
+== Citace
+
+Šablona podporuje správu citací pomocí standardního BibTeX @bibtex souboru, stejně jako
+například LaTeX. Citace ve vhodném formátu stačí přidat do souboru _citations.bib_, poté je možné se
+na ně odkazovat pomocí `@jmeno_citace`, nebo `#cite(<jmeno_citace>)`. Můžu se tak třeba odkázat na
+citaci Typstu #cite(<typst>).
+
+Formát souboru _citations.bib_ je naprosto stejný jako pro LaTeX. Tyto citace lze přímo vložit
+třeba z webu https://www.citace.com ve formátu BibTeX -- Typst tento formát také umí přečíst.
+
+Soubor, ze kterého se načtou citace lze změnit pomocí argumentu šablony:
+
+```typst
+#show: tultemplate2.with(
+  ...
+  citations: "jinysoubor.bib",
+  ...
+)
+```
+
 == Vnitřní odkazy a kotvy
 
 Trochu navážeme na Odkazy (@links).
@@ -217,10 +237,6 @@ Kotvu dáte někam do souboru a můžete na ní odkazovat stejně jako na citace
 @nazev_kotvy
 ```
 
-== Citace
-
-Šablona samozřejmě podporuje správu citací pomocí standardního BibTeX @bibtex souboru, stejně jako ta LaTeXová. Citace ve vhodném formátu stačí přidat do souboru _citacions.bib_, poté je možné se na ně odkazovat pomocí `@jmeno_citace`, nebo `#cite(<jmeno_citace>)`. Můžu se tak třeba odkázat na citaci Typstu #cite(<typst>).
-
 == Pro pokročilé
 
 Typst má spoustu dalších způsobů stylování (a i skriptování). Podívejte se třeba na zdrojový kód
@@ -229,3 +245,66 @@ pro nadpis @chained_subheading.
 Tyto pokročilejší funkce v drtivé většině dokumentů vůbec není potřeba použít. Nicméně pro
 ty, kteří to chtějí vyzkoušet, nebo to opravdu potřebují: podívejte se buď do zdrojového kódu
 této šablony nebo na dokumentaci Typstu https://typst.app/docs/.
+
+= Workflow a jak si zjednoduššit práci
+
+Tyhle věci používat _nemusíte_, aby vám šablona fungovala. Nicméně často jsou poměrně fajn.
+
+== Protypování
+
+=== Profily
+
+Šablona disponuje funkcí `profile`. Funkce na prototypování šablony jsou nastaveny tak, aby
+při zapnutí profilu pro finální verzi buď vrátily čistou verzi dokumentu, nebo vyhodily error.
+
+K dispozici jsou profily:
+- `debug` - Prototypování je povoleno, výstupem bude verze dokumentu s poznámkami
+- `release` - Výstupem bude čistý výsledný dokument
+
+Při generování výstupu je doporučeno hned za volání šablony na začátku souboru přidat:
+
+```typst
+#profile("release")
+```
+
+To vám pojistí, aby ve výstupu nebyly poznámky a todo.
+
+Pokud funkci `profile` nezavoláte, pak šablone použije profil "debug".
+
+=== Todo
+
+Pomocí todo svému budoucímu já můžete připomenout, že je něco potřeba dodělat. Funkce todo obsah
+zvýrazní, a v případě, že je zvolený profil "release", při kompilaci vyhodí error. To vám
+vlastně zabrání použít funkci todo v profilu "release".
+
+Zvýraznění také můžete vypnout (ale pak se vám todo bude hůř hledat - budete muset hledat v kódu).
+
+Zde je ukázkové použití:
+#block([
+```typst
+#todo(
+  "koupit vajíčka",
+  accent: false // vypnout zvýraznění (pokud chcete)
+)
+```
+], breakable: false)
+
+=== Lorem
+
+Typst má funkci, která vám vygeneruje text Lorem Ipsum -- ten může sloužit na otestování délky
+paragrafů, počtu písmen, atd...
+
+```typst
+#lorem(10)
+```
+
+Výše volaná funkce vygeneruje deset slov Lorem Ipsum. Doporučuji `lorem` kombinovat s `todo`.
+
+```typst
+#todo(lorem(10), accent: false)
+```
+
+Takhle si můžete předpřipravit délku odstavců a vyzkoušet si, jestli se rozsahem práce trefíte
+do požadavků. Pak můžete postupně přepisovat/vyplňovat.
+
+Funkce `todo` vám zároveň zabrání v tom, aby se text Lorem Ipsum vyskytl ve výsledném dokumentu.

template/prototyping.typ

@@ -1,6 +1,13 @@
 #let todos = state("todos", "0");
 #let is_prod = state("is_prod", "false");
 
+// Set a build profile.
+//
+// This can be:
+// - debug (debug comments and todos are displayed)
+// - release (document will be ready for release)
+//
+// - profile (str): The target profile
 #let profile(profile) = {
   let profiles = ("debug", "release");
   if profile not in profiles {
@@ -10,7 +17,12 @@
     )
   }
   context {
-    is_prod.update(is_prod => "true");
+    is_prod.update(is_prod => {
+      if eval(is_prod) and profile == "debug" {
+        panic("refusing to unset release profile - this is a safety measure");
+      }
+      if profile == "release" { "true" } else { "false" };
+    });
   }
 }
 
@@ -28,13 +40,19 @@
   }
 }
 
-#let todo(content, do_highlight: true) = {
+// Sets an item that should be done later.
+//
+// This will cause an error when compiling with a release profile.
+//
+// - content (str): What should you do?
+// - accent (bool): Whether to highlight the todo
+#let todo(content, accent: true) = {
   context {
     todos.update(todos => {
       str(eval(todos) + 1)
     });
   }
-  if do_highlight {
+  if accent {
     highlight(text(content, fill: white), fill: red, radius: .25em, extent: .25em);
   } else {
     text(content);

template/template.typ

@@ -1,27 +1,60 @@
+// +---------------+
+// | TULTemplate 2 |
+// +---------------+
+//
+// Unofficial TUL template for all kinds of documents.
+//
+// Git: https://git.zumepro.cz/tul/tultemplate2
+
 #import "prototyping.typ": todo, profile
 
-#let tultemplate(
-  template_id,
-  faculty_abbreviation,
-  language,
-  document_type: none,
-  title: none, author: none, supervisor: none, study_programme: none,
+// TUL Template 2
+//
+// Use this at the beginning of a Typst file:
+// ```typst
+// #import "template/template.typ": *
+//
+// #show: tultemplate2.with(
+//   "classic", "fm", "cs", ...
+// )
+// ```
+//
+// - style (str): Visual style to use. This can be "latex".
+// - faculty (str): Factulty abbreviation. One of "fs", "ft", "fp", "ef", "fua", "fm", "fzs", "cxi".
+// - lang (str): Language code. This can be "cs" or "en".
+// - document (str): Type of document. This can be "bp", "dp", "ds".
+// - title (str): The title of the document.
+// - author (str): The name of the document's author.
+// - supervisor (str): The name of the document's supervisor.
+// - programme (str): Study programme.
+// - citations (str): The location of the citation file.
+// - content (content): The content of the document
+//
+//-> none
+#let tultemplate2(
+  style,
+  faculty,
+  lang,
+  document: none,
+  title: none, author: none, supervisor: none, programme: none,
+  citations: "citations.bib",
   content,
 ) = {
   import "template_classic.typ": template_classic
   import "utils.typ": assert_in_dict
   let templates = (
-    classic: template_classic,
+    latex: template_classic,
   );
-  assert_in_dict(template_id, templates, "template name");
+  assert_in_dict(style, templates, "template name");
 
   // global set-up
   import "lang.typ": lang_ids
-  assert_in_dict(language, lang_ids, "language abbreviation");
-  set text(lang: language);
-  templates.at(template_id)(
-    faculty_abbreviation, language, document_type,
-    title, author, supervisor, study_programme,
+  assert_in_dict(lang, lang_ids, "language abbreviation");
+  set text(lang: lang);
+  templates.at(style)(
+    faculty, lang, document,
+    title, author, supervisor, programme,
+    "../" + citations,
     content
   );
 
@@ -29,6 +62,10 @@
   assert_release_ready();
 }
 
+// Make a new abbreviation
+//
+// - abbreviation (str): The abbreviation
+// - text (str): Optionally, the text - the meaning of the abbreviation.
 #let abbr(abbreviation, ..text) = {
   import "abbreviations.typ": abbr
   return abbr(abbreviation, if text.pos().len() == 0 { none } else { text.pos().at(0) });

template/template_classic.typ

@@ -94,6 +94,7 @@
   language,
   document_type,
   title, author, supervisor, study_programme,
+  citation_file,
   content,
 ) = {
   // intro page
@@ -150,5 +151,5 @@
   content
 
   // bibliography
-  bibliography("../citations.bib", style: "./tul_citace.csl")
+  bibliography(citation_file, style: "./tul_citace.csl")
 }