docs: update readme
This commit is contained in:
parent
2412feb190
commit
57606c93e3
1 changed files with 13 additions and 32 deletions
45
README.md
45
README.md
|
@ -9,38 +9,44 @@ Creative Commons Attribution-Noncommercial-Noderivatives 4.0 license), with one
|
|||
exception. The Nix source code that helps provide the document compilation
|
||||
infrastructure is free and unencumbered software released into the public
|
||||
domain. This includes all of the files in `./2024/nix` as well as any files
|
||||
ending in `.nix` generally. See more details in [the source code
|
||||
README.](./2024/nix/README.md)
|
||||
ending in `.nix` generally. The contents of `./quartz` are copyright Jerry Zhao
|
||||
under the MIT License.
|
||||
|
||||
I (and the license) do not grant permission for my work being passed off as
|
||||
someone else's (perhaps for the purpose of plagiarism). Obviously this does not
|
||||
extend to the Nix source code, which is in the public domain.
|
||||
|
||||
## Quartz 4 Web Deployment
|
||||
|
||||
The markdown files in this repository are Obsidian flavored and are
|
||||
automatically compiled into the knowledge garden at
|
||||
[garden.youwen.dev](https://garden.youwen.dev). Please visit!
|
||||
|
||||
## 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
|
||||
Within the [documents](./documents), 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.
|
||||
|
||||
Since the flake in [2024] provides a package set, you can use the `nix search`
|
||||
command on it to discover documents just like `nixpkgs`. Try:
|
||||
Since the flake in documents provides a package set, you can use the `nix
|
||||
search` command on it to discover documents just like `nixpkgs`. Try:
|
||||
|
||||
```sh
|
||||
nix search "git+https://code.youwen.dev/youwen5/alexandria?dir=2024" digression
|
||||
nix search "git+https://code.youwen.dev/youwen5/alexandria?dir=documents" digression
|
||||
```
|
||||
|
||||
You can compile any document in this repository yourself very easily! Simply
|
||||
run:
|
||||
|
||||
```sh
|
||||
nix build 'git+https://code.youwen.dev/youwen5/alexandria?dir=2024#digression-linear-algebra'
|
||||
nix build 'git+https://code.youwen.dev/youwen5/alexandria?dir=documents#digression-linear-algebra'
|
||||
```
|
||||
|
||||
The builds are managed by the amazing
|
||||
|
@ -57,28 +63,3 @@ 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 `typst` 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.
|
||||
|
|
Loading…
Reference in a new issue