diff --git a/content/images/covers/printing-press.jpg b/content/images/covers/printing-press.jpg new file mode 100644 index 0000000..2f4ac1b Binary files /dev/null and b/content/images/covers/printing-press.jpg differ diff --git a/content/software/typst.md b/content/software/typst.md new file mode 100644 index 0000000..e02ee26 --- /dev/null +++ b/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)(fr) +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).