Add README

.vscode/settings.json

@@ -1,5 +1,6 @@
 {
 	"latex-workshop.latex.recipe.default": "latexmk (xelatex)",
 	"tinymist.formatterPrintWidth": 80,
-	"tinymist.typstExtraArgs": ["--package-path=./lib/typst"]
+	"tinymist.typstExtraArgs": ["--package-path=./lib/typst"],
+	"tinymist.formatterMode": "typstyle"
 }

README.md

@@ -0,0 +1,111 @@
+[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://static.betalupi.com/ormc
+[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
+
+# 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).
+
+ - 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 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.
+# 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/ormc_handout.cls`](./resources/ormc_handout.cls)
+3. Put this `ormc_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/ormc_handout}
+```
+
+with
+
+```latex
+\documentclass[
+	...
+]{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.
+
+
+

docs-latex.md

@@ -0,0 +1,85 @@
+# LaTeX documentation
+
+All LaTeX handouts are based on [`ormc_handout.cls`](./lib/tex/ormc_handout.cls). \
+This class is based on `article.cls`, and should work with most LaTeX packages.
+
+The best way to start a new document is to make a copy of an existing one.
+- [Advanced/Cryptography](./src/Advanced/Cryptography) is a good example of a simple handout.
+- [Advanced/DFAs](./src/Advanced/DFAs) is a good example of a handout with graphs.
+- [Advanced/Geometric Optimization](./src/Advanced/Geometric%20Optimization) is a good example of a handout with geometry.
+
+
+## Notes
+- Compile your handouts with XeLaTeX. \
+  `pdflatex` is known to misbehave with `ormc_handout.cls`. \
+  This will happen by default if you use vscode. \
+  If you use Overleaf, you'll have to configure it manually (see document settings).
+
+## Document Options
+
+Document options are passed to `\documentclass`, as follows:
+```latex
+\documentclass[
+	% Show solutions is `solutions` is provided,
+	% hide them if `nosolutions` is provided.
+	%
+	% You should set only ONE of these flags at a time.
+	% Solutions are shown by default.
+	% All handouts are stored with `solutions` enabled.
+	solutions,
+	nosolutions,
+
+	% Enable this option if you need more space on the handout's first page.
+	% We use a long warning by default.
+	shortwarning,
+
+	% If present, hide page numbers.
+	% This should only be used for single-page handouts
+	% (e.g, warm-ups)
+	nopagenumber
+]{ormc_handout}
+```
+
+Use `geometry` to change margins and page dimensions. US letter is the default.
+
+
+## Utilities
+- `\say{text}`: Puts text in quotes, handling details like period spacing. Courtesy of `dirtytalk`.
+- `\note[Type]{text}`: Makes a note.
+- `\hint{text}`: Shorthand for `\note[Hint]{text}`
+
+## Sections
+
+The usual LaTeX title-customization techniques *WILL NOT WORK* with this class. \
+Don't even try to load `titlesec`.
+
+`ormc_handout.cls` supports two levels of sections:
+- `\section`, for large parts of the handout
+- `\definition`, `\theorem`, `\proposition`, `\example`, `\remark`, `\problem`, and `\problempart`
+
+All these macros have the following syntax: `\problem{title}<label>`
+- `title` is the problem's title, and may be empty.
+- `label` is the problem's label. This is optional. \
+  If a label is provided, this section may be referenced with `\ref{label}`.
+
+Examples:
+- `\problem{}`
+- `\problem{Bonus}`
+- `\problem{}<gcd>`, which may be referenced with `\ref{gcd}`
+
+Do **not** use `\begin{problem} ... \end{problem}`. \
+Sections are macros, not environments.
+
+## Environments:
+
+- `\begin{solution}`: A fancy red for solutions to problems. \
+	This is hidden if the `nosolutions` is provided.
+- `\begin{instrutornote}`: A fancy blue box for instructor notes. \
+	This is hidden if the `nosolutions` is provided.
+- `\begin{examplesolution}`: A fancy gray for sample solutions. \
+	This is never hidden.
+
+All the above environments break across pages and may safely be nested.
+
+Each of these environments also provides the `\linehack` macro, which draws a line across the box. \
+This is useful for, say, solutions to multipart problems.

docs-typst.md

@@ -0,0 +1,94 @@
+# Typst documentation
+
+See [typst.app/docs](https://typst.app/docs) for typst's documentation. \
+All typst handouts are based on [`handout@0.1.0`](./lib/typst/local/handout/0.1.0).
+
+The best way to start a new document is to make a copy of an existing one.
+- [Advanced/Tropical Polynomials](./src/Advanced/Tropical%20Polynomials) is a good place to start.
+- [Warm-Ups/Painting](./src/Warm-Ups/Painting) is a good example of tikz-like pictures.
+
+
+## Notes
+- Typst's equivalent of tikz is cetz ([homepage](https://cetz-package.github.io), [docs](https://cetz-package.github.io/docs/api))
+- Typst handouts are always compiled with solutions. \
+  Handouts without solutions are automatically compiled and published at [betalupi.com/handouts](https://static.betalupi.com/ormc). \
+  If you'd like to compile a student handout manually, run the following command in a handout directory:
+```bash
+typst compile main.typ --package-path ../../../lib/typst --input show_solutions=false
+```
+Where `package_path` is a relative path to [./lib/typst](./lib/typst).
+
+## Document Options
+
+All typst handouts start with the following:
+```typst
+#show: handout.with(
+  // Should match `meta.toml`
+  title: [handout title],
+
+  // Authors
+  by: "Mark",
+
+  // Subtitle (optional)
+  subtitle: "Based on a handout by Bryant Mathews",
+
+  // Group (optional)
+  group: "Advanced 2",
+)
+```
+
+## Notable commands
+- `#v(1fr)`: Like LaTeX's `\vfill`. Creates whitespace that grows automatically. \
+  `fr` means "fraction". `#v(2fr)` will fill twice as much space as `#v(1fr)` on the same page.
+
+## Utilities
+- `#note([content], type: "Note type")`: Makes a note. `type` is optional.
+- `#hint([content])`: Shorthand for `#note([content], type: "Hint")`
+- `#solution([content])`: A pretty box for solutions. Hidden in student handouts.
+- `#examplesolution([content])`: Like `#solution()`, but is never hidden.
+- `#if_solutions([content])`: Shows content only if we are showing solutions.
+- `#if_no_solutions([content])`: Shows content only if we **aren't** showing solutions.
+
+## Sections
+High-level sections are denoted with `=`. \
+Subsections start with `==`, subsubsections with `===`, and so on. \
+**`handout@0.1.0` is only designed to use `=`, subsections might be ugly.**
+
+
+`handout@0.1.0` also provides the following commands:
+- `problem`
+- `definition`
+- `theorem`
+- `example`
+- `remark`
+
+These all have the same syntax: `#problem("title", label: "label")`
+- `title` is the problem's title, and may be omitted.
+- `label` is the problem's label. This is optional. \
+  If a label is provided, this problem can be referenced with `@label`
+
+**Examples:**
+- `#problem()`
+- `#problem("Bonus")`
+- `#problem(label: "gcd")`, which may be referenced with `@gcd`
+
+### Complete example:
+
+```typst
+// Import definition(), problem(), etc.
+// Must be at the top of each file.
+#import "@local/handout:0.1.0": *
+
+// Make a section called "Tropical Cubic Polynomials"
+= Tropical Cubic Polynomials
+
+// Make a problem with a label
+#problem(label: "imaproblem")
+Consider the polynomial $f(x) = x^3 + 1x^2 + 3x + 6$.
+- sketch a graph of this polynomial
+
+// Make an untitled problem that references `problem`.
+#problem()
+Recall @imaproblem.
+- use this graph to find the roots of $f$
+```

lib/tex/ormc_handout.cls

@@ -58,7 +58,7 @@
 \ExecuteOptions{
 	10pt,
 	solutions,
-	multinumbering,
+	singlenumbering,
 	pagenumber,
 	longwarning,
 	yeswarning