From d67e925a5ef6b31ecdc27cb3ea731f481c483908 Mon Sep 17 00:00:00 2001 From: Youwen Wu Date: Sun, 20 Oct 2024 02:16:20 -0700 Subject: [PATCH] docs: update readme --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/README.md b/README.md index 7fc9e67..94c6588 100644 --- a/README.md +++ b/README.md @@ -6,3 +6,53 @@ where you do it. Please note, all of my work is licensed under [CC-BY-NC-ND 4.0](https://creativecommons.org/licenses/by-nc-nd/4.0/deed.en) (that's the Creative Commons Attribution-Noncommercial-Noderivatives 4.0 license). + +## Typst compilation infrastructure + +This repository contains a sophisticated system for reproducibly compiling +Typst documents using Nix, the purely functional package manager. Typst is a +modern typesetting system aiming to replace the venerable $\latex$ system. + +Within the [2024 directory](./2024), an ongoing experiment is taking place to +create a monorepo organization structure for a large amount of Typst documents. +Some custom Nix infrastructure has been created to provide a similar package +interface to the familiar `nixpkgs` package repository. Instead of building +programs, however, it builds documents. Review [the flake](./2024/flake.nix) +for more information. + +You can test this local compilation yourself very easily! Simply run: + +```sh +nix build 'git+https://code.youwen.dev/youwen5/alexandria?dir=2024#digression-linear-algebra' +``` + +This will create a `result` that points to the compiled PDF in the Nix store. +Currently, the file is not marked as a PDF with a `.pdf` file extension, but +one should be able to easily `cp` the file from the Nix store into another +directory with a proper file name. Work is ongoing to make this as smooth as +possible. + +## Goal of the experiment + +The end goal is to produce an easy-to-use infrastructure for creating personal +repositories of Typst documents. LaTeX documents could feasibly be supported as +well in the repository with some refactoring, but this is not a priority as the +I am not currently using LaTeX. + +All of the work is sectioned into a `2024` directory for two reasons. + +Firstly, since all of the documents in the repository depend on the `nixpkgs` +and `Typix` specified in the central `flake.nix`, breaking changes may require +refactoring and maintenance of old documents. This is how `nixpkgs` works, but +these repositories host _documents_, not software. Thus, I have opted to +organize the tree in such way that each year should be its own standalone +repository. This means that a year's worth of documents can be frozen in time +at the end to ensure that all of the existing documents will be able to +reproducible compile in the future without any maintenance, as the `nixpkgs` +and `typst` versions will be frozen in time. + +Secondly, this will encourage further development each year to incrementally +improve the infrastructure. + +Eventually, if the experiment is successful, I may decide to create a +standardized library or repository template for people to use.