handouts/README.md

# ORMC Handouts

This repository contains all the handouts I've written for the [ORMC](https://circles.math.ucla.edu/circles/). \
You can find the latest PDFs [here](https://static.betalupi.com/ormc).

**For my students:** Handouts will appear here a few days before class. Please don't look at them (or their solutions) beforehand, that spoils all the fun!

**For everyone else:** If you are not affiliated with the ORMC, ask for permission before using these.



## 📦 Contents

Handouts are sorted by the class they're for:
 - [`./Intermediate`](./Intermediate/): Grades 5 - 9
 - [`./Advanced`](./Advanced): Grades 9 - 12

Grade levels are estimates.



## 🛠️ Building these Handouts

Automatic builds are [here](https://static.betalupi.com/ormc), if you just want the PDFs.

If you want to edit these files, you'll need to download a custom document class. \
To compile one handout, do the following:
 1. Download the handout's directory (i.e, download the whole repo as a zip and extract the folder you want.)
 1. Download [`./resources/ormc_handout.cls`](./resources/ormc_handout.cls)
 2. Put this class in the same directory as the handout.
 3. Fix the include path at the top of the handout.

	Usually, you'll need to replace

	```latex
	\documentclass[
		...
	]{../../../lib/tex/ormc_handout}
	```

	with

	```latex
	\documentclass[
		...
	]{ormc_handout}
	```

These documents should work with any LaTeX engine. \
However, try changing your engine to LuaLaTeX if something breaks.




---------------------------------------------------------------------------


# 📜 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.