From 6861d4fca3cc073c48851b95f4aa767762fb4d49 Mon Sep 17 00:00:00 2001 From: Mark Date: Wed, 12 Feb 2025 17:30:23 -0800 Subject: [PATCH] README edits --- README.md | 61 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 2b28065..4bd0528 100644 --- a/README.md +++ b/README.md @@ -7,46 +7,64 @@ [Typst.app]: https://typst.app [vscode]: https://code.visualstudio.com [vscodium]: https://vscodium.com +[homebrew]: https://brew.sh # Mark's Handout Library + This is a collection of math circle handouts that I (and many others) have written. \ They are used regularly at the [ORMC]. For more information, visit [betalupi.com/handouts]. \ The latest version of each handout is available at that page. - ## License + Unless otherwise stated, all documents in this repository are licensed under [CC BY-NC-SA 4.0]. \ Each document has its own authors. See `meta.toml` in each project directory for details. By submitting or editing a handout in this repository, you agree to release it under this license. - - - ## 🛠️ Contributing + If you want to use one of these handouts for a class, see [`betalupi.com/handouts`](https://betalupi.com/handouts). \ You only need to read this section if you want to edit these handouts. -Use git to clone this repository, then open the root folder in [vscode] or [vscodium]. \ -We use the [latex-workshop] and [tinymist] extensions to write these handouts, install them before continuing. \ -[`./vscode/settings.json`](./vscode/settings.json) will automatically configure them to work with this repository. - - All handouts are in [`./src`](./src) \ - Every handout is stored in its own directory, even if it only consists of one file. \ - Handouts are organized by group (see [betalupi.com/handouts] for details). +### Setup - - Packages are stored in [`./lib`](./lib) \ - You shouldn't need to modify any library files, but you may want to read them to see how they work. \ +Use git to clone this repository, then open the root folder in [vscode] or [vscodium]. - - [`./tools`](./tools) contains build scripts, [`./.github`](./.github) configures automation. \ - You can ignore everything in these directories. +We use the [latex-workshop] and [tinymist] extensions. Install them before continuing. +[`./vscode/settings.json`](./vscode/settings.json) will automatically configure them to work with this repository. \ +You may need to install texlive and typst: + +- If you use Linux, you'll figure it out. +- On macos, use [homebrew]: \ + `brew install texlive typst typstyle` +- On Windows, I don't know. I may write instructions later. + +### Editing + +This repository is organized as follows: + +- All handouts are in [`./src`](./src). \ + Every handout is stored in its own directory, even if it only consists of one file. \ + Handouts are organized by group (see [betalupi.com/handouts] for details). + +- Packages are stored in [`./lib`](./lib) \ + You shouldn't need to modify any library files, but you may want to read them to see how they work. + +- [`./tools`](./tools) contains build scripts, [`./.github`](./.github) configures automation. \ + You can ignore everything in these directories. + +All handouts in this repository are based on `ormc_handout.cls` or `handout@0.1.0`. + +- If you're using Typst (preferred), read [`docs-typst.md`](./docs-typst.md) +- If you're still using LaTeX, read [`docs-latex.md`](./docs-latex.md). -All handouts in this repository are based on `ormc_handout.cls` or `handout@0.1.0`. \ -If you're using LaTeX, read [`docs-latex.md`](./docs-latex.md). \ -If you're using Typst (preferred), read [`docs-typst.md`](./docs-typst.md) ### Metadata + Every handout directory should contain a file called `meta.toml` with the following contents: + ```toml # This is a sample `meta.toml`. # A copy of this file should exist in every handout directory. @@ -69,12 +87,13 @@ handout = true solutions = true ``` - ## 💾 Out-of-band compilation + If you want to compile these handouts _without_ this repository (e.g, on [Overleaf] or [Typst.app]), do the following: \ _(I do not recommend this. The default toolchain makes it easier to share improvements to these handouts.)_ ### For LaTeX: + 1. Get the handout's directory (i.e, download the whole repo as a zip and extract the folder you want.) 2. Download [`./resources/ormc_handout.cls`](./resources/ormc_handout.cls) 3. Put this `ormc_handout.cls` in the same directory as the handout. @@ -95,17 +114,15 @@ with ... ]{ormc_handout} ``` + 5. Make a new overleaf project with the resulting directory. 6. **Do not use pdflatex**, it misbehaves with `ormc_handout`. Tell Overleaf to use XeLaTeX. - ### For Typst: + Out-of-band typst compilation isn't supported. Clone the repository and use vscode. \ This is because typst can't import packages from a relative path. If you _really_ want it, standalone typst compilation _is_ possible. \ Follow the LaTeX instructions, but fix `handout@0.1.0` instead of `ormc_handout`. \ You'll figure it out. - - -