Setup and Technical Details

Repository structure outline

• src: contains each semester's set of LaTeX worksheet templates
• topics: a question bank consisting of LaTeX files that are imported into worksheet templates. topics is divided into topical subdirectories, each of which is further divided into subfolders based on difficulty.
• commonheader.sty: The common header for all worksheet templates, which contains all common styling and content elements (such as the title and footers). Each worksheet template imports this file.
• scripts/latex_to_py.py: (Crudely) converts worksheet templates into Python files.
• Makefile: Used to produce all content with make.
• deps: Stores dependency files used by make to determine which files are used for each worksheet.
• make_dependency.py: Produces the dependency files used by make.
• made*: The place where all content produced by make is output.
• published: The place where all completely finalized content is stored.
• README: Provides information about the repository
• CODEOWNERS: lists the "owners" of the repository for configuring GitHub security settings
• old: ??
• synttree.sty: ??

*ignored by git

Getting Started

Clone this repository to your local machine. You will need to have LaTeX installed; some popular distributions include TeXworks and MiKTeX for Windows, and MacTeX for Mac. For our workflow to function properly, latex2pdf.exe must be in your machine's PATH variable, which should hopefully be handled automatically on installation.

Windows users will need to be able to use make. We recommend installing Git Bash and then installing make.

Mac users downloading TeXworks and MikTeX will run into problems with Error 127. To remedy this, instead download MacTeX, which will automatically install pdftex.exe to your Mac's PATH variable.

You can verify that you have correctly set up the repository by attempting to make a worksheet, as described in the next section.

Making Handouts

To make an individual worksheet, run the following command in the repository's root directory.

make mentor00

You will find the made file in the made directory.

Suffixes allow you to make different types of content:

make mentor00-meta # Makes the meta
make mentor00-sol # Makes the solutions
make mentor00-py # Makes both the Python file and the Python solutions file
make mentor00-py-sol # Makes the Python solutions file
make mentor00-py-no-sol # Makes the Python file (without solutions) only

make mentor00-pdfs # Makes all PDFs
make mentor00-all # Makes all content for the week

Multiple make targets can also be combined into a single command:

make mentor00-all mentor01-all mentor02-py

make clean will delete the made folder. This is useful if you are trying to remake a file but make is not recognizing the file as having changed.

In previous semesters, you would make multiple worksheets for a particular week by modifying these two lines at the top of the Makefile:

RELEASED = mentor00 mentor01 mentor02
SOLUTIONS = mentor00 mentor01

Then, you would run make all to build all the worksheets in the RELEASED variable and all the solutions and metas in the SOLUTIONS variable. I don't recommend using this behavior.

Troubleshooting

The most common issues relating to installation are

• incorrectly installed LaTeX (latex2pdf.exe not in PATH)
• incorrectly installed make (only on Windows)

Google is your best friend here.

The most common issues when making a worksheet are

• the presence of unescaped underscores. Underscores must either be escaped with a backslash (\_) or they must appear within a lstlisting or \lstinline environment.
• mismatched environments. Make sure that every environment you open with \begin is closed with \end, and that these statements appear in the right order.

You should look at the error message to help determine what the issue is and where it occurs. Unfortunately, the error message is sometimes of dubious assistance.

---

Major Contributors: Gabe Classon