diff --git a/content/examples/typst-example.pdf b/content/examples/typst-example.pdf new file mode 100644 index 0000000..73ebae9 Binary files /dev/null and b/content/examples/typst-example.pdf differ diff --git a/content/software/typst.md b/content/software/typst.md index 924d6ce..8c3b26f 100644 --- a/content/software/typst.md +++ b/content/software/typst.md @@ -1,6 +1,7 @@ --- Title: Typesetting with Typst Date: 2024-10-19 18:00 +Modified: 2024-10-19 21:00 Lang: en Author: Fabrice Category: software @@ -30,27 +31,85 @@ open-source typesetting engine that is written in [rust](https://rust-lang.org/), that promotes modern features such as _incremental compilation_, and a scripting language that is actually readable by humans. Moreover, the markup language is clean, and as in -[markdown](https://daringfireball.net/projects/markdown/) or -[asciidoc](https://asciidoc.org/), it can be read from the source (without a +[markdown] or [asciidoc], it can be read from the source (without a [concealer](https://alok.github.io/2018/04/26/using-vim-s-conceal-to-make-languages-more-tolerable/)) to have an idea of the typeset text before compiling it. + The project is still in development and some features may break before the first major version is out. However, to quickly generate a document, it can be a good -idea to consider. It is also to note that there is no native output from Typst -to html, but Pandoc can read and write `.typ` files, so it’s an alternative +idea to consider. Also, please note that there is no native output from Typst to +HTML. However, Pandoc can read and write `.typ` files, so it’s an alternative worth considering given that native LaTeX is **not** easy to write for that purpose. In the following, it will be a quick overview of the features that I find nice -in Typst. Please don’t expect a in-depth review, I only used it for a couple of +in Typst. Please don’t expect an in-depth review, I only used it for a couple of opportunities. +# Syntax + +To illustrate Typst, here follows a simple document, with its corresponding [compiled +version]({static}/examples/typst-example.pdf). + +```typst +/* Set some variables for the authors and the title */ +#let title = [How to type in Typst] +#let authors = ("Fabrice Mouhartem", ) + +/* Set some document properties: + * - Numbering of sections (default: none) + * - PDF properties (it does not print anything) */ +#set heading(numbering: "I.") +#set document(title: title, author: authors) + +/* Now we can print the title and the authors */ +#align(center, text(size: 17pt, strong(title))) +#for author in authors { // TODO: would be better in a grid + align(center, text(author)) +} + +/* Table of contents */ +#outline() + +/* To define a section */ += Introduction +/* And to write the content: */ +To _type_ in Typst, you just have to… *type*. + += Conclusion +See, it was #strike[hard] easy. +``` + +Besides the programmatic part at the start, we can see that the syntax is close +to what we may know in other simple markup languages such as [markdown] or +[asciidoc]. However, it is its own and Typst [doesn’t +plan](https://github.com/typst/typst/discussions/2498) to converge toward +another markup language, especially knowing that the markdown syntax is +[ambiguous](https://roopc.net/posts/2014/markdown-cfg/). + +For the preamble of the file, it can be deferred to another file to accentuate +the separation between content and typesetting. We won’t go into details, but it +was mostly there to illustrate some parts of the language, such as variable +declaration (`#let …`) or loops over arrays (`#for … in …`). We also set some +values about the document using either static values (for the numbering) or the +defined variables (authors and title options). + +Let us now check that these options are indeed well set: +```bash +❯ pdfinfo "typst-example.pdf" | head -n 3 +Title: How to type in Typst +Author: Fabrice Mouhartem +Creator: Typst 0.12.0 +``` + +The generated document is a bit bare, but we can easily change it, and as easily +create a template to automate this work for us. + # Example: a letter (the French way) -Now, let us look at what a Typst document looks like. For a simple example, I’ll -take the letter one, for which I wrote a simple template to generate them. The -template is available in [this +For a simple example, I’ll take the letter one, for which I wrote a simple +template to generate them. The template is available in [this repository](https://git.epheme.re/fmouhart/typst-lettre). The main issue I had is that the French way of doing letters revert the order of the addresses of the sender and recipient are… reverted compared to the English style. @@ -58,7 +117,7 @@ sender and recipient are… reverted compared to the English style. Let us dig in what it does by looking at the example file. First thing first, the file is loading the template from `lettre.typ`. This file -defines the typesetting and the paginations properties, and provide a +defines the typesetting and the paginations properties, and provide an initialisation function to define the different headers, which you can look into if you feel curious. If you find it a bit unbearable, you can create a new file `preamble.typ` to hide everything, and include it with `#include "preamble.typ"` @@ -101,7 +160,7 @@ input variables. Another nice feature is that Typst embeds a bibliography engine, that is compatible with the bibtex format. Meaning that I don’t have to change the way I manage my bibliography or directly use [community-managed -bibliography](https://cryptobib.di.ens.fr/) +bibliography](https://cryptobib.di.ens.fr/). For that you simply have to call the bibliography function where you want it to be generated: @@ -123,7 +182,10 @@ Language](https://citationstyles.org/). Meaning that you can pick the best one for your usage in the [CSL repository](https://github.com/citation-style-language/styles). -Note that the bibliography command does not seem to be recognized +To put multiple citations (as in `\cite{ref1, ref2}` in _LaTeX_), you just have +to concatenate them, like `@ref1 @ref2`. If the citation style supports it, it would automatically +merge them under the same bracket (however, it’s not the case for all citation +styles). # Tooling @@ -139,10 +201,11 @@ for your system and for edition. Now, each time I save, the document is incrementally compiled (I think) and updated in my PDF viewer. -I tried using typst language servers as well, but they don’t seem mature yet and -in the end the `typst.vim` plugin suffices to my needs without being too nosy. +I tried using typst language servers as well, but they don’t seem mature enough +yet. In the end, the `typst.vim` plugin suffices to my needs without being too +nosy. -Hopefully, the tooling will be better with time. +Hopefully, the tooling will get better with time. # Conclusion @@ -150,8 +213,9 @@ For simple document typesetting, even with features such as bibliography, cross-referencing, and table of contents, Typst seems to be a good choice. However, for long-term support documents, such as documentation, I would wait to see it being more stable. Even while writing this blog post, the _lettre_ -template I made was done in Typst 0.11, and preparing it in a repository raises -some warnings about breaking changes from 0.12: +template I made was done in Typst 0.11, and preparing it in a repository raised +some warnings about breaking changes from 0.12 that has been published 3 days +ago (at the time of writing): > Added > [`par.spacing`](https://typst.app/docs/reference/model/par/#parameters-spacing @@ -159,12 +223,13 @@ some warnings about breaking changes from 0.12: > spacing. This should now be used instead of `show par: set block(spacing: ..)` > **(Breaking change)** -Which let me also say that one other advantage from Typst is… the error messages -that are way much cleaner than the ones from _LaTeX_. Leading to easier -debugging as well. I, however, can’t say for sure as I didn’t typeset big documents using -Typst yet (which is unlikely to happen given my stance so far, but who knows…). +Which also leads me to say that one other advantage of Typst is… the readability of +error messages. They are way much cleaner than the ones from _LaTeX_. Leading to +easier debugging as well. I, however, can’t say for sure as I didn’t typeset big +documents using Typst yet (which is unlikely to happen given my stance so far, +but who knows…). -Finally, to complete the note about compiling in latex from Pandoc in the +Finally, to complete the note about compiling in _LaTeX_ from Pandoc in the introduction of this blogpost… I’m apparently not up to date. For the sake of transparency, it is possible to use different PDF engines with Pandoc according to the [documentation](https://pandoc.org/MANUAL.html#option--pdf-engine). I @@ -182,3 +247,7 @@ already clean enough). - [Typst for _LaTeX_ users](https://typst.app/docs/guides/guide-for-latex-users/ "Typst documentation: guide for LaTeX users"): a comprehensive guide for typst for _LaTeX_ users. + +[markdown]: https://daringfireball.net/projects/markdown/ +[asciidoc]: https://asciidoc.org/ +