From 3d183b86731a73da7ad7c1cde5b5ecc0c12b1849 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Mekina?= Date: Wed, 24 Sep 2025 13:37:44 +0200 Subject: [PATCH] add function documentation and citation file changing --- example.typ | 35 +++++++++++++++------- template/prototyping.typ | 17 +++++++++-- template/template.typ | 55 ++++++++++++++++++++++++++--------- template/template_classic.typ | 3 +- 4 files changed, 83 insertions(+), 27 deletions(-) diff --git a/example.typ b/example.typ index 6542a36..6409e44 100644 --- a/example.typ +++ b/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()`. Můžu se tak třeba odkázat na +citaci Typstu #cite(). + +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,13 +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()`. Můžu se tak třeba odkázat na -citaci Typstu #cite(). - == 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 @@ -271,7 +284,7 @@ Zde je ukázkové použití: ```typst #todo( "koupit vajíčka", - do_highlight: false // vypnout zvýraznění (pokud chcete) + accent: false // vypnout zvýraznění (pokud chcete) ) ``` ], breakable: false) @@ -288,7 +301,7 @@ paragrafů, počtu písmen, atd... Výše volaná funkce vygeneruje deset slov Lorem Ipsum. Doporučuji `lorem` kombinovat s `todo`. ```typst -#todo(lorem(10), do_highlight: false) +#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 diff --git a/template/prototyping.typ b/template/prototyping.typ index bb10bcd..54e197e 100644 --- a/template/prototyping.typ +++ b/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 { @@ -33,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); diff --git a/template/template.typ b/template/template.typ index 5af5eb7..ebd56f4 100644 --- a/template/template.typ +++ b/template/template.typ @@ -8,28 +8,53 @@ #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 ); @@ -37,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) }); diff --git a/template/template_classic.typ b/template/template_classic.typ index 6c08e44..47b3a52 100644 --- a/template/template_classic.typ +++ b/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") }