146 lines
4.9 KiB
Markdown
146 lines
4.9 KiB
Markdown
# tultemplate2
|
|
|
|
Easy Typst template for TUL documents. Begin by compiling `documentation.typ` and reading it.
|
|
|
|
## 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)
|
|
|
|
## Contributing
|
|
|
|
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.
|
|
|
|
If you wish to help with the development (or just want to ask us something), feel free to reach out
|
|
to the maintainer:
|
|
|
|
Ondřej Mekina <ondrej@mekina.cz>
|
|
|
|
## The goals of this template
|
|
|
|
We dream of a simple way for students to make documents. Of a workflow revolving not around
|
|
citations, fonts, paragraphs and other formal nonsense, 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/).
|
|
|
|
Our project 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, translation 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 (or run using make):
|
|
> `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)
|
|
|
|
or
|
|
|
|
- Nix (use `nix develop` to enter the development shell and you can skip dependency installation)
|
|
|
|
### 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.
|
|
|
|
Now, if you don't want to use the generator, drop into the repo directory and run:
|
|
|
|
```sh
|
|
make pack
|
|
```
|
|
|
|
This will generate outputs at `target/pack/tultemplate2` and `target/pack/tultemplate2.zip`.
|
|
We recommend copying the files (either from the zip or the directory) somewhere else and (in there)
|
|
running:
|
|
|
|
```sh
|
|
make view_documentation
|
|
```
|
|
|
|
After you have created your own `filename.typ` you can run:
|
|
|
|
```sh
|
|
make view_filename
|
|
```
|
|
|
|
or
|
|
|
|
```sh
|
|
make watch_filename
|
|
```
|
|
|
|
The `Makefile` provided in the packed build is just an example... feel free to adjust it according
|
|
to your needs.
|
|
|
|
The packed builds also provide `documentation.pdf` such that you can jump into it straight away
|
|
or keep it around during the writing of your own thesis.
|
|
|
|
### 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`. In the files with names like `bp_en.typ` you can find the example
|
|
header for each thesis (and after that some spelling substitutions for the build system).
|
|
And in `theses/content_cs.typ` and `theses/content_en.typ` is the content for the theses.
|
|
|
|
Using:
|
|
|
|
```sh
|
|
make thesis_bp_cs
|
|
```
|
|
|
|
Will make and view an example bachelor's thesis in czech.
|
|
|
|
We also have (at the moment):
|
|
- `bp_en`
|
|
- `dp_cs`
|
|
- `dp_en`
|
|
- `prj_cs`
|
|
- `prj_en`
|