Add an article about typst

content/software/typst.md

@@ -0,0 +1,176 @@
+---
+Title: Typesetting with Typst 
+Date: 2024-10-19 18:00
+Lang: en
+Author: Fabrice
+Category: software
+Tags: vim, neovim. typst
+Slug: typst-intro
+table-of-contents: true
+Summary: Simple typesetting with Typst.
+Header_Cover: ../images/covers/printing-press.jpg
+---
+
+For about ten years now, I’ve been using _LaTeX_ to typeset any document which
+aims to be printed. The main reason is that I’m quite familiar with the syntax
+to adjust the page setting to what I imagine. Other solutions exist to ease this
+workflow, such as [Pandoc](https://pandoc.org/) to convert easier to write syntax to
+other formats. However, this solution was not palatable to me as the universal
+aspect of Pandoc, makes it a pain to specify pagination properties. And, to
+produce a PDF in the end, Pandoc calls _LaTeX_, and for the sake of simplicity I
+prefer to directly write in _LaTeX_ (see the conclusion for clarification).
+
+However, for some kind of documents that I don’t write very often, such as
+letters, it’s sometimes a pain to find the syntax of the [LaTeX class for
+letters](https://texlive.mycozy.space/macros/latex/contrib/lettre/lettre.pdf)<sup>(fr)</sup>
+I use. Recently, I had to write small documents (approx 3 pages), with a
+bibliography, and that just needed to have a nice and neat presentation. Before
+going farther, I decided to give a try to [typst](https://typst.app/). It is an
+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
+[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
+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
+opportunities.
+
+# 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
+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.
+
+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
+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"`
+at the outset of the file.
+
+```typst
+#import "lettre.typ": *
+#show link: strong
+
+#show: doc => lettre(
+  de: [
+    Sender\
+    Address
+  ],
+  pour: [
+    Recipient\
+    Address
+  ],
+  objet: "subject of the letter", // optional
+  date: "date of sending", // optional
+  lieu: "location",
+  introduction: "opening",
+  cloture: "closing",
+  signature: "signature",
+  post: [
+    post-letter (e.g., post-scriptum)
+  ],
+  doc
+)
+```
+
+This will generate the template with the elements where they should be, in a
+very simple fashion. Now, we just have to write the content of the letter and
+have a `pdf` file pretty easily with `typst compile` without all the files that
+_LaTeX_ generates for us. As a bonus, it also set some PDFs metadata from the
+input variables.
+
+# Bibliography
+
+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/)
+
+For that you simply have to call the bibliography function where you want it to be generated:
+
+```typst
+#bibliography("bibliography.bib", title: "References", style: "springer-basic")
+```
+
+And cite the references you want with the `@bibkey` syntax (note that it’s the
+same syntax for cross-referencing) or the `#cite` function. Note that if you
+have a `+` in your bibliography key, the label won’t be recognized. It is my
+case as my bibkeys are in the _alpha_ style with the initials of the authors +
+year up to 3 names, and a `+` afterward… To be able to cite the reference
+anyway, just do `#cite(label("bib+key"))`.
+
+The full list of natively available style is given in the [Typst
+documentation](https://typst.app/docs/reference/model/bibliography/#parameters-style),
+however you can define your own in the [Citation Style
+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 
+
+# Tooling
+
+Unlike my [blogpost about using nvim for LaTeX]({filename}./nvim-latex.md),
+it’s pretty much easier here.
+
+I just added the [`typst.vim`](https://github.com/kaarmu/typst.vim) plugin to
+_neovim_, added a binding for the `:TypstWatch` command and that’s basically
+all. It is possible to set the `g:typst_pdf_viewer` (`vim.g.typst_pdf_viewer` in
+Lua) global variable as well if you want to have a different default PDF viewer
+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.
+
+Hopefully, the tooling will be better with time.
+
+# Conclusion
+
+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 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:
+
+> Added
+> [`par.spacing`](https://typst.app/docs/reference/model/par/#parameters-spacing
+> "Typst Documentation: paragraph spacing") property for configuring paragraph
+> 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…).
+
+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
+didn’t try them yet, so I can’t provide feedbacks about them. Note that Typst is
+part of the PDF generators, as well as other nice typesetting projects such as
+[pagedjs](https://pagedjs.org/) that aims at paginating HTML sources to have
+great web page and print-ready PDFs. However, the argument about avoiding
+intermediate steps if possible still holds (moreover when the syntax of Typst is
+already clean enough).