docs-latex draft

.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,103 @@
+[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
+
+# 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.
+
+
+
+
+
+
+## 🛠️ 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](https://code.visualstudio.com). \
+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:
+
+### 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.
+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
+TODO
+
+
+

docs-latex.md

@@ -0,0 +1,102 @@
+- comments package breaks when not using xelatex
+- Install latex-workshop
+
+# 📜 Class Documentation
+
+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.
+
+
+
+## 🎏 Arguments
+
+These are passed to `\documentclass`, as follows:
+```latex
+% Documentclass argument example
+\documentclass[
+	nosolutions,
+	shortwarning
+]{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.
+
+
+
+
+## 🪖 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:**
+
+- `\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}`
+
+
+
+### **Sectioning:**
+
+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.
+
+
+
+### **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. \
+	This is never hidden.
+
+All the above environments break across pages and may be safely 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.