Added README and docs

README.md

@@ -5,6 +5,8 @@
 [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. \
@@ -18,7 +20,7 @@ The latest version of each handout is available at that page.
 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.
 
 
 
@@ -27,7 +29,7 @@ Each document has its own authors. See `meta.toml` in each project directory for
 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](https://code.visualstudio.com). \
+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) \
@@ -68,13 +70,14 @@ 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:
+## 💾 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 file in the same directory as the handout.
+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
@@ -96,8 +99,13 @@ with
 6. **Do not use pdflatex**, it misbehaves with `ormc_handout`. Tell Overleaf to use XeLaTeX.
 
 
-### For Typst
-TODO
+### 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

@@ -1,102 +1,85 @@
-- comments package breaks when not using xelatex
-- Install latex-workshop
+# LaTeX documentation
 
-# 📜 Class 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 class `ormc_handout` is based on `article.cls`, and should work with most LaTeX packages. It has everything you need and nothing you don't; it looks pretty and it is optimized for greyscale printing.
-
-If you find something broken, please tell me so I may try to fix it.
+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).
 
-## 🎏 Arguments
+## Document Options
 
-These are passed to `\documentclass`, as follows:
+Document options are passed to `\documentclass`, as follows:
 ```latex
-% Documentclass argument example
 \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,
-	shortwarning
+
+	% 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}
 ```
 
-- `10pt`, `11pt`, `12pt`:\
-	Default: `10pt`. Sets font size.
-
-- `pagenumber`, `nopagenumber`:\
-	Default: `pagenumber`. Shows or hides page numbers.
-
-- `solutions`, `nosolutions`:\
-	Default: `solutions`\
-	If `nosolutions` is passed, `solution` and `instructornote` environments are hidden.
-
-- `showwarning`, `hidewarning`:\
-	Default: `showwarning`. Shows or hides instructor handout warning.
-
-- `shortwarning`, `longwarning`:\
-	Default: `longwarning`. Sets instructor handout warning type.
-
-- `multinumbering`, `singlenumbering`:\
-	Default: `multinumbering`\
-	How problems, theorems, etc should be numbered. If `mulitnumbering` is passed, problems, theorems, etc will be numbered independently. If `singlenumbering` is passed, one global counter will be used. (I think `singlenumering` is better, it makes the handout easier to navigate.)
-
-Use `geometry` to change page lengths. Letter paper is the default.
+Use `geometry` to change margins and page dimensions. US letter is the default.
 
 
-
-
-## 🪖 Commands & More:
-`ormc_handout` automatically includes `tcolorbox`, `xcolor`, `tikz`, `amsmath`, `amssymb`. \
-It also includes a few other packages that are used internally and shouldn't have an effect on most workflows.
-
-
-
-### **Basics:**
-
+## Utilities
 - `\say{text}`: Puts text in quotes, handling details like period spacing. Courtesy of `dirtytalk`.
-- `\tab`: Typewriter-style tabs every `1cm`. Courtesy of `tabto`.
-- `\maketitle`: Makes a title. This is never placed on a separate page.
-  - Set title data with the following commands:\
-	`\title{text}`, `\subtitle{text}`, `\uptitlel{text}`, `\uptitler{text}`\
-	`\uptitlel` and `\uptitler` are optional, but usually come together.
 - `\note[Type]{text}`: Makes a note.
 - `\hint{text}`: Shorthand for `\note[Hint]{text}`
 
+## Sections
 
-
-### **Sectioning:**
-
-The usual LaTeX title-customization techniques *WILL NOT WORK* with this class.\
+The usual LaTeX title-customization techniques *WILL NOT WORK* with this class. \
 Don't even try to load `titlesec`.
 
-- `\section{title}<label>`: Creates a section with an optional label.\
-	You do not need to include the angle brackets.\
-	If you do, you can reference this section with `\ref{label}`.
-- `\definition{title}<label>`: Makes a definition. Works just like `\section`.
-- `\proposition{title}<label>`: Makes a proposition. Works just like `\section`.
-- `\theorem{title}<label>`: Makes a theorem. Works just like `\section`.
-- `\example{title}<label>`: Makes an example. Works just like `\section`.
-- `\problem{title}<label>`: Makes a problem. Works just like `\section`.
-- `\problempart{title}<label>`: Makes a problem part. Works just like `\section`.\
-	As the name implies, this command should only be used to make subparts of `\problems`.\
-	This command may be removed in the future.
-- `\generic{title}<label>`: Makes a generic section. Works just like `\section`.\
-	Avoid using this if you can. \
-	Generic sections have no counter, and are usually used to get text to look the same as a section title. \
-	This command may be removed in the future.
+`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 referened with `\ref{label}`.
 
+Examples:
+- `\problem{}`
+- `\problem{Bonus}`
+- `\problem{}<gcd>`, which may be referenced with `\ref{gcd}`
 
-### **Environments:**
+Do **not** use `\begin{problem} ... \end{problem}`. \
+Sections are macros, not environments.
 
-- `\begin{solution}`: A fancy `tcolorbox` for solutions to problems. \
-	This is hidden if the `nosolutions` flag is passed.
-- `\begin{instrutornote}`: A fancy `tcolorbox` for instructor notes. \
-	This is hidden if the `nosolutions` flag is passed.
-- `\begin{examplesolution}`: A fancy `tcolorbox` for sample solutions. \
+## 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 be safely nested.
+All the above environments break across pages and may safely be nested.
 
-Each also has a special command `\linehack`, which draws a line across the box.\
-Use `\linehack` instead of `tcolorbox` sections. `tcolorbox` only lets you have two, while `\linehack` gives you as many as you want.
+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