add(typst): add an example

+ proofreading

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
+[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/))
 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
+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 it’s an alternative
+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
+For a simple example, I’ll 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
 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
+I tried using typst language servers as well, but they don’t 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
 
@@ -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
+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
 > [`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
+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, can’t say for sure as I didn’t typeset big documents using
+easier debugging as well. I, however, can’t say for sure as I didn’t 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… 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/
+