update readme

2024/documents/README.md

@@ -0,0 +1,37 @@
+# alexandria, the document repository
+
+This is where documents and their derivations are stored. The source code of
+the document and its corresponding `package.nix` are placed in the same place.
+
+There are two ways to organize documents. You can directly place the document
+in [by-name](./by-name/), suitable for documents not assorted with a
+particular course and various miscellany.
+
+For documents related to specific courses, it is preferable to create a
+directory for that course in [by-course](./by-course/), and then nesting the
+document directory within the course directory. This will create a nested
+structure for the packages as well.
+
+For example, the following path:
+
+```
+by-name/my-document
+```
+
+will result in a package set containing `my-document`.
+
+The path
+
+```
+by-course/phil-1/paper-1
+```
+
+results in a nested package set containing `phil-1.paper-1`. That means that
+you can build that document with the command
+
+```sh
+nix build .#phil-1.paper-1
+```
+
+It's evident that this organization structure could be useful for organizing by
+some topics other than courses, so the naming may change in the future.

README.md

@@ -23,15 +23,32 @@ 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:
+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:
+
+```sh
+nix search git+https://code.youwen.dev/youwen5/alexandria?dir=2024 phil-1
+```
+
+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'
 ```
 
-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
+The builds are managed by the amazing
+[typix](https://github.com/loqusion/typix) project. It helps provide a
+hermetically sealed build environment, which means that all _dependencies_ of
+the documents are specified, including fonts, commonly forgotten due to being
+installed systemwide. Also, the build process clones down a copy of the entire
+[Typst package repository](https://github.com/typst/packages), version locked
+in [flake.lock](./2024/flake.lock). This means that packages are also
+guaranteed to be reproducible and available.
+
+Compilation creates 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.
 
@@ -45,7 +62,7 @@ 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
+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