expand documentation in README

2025-10-21 20:36:48 +02:00
parent 7193b648f2
commit 13465c8d78
2 changed files with 85 additions and 95 deletions
--- a/README.md
+++ b/README.md
@@ -2,24 +2,102 @@

 Easy Typst template for TUL documents. Begin by compiling `example.typ` and reading it.

-## How to compile
+## Recommended usage

 It is recommended to use either:
 - The on-line Typst editor (https://typst.app/play/) - use some zip build from releases
  (https://git.zumepro.cz/tul/tultemplate2/releases).
 - The `typst` CLI tool (available in Arch repos and Snap)

-On Linux, with the `typst` command available, you can just run:
+## Contributing

-```sh
-make
-```
+The development is done on our own Gitea instance
+(over at https://git.zumepro.cz/tul/tultemplate2). We have a GitHub mirror, but don't actively
+monitor it. We're sorry for this inconvenience, Gitea just gives us so many useful features.

-That will compile the example document and view it.
+If you wish to help with the development (or just want to ask us something), feel free to reach out
+to the maintainer:

-## Repo structure note
+Ondřej Mekina <ondrej@mekina.cz>
+
+## Our goals and dreams
+
+We dream of a simple way for students to make documents. Of a workflow revolving not around
+citations, fonts, paragraphs and other formal bs, but around the actual content of the document.
+
+We aim to provide a robust (but simple) framework to build official documents at TUL.
+
+We want to check as much as we can on behalf of the user and stop the compilation of the document if
+any formal rules could be broken. Our opinion is that the average user should not even have the
+opportunity to break formal rules. And if they want to - they will have to dig a bit (or set
+additional parameters in the template).
+
+When we started developing this template, we cosmically underestimated the amount of effort we'd
+have to put into this project. Since then we consulted teachers, executives, typographers and
+previous TUL template developers. But even now we feel like we're far from perfect. So if you
+think you could help us or give us any advice to make this project thrive, please **reach out**.
+
+This project was inspired by Pavel Satrapa's TUL LaTeX bundle
+(https://www.nti.tul.cz/~satrapa/vyuka/latex-tul/). It aims to be a modern and more robust
+alternative.
+
+By rewriting in Typst, we have access to scripting. So we can programmatically pull up some
+information, translationa and abort the compilation when necessary.
+
+Oh and also... it's hella fast.
+
+## How to build in CLI

 > [!IMPORTANT]
 > This repo uses git lfs to pull fonts. Please set it up (or download a packed build from releases).
 > When running in CLI - you'll want to include the embedded fonts:
 > `typst compile --font-path template/fonts example.typ`
+
+### Dependencies
+
+- Standard `bash` for Makefile commands (`mkdir`, `rm`, `xdg-open`, `echo`, `cd`, `ln`, `awk`, `sed`, `cat`)
+- `jq` for processing JSON files (is pretty standard on most GNU/Linux distros)
+- `GNU Make` for Makefiles
+- Typst command (`typst` on Snap / `typst` package on Arch-based repos - AUR not required)
+- `zip` if you want to make packed builds (perhaps for the on-line editor)
+
+### Building your own thesis
+
+> [!TIP]
+> We **strongly** recommend to use the template package generator available at
+> https://tulsablona.zumepro.cz/
+
+The generator will help you generate the necessary headers (so you don't have to go error-by-error -
+sadly, Typst does not yet support emitting multiple errors or warnings at once).
+
+It will also give you some tips (like to upload the assignment PDF from STAG) on how to structure
+the thesis. And at the end, it will generate a whole example document for you.
+
+### Building documentation
+
+The documentation PDF explains different concepts in Typst and in this template.
+It's source code can be found in `documentation.typ`.
+
+You can build (and view) it by running:
+
+```sh
+make
+```
+
+This will compile it once and open it using `xdg-open`.
+
+### Building thesis examples
+
+Thesis examples are in `theses`. They also have assignments pulled from an external file.
+
+Using:
+
+```sh
+make bp_cs.pdf
+```
+
+Will generate an example bachelor's thesis in czech.
+
+We also have:
+- `bp_en.pdf` (partially translate - if you wish to help translating, we'll gladly welcome it)
+- `dp_cs.pdf`
--- a/documentation.typ
+++ b/documentation.typ
@@ -303,94 +303,6 @@ co nejvíce využívala základních funkcí Typstu -- například:

 V této kapitole se naučíme vymaxovat využití této šablony za pomocí dalších funkcí a syntaxe.

-#pagebreak(weak: true)
-== Parametry této šablony
-
-Šablonu standardně použijete takto:
-```typst
-#show: tultemplate2.with(
-  <název_parametru>: <hodnota_parametru>,
-  <nazev_dalšího_parametru>: "<hodnota_dalšího_parametru>",
-  ...
-)
-```
-
-Funkce `tultemplate2` přijímá následující parametry.
-Zvýrazněné hodnoty jsou základní -- pokud vynecháte parametr, pak bude použita tato hodnota.
-
-#line()
- `style` (vizuální styl dokumentu)
-  - *`"classic"`* - Klasický vizuální styl. Tento styl je neblíže klasické formální
-    podobě dokumentů. _(doporučeno pro nováčky této šablony)_
-#line()
- `faculty` (zkratka fakulty)
-  - *`"tul"`* - barvy a logomarky univerzity
-  - `"fs"` - fakulta strojní
-  - `"ft"` - fakulta textilní
-  - `"fp"` - fakulta přírodovědně-humanitní a pedagogická
-  - `"ef"` - ekonomická fakulta
-  - `"fua"` - fakulta umění a architektury
-  - `"fm"` - fakulta mechatroniky, informatiky a mezioborových studií
-  - `"fzs"` - fakulta zdravotnických studií
-  - `"cxi"` - ústav pro nanomateriály, pokročilé technologie a inovace
-#line()
- `lang` (základní jazyk dokumentu)
-  - *`"cs"`* - čeština
-  - `"en"`
-#line()
- `document` (typ dokumentu)
-  - *`"other"`* - nespecifikovaný (neformální) typ dokumentu
-  - `bp` - Bakalářská práce
-  - `dp` - Diplomová práce
-#line()
- `title` (nadpis dokumentu)
-  - Ve formátu `(<zkratka_jazyka>: "<nadpis>")`, například `(cs: "Můj nadpis")`
-  - Pro většinu dokumentů (kromě `other`) jsou vyžadovány verze _cs_ a _en_ (kvůli abstraktu).
-#line()
- `author` (autor/autoři dokumentu)
-  - Příklad: `"Pavel Novák"` nebo `"Petra Velká, Jindřich Peterka"`
-#line()
- `author_pronouns` (jazykový rod autora - není potřeba pro angličtinu, která má základní hodnotu)
-  - Pro vybraný jazyk _cs_:
-    - `"masculine"` - Mužský rod
-    - `"feminine"` - Ženský rod
-    - `"we"` - Množné číslo
-  - Pro vybraný jazyk _en_:
-    - *`"me"`* - První osoba jednotného čísla
-    - `"we"` - První osoba množného čísla
-#line()
- `supervisor` (vedoucí práce) <arg_supervisor>
-  - V podobě textového řetězce, příklad: `"prof. Jindřich Jindřich"`
-  - Ve formátu `(name: "<jméno>", institute: "<institut>")` (toto lze využít například při DP)
-#line()
- `consultant` (konzultant práce)
-  - Stejně jako u #link(<arg_supervisor>, [`supervisor`])
-#line()
- `programme` (studijní program) <arg_programme>
-  - Ve formátu `(<zkratka_jazyka>: "<název_programu>")`
-  - Je vyžadován jazyk, který je vybrán pro celou šablonu -- tohle je pojistka, aby uživatel šablony
-    nevynechal vybraný jazyk
-#line()
- `specialization` (specializace)
-  - Stejně jako #link(<arg_programme>, [`programme`])
-#line()
- `abstract` (abstrakt)
-  - Ve formátu `(<zkratka_jazyka>: [<abstrakt>])`, například `(cs: [Můj *krásný* abstrakt.])`
-  - Dokumenty vyžadují _cs_ i _en_ abstrakt (kromě typu dokumentu `other`).
-#line()
- `keywords` (klíčová slova zobrazovaná pod abstraktem)
-  - Ve formátu `(<zkratka_jazyka>: ("slovo1", "slovo2", ...))`
-#line()
- `assignment` (PDF soubor se zadáním)
-  - Ve formě cesty k souboru, například: `"zadani.pdf"`. Pokud je tento argument vynechán, bude
-    vložena hláška "vložte zadání" na příslušné místo v dokumentu -- tu stranu můžete pak nahradit
-    originálem zadání.
-#line()
- `citations` (BibTex soubor s citacemi)
-  - Ve formě cesty k souboru, například: `"citace.bib"`. Pokud není specifikován, bude použit
-    výchozí (`"citations.bib"`).
-
-#pagebreak(weak: true)
 == Zkratky

 LaTeX TUL šablona má k začátku dokumentu seznam zkratek. Proto jsme ho přidali i do této šablony.