129 lines
4.4 KiB
Markdown
129 lines
4.4 KiB
Markdown
[tinymist]: https://marketplace.visualstudio.com/items?itemName=myriad-dreamin.tinymist
|
|
[latex-workshop]: https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop
|
|
[CC BY-NC-SA 4.0]: https://creativecommons.org/licenses/by-nc-sa/4.0
|
|
[betalupi.com/handouts]: https://betalupi.com/handouts
|
|
[ORMC]: https://circles.math.ucla.edu/circles/
|
|
[Overleaf]: https://overleaf.com
|
|
[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]. \
|
|
You only need to read this section if you want to edit these handouts.
|
|
|
|
### Setup
|
|
|
|
Use git to clone this repository, then open the root folder in [vscode] or [vscodium].
|
|
|
|
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 `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).
|
|
|
|
### 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.
|
|
# All keys are required.
|
|
|
|
[metadata]
|
|
title = "title of this handout"
|
|
|
|
|
|
[publish]
|
|
# Should we publish this handout?
|
|
# If `false`, no part of this handout is published.
|
|
handout = true
|
|
|
|
# Should we publish an "instructor's" version of this handout?
|
|
# This key has no effect if `publish.handout` is false.
|
|
#
|
|
# If `true`, publish a second version of this handout with solutions.
|
|
# Set this to `false` if solutions haven't been written.
|
|
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/handout.cls`](./resources/handout.cls)
|
|
3. Put this `handout.cls` in the same directory as the handout.
|
|
4. Fix the include path at the top of `main.tex`:
|
|
|
|
You'll need to replace
|
|
|
|
```latex
|
|
\documentclass[
|
|
...
|
|
]{../../../lib/tex/handout}
|
|
```
|
|
|
|
with
|
|
|
|
```latex
|
|
\documentclass[
|
|
...
|
|
]{handout}
|
|
```
|
|
|
|
5. Make a new overleaf project with the resulting directory.
|
|
6. **Do not use pdflatex**, it misbehaves with `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 `handout`. \
|
|
You'll figure it out.
|