Cleanup and documentation

README.md

@@ -1,8 +1,11 @@
 # ORMC Handouts
 
-This repository contains all the handouts I've written for the [ORMC](https://circles.math.ucla.edu/circles/).
+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://nc.betalupi.com/s/ormc-handouts).
 
-If you are not affiliated with the ORMC, ask for permission before using these.
+**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.
 
 
 
@@ -16,19 +19,15 @@ Grade levels are estimates.
 
 
 
-## Getting these Handouts
+## Building these Handouts
 
-If you don't want to compile these yourself, I've configured CI that puts the latest pdfs [here](https://nc.betalupi.com/s/ormc-handouts).
+Automatic builds are [here](https://nc.betalupi.com/s/ormc-handouts), if you just want the PDFs.
 
-**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!
-
-
-
-## Building them Yourself
-
-Most handouts use a custom document class. If you move any files out of this repository, you'll need to change a few things for the handout to compile:
- 1. Download [`./resources/ormc_handout.cls`](./resources/ormc_handout.cls).
- 2. Put it in the same directory as the handout.
+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
@@ -47,4 +46,107 @@ Most handouts use a custom document class. If you move any files out of this rep
 	]{ormc_handout}
 	```
 
-I build these handouts with LuaLaTeX. If you have issues building them, try changing your engine.
+These documents should work with any LaTeX engine. \
+However, try changing your engine to LuaLaTeX if something breaks.
+
+
+
+
+---------------------------------------------------------------------------
+
+
+# `ormc_handout` Documentation
+
+This class is based on `article.cls`, and should work with most packages.\
+If something breaks, tell me so I may try to fix it.
+
+
+
+## Arguments
+
+These are passed to `\documentclass`, as follows:
+```latex
+\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 seperate 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 of the above break across pages and may be safely nested.
+They also define `\linehack`, which draws a line across the box.\
+Use `\linehack` replaces `tcolorbox` sections. `tcolorbox` only lets you have two, while `\linehack` gives you as many as you want.