298 lines
9.6 KiB
Typst
298 lines
9.6 KiB
Typst
#import "template/template.typ": *
|
|
|
|
#show: tultemplate.with(
|
|
"classic", "fm", "cs",
|
|
title: "Návod na použití Typst TUL šablony",
|
|
author: "Ondřej Mekina",
|
|
)
|
|
|
|
= Lehký úvod do Typstu a této šablony
|
|
|
|
Typst je profesionální sázecí nástroj podobný markdownu, LaTeXu/TeXu, groffu, atd.
|
|
|
|
Typst je moderní obdobou starších nástrojů, které postrádají spoustu důležitých funkcí, bez kterých
|
|
se v dnešní době prakticky nedá fungovat. Uživatel často musí importovat nepřeberné množství
|
|
balíčků, které poskytují (podle mě) naprosto základní funkcionalitu - jako například správná podpora
|
|
UTF-8 znaků, formátování prvků na základě jazykového lokálu, apod.
|
|
|
|
Další velkou výhodou Typstu je velmi rychlá kompilace dokumentů. S použitím inkrementální kompilace
|
|
pomocí Typstové funkce `watch` je vše prakticky instantní. On-line Typst aplikace na URL
|
|
https://typst.app/play, kterou bych doporučil používat začátečníkům, se prakticky až vychloubá
|
|
rychlou kompilací -- změny vidíte téměř po každém stisku klávesy.
|
|
|
|
Tyto dva hlavní důvody byly mou motivací pro tvorbu této šablony.
|
|
|
|
== Hlášení chyb a návrhy na funkce
|
|
|
|
Mainteinerem šablony jsem já, Ondřej Mekina, ale jakékoliv návhry na zlepšení, pomoc s vývojem a
|
|
hlášení chyb moc rád uvítám.
|
|
|
|
Pokud budete mít dotaz na fungování (vysvětlivky se snažím přidávat do tohoto ukázkového dokumentu),
|
|
návrh, nebo budete chtít nahlásit chybu, využijte jeden z následujících komunikačních kanálů:
|
|
- Můj e-mail: #link("mailto:ondrej@mekina.cz", "ondrej@mekina.cz")
|
|
- Issues na gitu šablony: https://git.zumepro.cz/tul/tultemplate2
|
|
- E-maily dalších maintainerů: #todo("přidat e-maily")
|
|
|
|
= První krůčky, aneb jak rozchodit šablonu
|
|
|
|
== Editor, CLI, LSP
|
|
|
|
Jaký zvolit editor?
|
|
|
|
=== Pro lidi, kteří svůj život nežijí v příkazové řádce
|
|
|
|
Pro začátečníky doporučuji použít on-line Typst editor https://typst.app/play. Můžete ho vyzkoušet
|
|
i bez účtu.
|
|
|
|
=== Pro Arch uživatele
|
|
|
|
Pro pokročilejší je možné použít i CLI (je v Arch repu a jmenuje se... uhodnete to? `typst`).
|
|
Soubor zkompilujete pomocí:
|
|
```sh
|
|
typst compile file.typ
|
|
```
|
|
#highlight[Pozor! Pro kompilaci s touto šablonou budete chtít ještě fonty:]
|
|
```sh
|
|
typst compile --font-path template/fonts file.typ
|
|
```
|
|
Kde `template` je název složky s touto šablonou -- změňte dle potřeby.
|
|
|
|
Jako LSP doporučuji použít `tinymist` (pro nvim je v masonu), téměř kompletně podporuje funkce
|
|
(umí například `textDocument/definition` nebo `textDocument/signatureHelp`, docela fajn věci).
|
|
|
|
== Absolutní minimum
|
|
|
|
Rozchodit šablonu je poměrně jednoduché. Stačí do projektu vložit složku se šablonou a použít
|
|
import, nezapomeňte nahradit `nazev_slozky` za název složky.
|
|
```typst
|
|
#import "nazev_slozky/template.typ": *
|
|
```
|
|
Takto naimportujete všechny nabízené funkce. To obsahuje hlavní šablonovou funkci `tultemplate`,
|
|
ale i dodatečné funkce pro jednodušší práci se šablonou -- k těm se dostaneme později.
|
|
|
|
Dále je potřeba funkci zavolat jako šablonu, abychom pod ní mohli psát obsah.
|
|
```typst
|
|
#show: tultemplate.with(<vzhled_sablony>, <fakulta>, <jazyk>)
|
|
```
|
|
A to je vše. Absolutní minimum pro rozchození šablony. Nebojte se, pokud neznáte názvy
|
|
vzhledů šablony, zkratku fakulty, nebo zkratku pro jazyk. Šablona vás navede pomocí chybových
|
|
hlášek (nebo se můžete podívat do zdrojového souboru pro toto PDF `example.typ`).
|
|
|
|
== Titulní stránka
|
|
|
|
Nyní pojďme přidat nějaký obsah na titulní stránku. Jednoduše do volání šablony přidáme další
|
|
parametry.
|
|
```typst
|
|
#show: tultemplate.with(..., title: "Můj úžasný dokument", author: "Já")
|
|
```
|
|
Všechny možné parametry by vám měl našeptávat váš editor (nebo LSP) -- poslouchejte takové nápovědy,
|
|
opravdu hodně vám to usnadní práci.
|
|
|
|
= Základy formátování v Typstu
|
|
|
|
// tohle je podnadpis :)
|
|
#heading(
|
|
level: 3,
|
|
range(1, 6).map((v) => range(1, v).map((_) => "pod").join("") + "nadpisy").join(", ") + ", ..."
|
|
)<chained_subheading>
|
|
|
|
Velmi jednoduché. Stačí na začátek řádku dát znak `=` kolikrát chcete.
|
|
```typst
|
|
= Nadpis
|
|
== Podnadpis
|
|
=== Podpodnadpis
|
|
==== už tomu asi rozumíte ...
|
|
|
|
A pak obsah
|
|
```
|
|
|
|
== Zvýrazňování textu
|
|
|
|
Syntaxe je velmi podobná například markdownu. Stačí:
|
|
```typst
|
|
*tučně*
|
|
_kurzívou_
|
|
```
|
|
Další stylování lze dělat přes funkce.
|
|
```typst
|
|
#underscore[podtrženo]
|
|
#strike[přeškrtnuto]
|
|
```
|
|
|
|
== Odkazy<links>
|
|
|
|
Odkazy je možné dělat na URL/URI zdroje, e-maily, telefony, atd...
|
|
Odkázat URL (URI) je možné bez zavolání funkce, odkaz stačí prostě a jednodušše napsat:
|
|
https://git.zumepro.cz/tul/tultemplate2
|
|
|
|
```typst
|
|
https://git.zumepro.cz/tul/tultemplate2
|
|
```
|
|
|
|
Tohle interně volá funkci `link`.
|
|
|
|
Pokud odkazujeme na méně časté věci (jako e-maily), můžeme použít funkci `link` přímo.
|
|
```typst
|
|
#link("mailto:ondrej@mekina.cz")
|
|
```
|
|
|
|
Dalši předpony (URI schémata) můžete najít třeba na Wikipedii
|
|
https://en.wikipedia.org/wiki/List_of_URI_schemes.
|
|
|
|
Už jsme několikrát narazili na funkce, tak to dále neodkládejme a vzhůru na @functions.
|
|
|
|
== Funkce<functions>
|
|
|
|
Funkce se v Typstu volají pomocí znaku `#`.
|
|
Některé funkce neberou žádné parametry.
|
|
```typst
|
|
#linebreak // Zalomí (ukončí) řádek, je možné také udělat jeden prázdný řádek v kódu
|
|
```
|
|
Některé funkce berou parametry ve skriptovací podobě.
|
|
```typst
|
|
#profile("debug") // Zapne ladící profil (todo funkce nehází chyby, o tom více později)
|
|
```
|
|
A některé funkce berou klasický obsah -- v těch je možné psát obsah jako kdyby byl mimo funkci.
|
|
```typst
|
|
#highlight[
|
|
= Nadpis
|
|
|
|
Text. *Tučný text*
|
|
]
|
|
```
|
|
#highlight[
|
|
Sledujte nápovědy editoru. Když napíšete \#, tak vám editor nabídne kupu funkcí.
|
|
V on-line editoru se dá hledat ve vyskakovací nabídce. Vestavěné funkce jsou pojmenovány
|
|
srozumitelně a očekávatelně.
|
|
]
|
|
|
|
== Obrázky
|
|
|
|
Obrázky je možné vkládat samotné i třeba s popiskem.
|
|
|
|
Obrázek se vloží pomocí funkce `image`:
|
|
|
|
Přidání popisku a zároveň zalistování obrázku v indexu (aby se na ně třeba dalo odkazovat) lze
|
|
udělat pomocí funkce `figure`.
|
|
|
|
#block([
|
|
```typst
|
|
#figure(
|
|
image("mujobrazek.jpg"),
|
|
caption: [
|
|
*Krásný* obrázek, který vypadá jako obrázek.
|
|
]
|
|
)
|
|
```
|
|
], breakable: false)
|
|
|
|
Tady je praktická ukázka jednoduchého vložení obrázku s popiskem:
|
|
|
|
#figure(image("template/assets/tul_logo.svg", width: 25%), caption: [
|
|
Logo *TUL*
|
|
])
|
|
|
|
== Vnitřní odkazy a kotvy
|
|
|
|
Trochu navážeme na Odkazy (@links).
|
|
|
|
Můžete dělat i vnitřní odkazy třeba na kapitoly, stránky nebo obrázky s popiskem (zabalené ve
|
|
`figure`).
|
|
|
|
```typst
|
|
= Dobrá kapitola<dobra_kapitola>
|
|
|
|
Podívejme se na Dobrou kapitolu (@dobra_kapitola).
|
|
```
|
|
|
|
Takhle vypadá kotva:
|
|
|
|
```typst
|
|
<nazev_kotvy>
|
|
```
|
|
|
|
Kotvu dáte někam do souboru a můžete na ní odkazovat stejně jako na citace:
|
|
|
|
```typst
|
|
@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
|
|
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",
|
|
do_highlight: 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), do_highlight: 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.
|