add(typst): add an example

+ proofreading
This commit is contained in:
Fabrice Mouhartem 2024-10-19 21:12:20 +02:00
parent 0eec47dc72
commit 57e445a02d
Signed by: fmouhart
GPG Key ID: 2C5033B228CFE4E7
2 changed files with 90 additions and 21 deletions

Binary file not shown.

View File

@ -1,6 +1,7 @@
--- ---
Title: Typesetting with Typst Title: Typesetting with Typst
Date: 2024-10-19 18:00 Date: 2024-10-19 18:00
Modified: 2024-10-19 21:00
Lang: en Lang: en
Author: Fabrice Author: Fabrice
Category: software 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 [rust](https://rust-lang.org/), that promotes modern features such as
_incremental compilation_, and a scripting language that is actually readable by _incremental compilation_, and a scripting language that is actually readable by
humans. Moreover, the markup language is clean, and as in humans. Moreover, the markup language is clean, and as in
[markdown](https://daringfireball.net/projects/markdown/) or [markdown] or [asciidoc], it can be read from the source (without a
[asciidoc](https://asciidoc.org/), 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/)) [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. 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 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 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 idea to consider. Also, please note that there is no native output from Typst to
to html, but Pandoc can read and write `.typ` files, so its an alternative HTML. However, Pandoc can read and write `.typ` files, so its an alternative
worth considering given that native LaTeX is **not** easy to write for that worth considering given that native LaTeX is **not** easy to write for that
purpose. purpose.
In the following, it will be a quick overview of the features that I find nice In the following, it will be a quick overview of the features that I find nice
in Typst. Please dont expect a in-depth review, I only used it for a couple of in Typst. Please dont expect an in-depth review, I only used it for a couple of
opportunities. 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 [doesnt
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 wont 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) # Example: a letter (the French way)
Now, let us look at what a Typst document looks like. For a simple example, Ill For a simple example, Ill take the letter one, for which I wrote a simple
take the letter one, for which I wrote a simple template to generate them. The template to generate them. The template is available in [this
template is available in [this
repository](https://git.epheme.re/fmouhart/typst-lettre). The main issue I had 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 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. 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. 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 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 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 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"` `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 Another nice feature is that Typst embeds a bibliography engine, that is
compatible with the bibtex format. Meaning that I dont have to change the way I compatible with the bibtex format. Meaning that I dont have to change the way I
manage my bibliography or directly use [community-managed 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: 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 for your usage in the [CSL
repository](https://github.com/citation-style-language/styles). 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, its not the case for all citation
styles).
# Tooling # Tooling
@ -139,10 +201,11 @@ for your system and for edition.
Now, each time I save, the document is incrementally compiled (I think) and Now, each time I save, the document is incrementally compiled (I think) and
updated in my PDF viewer. updated in my PDF viewer.
I tried using typst language servers as well, but they dont seem mature yet and I tried using typst language servers as well, but they dont seem mature enough
in the end the `typst.vim` plugin suffices to my needs without being too nosy. 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 # 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. 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 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_ 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 template I made was done in Typst 0.11, and preparing it in a repository raised
some warnings about breaking changes from 0.12: some warnings about breaking changes from 0.12 that has been published 3 days
ago (at the time of writing):
> Added > Added
> [`par.spacing`](https://typst.app/docs/reference/model/par/#parameters-spacing > [`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: ..)` > spacing. This should now be used instead of `show par: set block(spacing: ..)`
> **(Breaking change)** > **(Breaking change)**
Which let me also say that one other advantage from Typst is… the error messages Which also leads me to say that one other advantage of Typst is… the readability of
that are way much cleaner than the ones from _LaTeX_. Leading to easier error messages. They are way much cleaner than the ones from _LaTeX_. Leading to
debugging as well. I, however, cant say for sure as I didnt typeset big documents using easier debugging as well. I, however, cant say for sure as I didnt typeset big
Typst yet (which is unlikely to happen given my stance so far, but who knows…). 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… Im apparently not up to date. For the sake of introduction of this blogpost… Im apparently not up to date. For the sake of
transparency, it is possible to use different PDF engines with Pandoc according transparency, it is possible to use different PDF engines with Pandoc according
to the [documentation](https://pandoc.org/MANUAL.html#option--pdf-engine). I 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 for _LaTeX_ users](https://typst.app/docs/guides/guide-for-latex-users/
"Typst documentation: guide for LaTeX users"): a comprehensive guide for typst "Typst documentation: guide for LaTeX users"): a comprehensive guide for typst
for _LaTeX_ users. for _LaTeX_ users.
[markdown]: https://daringfireball.net/projects/markdown/
[asciidoc]: https://asciidoc.org/